GitHub Pages turns a repository into a live website with no hosting bill

GitHub Pages is a feature built into GitHub that publishes HTML, CSS, and JavaScript files directly from a repository as a live website. You point a domain name at GitHub's servers, push your code to a repository, and the site goes live. There is no monthly hosting fee, no server to manage, and no deployment step beyond a normal git push.

The process has three parts: create a repository with the right name, write or paste your HTML and CSS, and optionally connect a custom domain. Most people finish the first two steps in under an hour. The site updates automatically whenever you push new code.

Key Takeaways

  • A repository named username.github.io publishes automatically to https://username.github.io with no extra configuration needed.
  • You can write HTML and CSS by hand, use a static site generator like Jekyll, or paste a template into your repository.
  • GitHub Pages works only with static files — HTML, CSS, JavaScript, images — not with databases or server-side code.
  • Custom domains point to GitHub's servers through a CNAME file in your repository and DNS records at your domain registrar.
  • The site rebuilds and goes live within seconds of pushing code, so testing happens on your local machine before you push.

Creating the repository with the correct name

GitHub Pages looks for a repository with a specific naming pattern. If your GitHub username is janedoe, create a repository named exactly janedoe.github.io

If you create a repository with any other name, GitHub Pages still works, but the site publishes to a subdirectory instead: https://janedoe.github.io/my-portfolio rather than the root. For a personal homepage, the username.github.io pattern is simpler.

Clone the repository to your computer, or initialize a new folder as a git repository if you are starting from scratch. Either way, you now have a folder connected to GitHub where you can add files.

Writing HTML and CSS or using a template

GitHub Pages serves whatever HTML files you put in the repository. Create a file named index.html in the root folder — this is the file that loads when someone visits your site. Write your HTML by hand, paste a template from a site like HTML5 UP or Start Bootstrap, or use a static site generator.

If you write by hand, create a simple structure: an index.html file for the homepage, a style.css file in a folder called css, and an images folder for pictures. Link the CSS file in the <head> of your HTML with a relative path like <link rel="stylesheet" href="css/style.css">. Test the site on your computer by opening index.html in a browser before you push to GitHub.

Jekyll is a static site generator that many people use with GitHub Pages. It reads Markdown files and configuration and builds HTML automatically. If you choose Jekyll, GitHub Pages detects it and runs the build step for you — you push Markdown and configuration, and GitHub outputs the HTML. This is optional; plain HTML works just as well.

Pushing your code and going live

Once your files are in the repository folder, add them to git, commit, and push to GitHub.

  1. Open a terminal in your repository folder.
  2. Type git add . to stage all files.
  3. Type git commit -m "Initial commit" to create a commit message.
  4. Type git push to send the code to GitHub.

Within seconds, GitHub Pages detects the push and publishes your site. Visit https://janedoe.github.io (using your actual username) and you will see your site live. Any time you push new code, the site updates automatically.

Connecting a custom domain name

If you own a domain name, you can point it to your GitHub Pages site instead of using the github.io address. This requires two steps: a file in your repository and DNS records at your domain registrar.

First, create a file named CNAME (no extension) in the root of your repository. Inside it, write only your domain name — for example, janedoe.com — on a single line. Commit and push this file. GitHub now expects traffic to arrive at that domain.

Second, log into your domain registrar (GoDaddy, Namecheap, Google Domains, or wherever you bought the domain) and update the DNS records. Create an A record pointing to GitHub's IP addresses, or a CNAME record pointing to username.github.io. The exact steps vary by registrar, but GitHub's documentation lists the IP addresses and the process for each major provider. DNS changes take a few minutes to an hour to propagate.

Once DNS propagates, visiting your domain will load your GitHub Pages site. The site will also be available at the github.io address, but visitors usually see the custom domain in the browser.

What GitHub Pages can and cannot do

GitHub Pages publishes static files only — HTML, CSS, JavaScript, images, and documents. It does not run server-side code, databases, or backend languages like Python or PHP. If your site needs to store form submissions, authenticate users, or fetch data from a database, GitHub Pages alone is not enough.

For a personal portfolio, resume site, blog, or documentation, GitHub Pages is complete. For anything that requires a backend, you can write JavaScript that runs in the browser and calls an external API, or you can host the backend elsewhere and have GitHub Pages serve only the front end.

HTTPS is automatic — GitHub Pages serves all sites over a secure connection at no cost. Search engines index GitHub Pages sites normally, so your site will appear in search results if people look for your name or your content.

Testing locally before pushing to GitHub

The fastest way to catch mistakes is to test your site on your computer before you push. Open index.html directly in a browser to see how it looks, or use a local server to test more realistically.

If you use Jekyll, install it on your computer and run jekyll serve in your repository folder. Jekyll builds the site and serves it at http://localhost:4000. You can then visit that address in your browser and see the site as it will appear on GitHub. If you are using plain HTML, you can use Python's built-in server: run python -m http.server in your repository folder and visit http://localhost:8000.

Test on different browsers and devices before pushing. Once you push, the site is live, and any mistakes are visible to anyone who visits.

Frequently Asked Questions

Can I use a subdomain like blog.janedoe.com with GitHub Pages?

Yes. Create a CNAME file with the subdomain name, then add a CNAME record at your registrar pointing that subdomain to username.github.io. The process is the same as with a root domain, just with a different domain name in the CNAME file.

What happens if I delete the repository?

The site goes offline immediately. GitHub Pages only publishes repositories that exist. If you delete the repository by accident, you can restore it from GitHub's recycle bin within 90 days, or you can recreate it from a local backup.

Can I use a database or backend with GitHub Pages?

No. GitHub Pages serves static files only. If you need a database, you must host the backend separately — on Heroku, AWS, or another service — and have your JavaScript call it. GitHub Pages can serve the front end while the backend runs elsewhere.

How do I add a blog or multiple pages to my GitHub Pages site?

Create additional HTML files in your repository and link to them from your main page. For example, create blog.html and link it with <a href="blog.html">Blog</a>. If you use Jekyll, you can write blog posts in Markdown and Jekyll will generate the HTML automatically.

Is there a cost to use GitHub Pages?

No. GitHub Pages is free for public repositories. You do not pay for hosting, bandwidth, or SSL certificates. The only cost is your domain name if you use a custom domain, which is optional.