Deploy Static Sites with Git and GitHub Pages Step by Step

Want to launch a website without paying for hosting or wrestling with servers?
This step-by-step guide shows how to deploy a static site using Git and GitHub Pages.
You’ll set up a repo, push your files, enable Pages, and get a live URL in minutes.
Along the way you’ll learn the exact Git commands, what to do when builds fail, and how to add a custom domain.
By the end you’ll have a repeatable workflow that updates your site every time you push a commit.

Understanding the Goal of Deploying a Static Site with Git and GitHub Pages

GitHub Pages is a free hosting service that turns a Git repository into a live website. It’s built for static sites, meaning websites made only of HTML, CSS, and JavaScript files that don’t need server-side code or a database. When you push changes to your repository, GitHub Pages automatically publishes your site at a URL you can share. People like it because it combines version control, free hosting, and simple deployment into one workflow. If you’ve ever wanted to launch a portfolio, documentation site, or simple project page without paying for hosting or managing a server, this is what you’re building toward.

The basic process works like this: you create a repository on GitHub, add your website files, enable GitHub Pages in the repository settings, and wait a few minutes for the site to go live. Every time you push a new commit, the site updates automatically. The URL GitHub gives you follows the format username.github.io/repo-name (or just username.github.io if you use a special naming convention). You can also attach a custom domain later if you want a branded address.

Here’s the short version of the full deployment process:

1. Create a new repository on GitHub and choose a public visibility setting.
2. Add an index.html file at the root of your repository. This is the page GitHub Pages will serve by default.
3. Use Git commands to initialize your local project, commit your files, and push everything to the remote repository on GitHub.
4. Go to your repository Settings → Pages and select the branch and folder you want to publish from.
5. Wait a few minutes (typically under 10) for GitHub to build and publish your site.
6. Visit the live URL displayed in the Pages settings to confirm your site is online.

Why Static Site Deployment Issues Occur When Using Git and GitHub Pages

Most deployment problems happen because the repository is missing a file GitHub Pages expects, or because the settings don’t match where your files actually live. GitHub Pages looks for a file named index.html in a specific branch and folder. If that file isn’t there, the site won’t load. You’ll see a 404 error instead. Another common issue is choosing the wrong branch or folder in the Pages settings. If you tell GitHub to publish from the main branch but your HTML is actually in a gh-pages branch, nothing will show up.

DNS configuration for custom domains is another frequent source of confusion. When you add a custom domain, you also need to update DNS records at your domain registrar. Those changes can take anywhere from 5 minutes to 48 hours to fully propagate across the internet. Until DNS is live, your custom domain won’t resolve to the GitHub Pages server. Sometimes GitHub Pages also tries to process your files with Jekyll (a static site generator built into GitHub), and if your file structure conflicts with Jekyll’s expectations, the build will fail. You can bypass Jekyll entirely by adding a .nojekyll file to your repository.

Common causes of failed deployments include:

• Missing or misnamed index.html file at the repository root (or chosen folder).
• Incorrect branch or folder selected in the GitHub Pages settings (e.g., Pages set to main/root but files are in gh-pages).
• DNS records not configured correctly or still propagating after a custom domain is added.
• Jekyll build errors that block publishing (often resolved by adding a .nojekyll file or fixing Jekyll config issues).

Preparing Your Environment for a Git and GitHub Pages Deployment

Before you can deploy a static site, you need a few tools and accounts set up. First, create a free GitHub account if you don’t have one. This is where your repository will live and where GitHub Pages will host your site. Next, install Git on your computer. Git is the version control software that tracks changes to your files and sends them to GitHub. You can download it from the official Git website or install it through a package manager on macOS or Linux. On Windows, run the installer and accept all the default settings. On macOS, open Terminal and install Git using Homebrew. On Ubuntu or Debian-based Linux, install it using your distribution’s package manager.

After installing Git, verify it’s working by opening your terminal or command prompt and typing git –version. You should see a version number. Once Git is installed, configure it with your name and email so your commits are labeled correctly. Run these commands in your terminal, replacing the placeholders with your actual information. Git will now attach your identity to every commit you make.

You’ll also need a static site project to deploy. This can be a single HTML file or a full project with CSS, JavaScript, and images. The only hard requirement is that you have a file named index.html at the root of your project folder. This is the page GitHub Pages will serve when someone visits your site.

The complete list of prerequisites includes:

• A GitHub account (sign up at github.com if needed).
• Git installed locally and verified with git –version.
• Git configured with your username and email using git config commands.
• A static site project with at least one index.html file.
• A code editor like VS Code (optional but helpful for editing files locally).

Creating and Structuring the Repository for GitHub Pages Deployment

GitHub Pages can host two types of sites: user or organization sites, and project sites. User sites are published from a repository named exactly username.github.io (replace “username” with your GitHub username). When you use that naming pattern, GitHub automatically publishes the site at username.github.io without a repo name in the URL. Project sites use any other repository name and are published at username.github.io/repo-name. If you want a single portfolio or landing page for your GitHub profile, use the username.github.io naming convention. If you’re deploying a specific project or multiple sites, use a normal repository name for each one.

To create a repository, log in to GitHub, click the New button (usually in the repositories tab or from the plus icon in the top-right corner), and fill out the form. Enter your repository name, add an optional description, and choose Public visibility. GitHub Pages requires a public repository on the free plan. You can leave the “Initialize this repository with” options unchecked if you plan to push an existing local project. If you’re starting from scratch, you can check “Add a README file” to get a starting point, but you’ll still need to add index.html separately.

Here’s how to set up your repository step by step:

1. Log in to GitHub and click New (or navigate to github.com/new).
2. Enter a repository name. Use username.github.io for a user site or any name for a project site.
3. Add a description (optional) that explains what the site is for.
4. Choose Public visibility, required for GitHub Pages on the free plan.
5. Skip the “Initialize this repository with” checkboxes if you already have local files to push.
6. Click Create repository and copy the repository URL shown on the next page (you’ll need this to link your local Git project).

Using Git Commands to Initialize, Commit, and Push Your Static Website

Git organizes your project into commits, snapshots of your files at a specific point in time. To start tracking your project with Git, open your project folder in your terminal or code editor’s integrated terminal and run git init. This creates a hidden .git folder that stores all the version control data. Next, you’ll stage your files with git add, commit them with a message describing the changes, and push everything to the remote repository on GitHub.

Here’s the full command sequence with examples (replace placeholders like “username” and “repo-name” with your actual values):

1. git init — Initialize a new Git repository in the current folder (creates .git folder and sets up the main branch).
2. git add . — Stage all files in the project for the next commit (the dot means “everything in this folder”).
3. git commit -m “Initial commit” — Create a commit with a message; this saves the current state of all staged files.
4. git branch -M main — Rename the default branch to “main” (older Git versions used “master”).
5. git remote add origin https://github.com/username/repo-name.git — Link your local repository to the remote GitHub repository (use the URL you copied earlier).
6. git push -u origin main — Push your local commits to the remote repository on the main branch; the -u flag sets main as the default upstream branch.
7. git status — Check the current state of your repository and see which files are tracked, staged, or modified.

When you write commit messages, make them short and specific. Instead of “update files,” write “Add navigation menu to index.html” or “Fix broken image link in about page.” Clear messages help you understand what changed when you look back at your commit history. Also, use lowercase filenames with no spaces. “about.html” instead of “About Page.html” avoids issues with case-sensitive servers and URL encoding.

Enabling GitHub Pages and Selecting the Correct Branch for Deployment

Once your files are pushed to GitHub, you need to tell GitHub Pages where to find your website. Open your repository on GitHub, click Settings in the top menu, then scroll down to the Pages section in the left sidebar. Under Source, you’ll see options for which branch and folder to publish from. The most common setup is to publish from the main branch and the root folder. Select main from the branch dropdown, leave the folder set to / (root), and click Save. GitHub will display a message saying “Your site is ready to be published at…” followed by your URL.

The URL format depends on your repository name. If you used username.github.io, your site will be at username.github.io. If you used a project name like “portfolio,” your site will be at username.github.io/portfolio. After you save the Pages settings, GitHub starts building your site. This usually takes less than a minute, but can take up to 10 minutes for larger projects or during high-traffic periods. Refresh the Settings → Pages page to see the current status. When the build is complete, the message will change to “Your site is published at…” and the URL will be clickable.

You have three main options for which branch and folder to publish from. Each has a different use case:

Configuring a Custom Domain and DNS for Your GitHub Pages Site

If you want to use your own domain instead of the default username.github.io URL, you’ll need to configure DNS records at your domain registrar and add a CNAME file to your repository. The CNAME file tells GitHub what custom domain to expect. Create a new file at the root of your repository named CNAME (all caps, no file extension) and put your domain on a single line, for example, example.com or www.example.com. Commit and push the file to your repository.

Next, log in to your domain registrar (the service where you bought your domain) and add DNS records. For an apex domain (example.com with no “www”), create four A records that point to GitHub’s IP addresses: 185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153. For a subdomain like www.example.com, create a CNAME record that points to username.github.io (replace “username” with your GitHub username). Some registrars also support ALIAS or ANAME records for apex domains, which can point to username.github.io instead of using A records. Check your registrar’s documentation to see what’s supported.

Here’s the step-by-step DNS setup process:

1. Create a CNAME file in your repository root containing your custom domain (e.g., example.com) and push it to GitHub.
2. Go to Settings → Pages on GitHub and enter your custom domain in the “Custom domain” field, then click Save.
3. Log in to your domain registrar’s DNS management panel.
4. For apex domains, add four A records pointing to 185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153.
5. For subdomains, add a CNAME record pointing to username.github.io.

DNS changes can take anywhere from 5 minutes to 48 hours to propagate worldwide, though most updates are visible within an hour. You can check propagation status using a tool like dig or nslookup from your terminal. Once DNS is live, GitHub will automatically provision a free HTTPS certificate using Let’s Encrypt. This usually happens within a few minutes to a couple of hours after DNS resolves correctly. Once the certificate is active, you can check the “Enforce HTTPS” box in Settings → Pages to force all visitors to use the secure version of your site.

Troubleshooting Static Site Deployment Issues on GitHub Pages

When your site doesn’t load or shows a 404 error, the first thing to check is whether index.html exists in the exact branch and folder you selected in the Pages settings. Go to your repository on GitHub, switch to the branch you chose (main or gh-pages), and confirm that index.html is visible in the file list. If it’s missing or in a subfolder, GitHub Pages won’t find it. The second most common issue is a mismatch between the Pages settings and your actual file structure. Open Settings → Pages and verify that the branch and folder match where your index.html lives.

If the site was working and suddenly broke after a recent commit, check your commit history to see what changed. A renamed or deleted file, a broken link, or a typo in index.html can all cause problems. You can roll back to a previous working commit by using git revert or git reset if you need to undo changes. If you see a “Page build failed” error in the Pages settings, GitHub likely tried to process your files with Jekyll and ran into a problem. Add a .nojekyll file (empty, no extension) to the root of your repository and push it. This tells GitHub to skip Jekyll processing entirely.

Here are the most common issues and their fixes:

• 404 Not Found: index.html is missing from the chosen branch/folder or Pages is set to the wrong branch; confirm index.html is at the repository root (or /docs if configured) and re-check Settings → Pages Source.
• Page build failed: Jekyll build error or configuration conflict; add a .nojekyll file to bypass Jekyll, or review the build log if available.
• Custom domain not resolving: DNS records are incorrect or still propagating; verify A or CNAME records at your registrar and wait up to 48 hours for propagation.
• HTTPS not active: certificate provisioning delayed or DNS not yet correct; wait a few hours after DNS is live, then check Settings → Pages for the “Enforce HTTPS” checkbox.
• Site shows old content after a new commit: browser caching; hard-refresh your browser (Ctrl+Shift+R or Cmd+Shift+R) or test in an incognito/private window.
• Files with underscores or special characters missing: Jekyll ignores certain filenames by default; add .nojekyll to disable Jekyll or rename files to avoid underscores at the start.

Preventing Future Deployment Problems for GitHub Pages Sites

The best way to avoid deployment headaches is to build good Git habits and keep your project structure simple. Use clear, lowercase filenames without spaces or special characters. “about.html” and “style.css” work everywhere, but “About Page.html” and “My Styles!.css” can cause issues. Commit your changes often with meaningful messages so you can trace what happened if something breaks. Include a README.md file that explains what the site is, how to run it locally, and any special setup steps. This helps you (and anyone else) understand the project later.

Enforce HTTPS in Settings → Pages once your site is live or after you’ve configured a custom domain. This ensures visitors always use the encrypted connection. If you update CSS or JavaScript files and notice browsers still show old versions, consider adding cache-busting techniques like appending version numbers to filenames or using query strings (e.g., style.css?v=2). Test your site locally before pushing by opening index.html in a browser or using a simple local server. This catches broken links and missing files before they go live.

Five preventive habits that reduce deployment issues:

• Use lowercase filenames with no spaces, underscores at the start, or special characters; keeps URLs clean and avoids Jekyll conflicts.
• Commit regularly with clear messages that describe what changed; makes it easier to debug when something breaks.
• Keep index.html at the repository root (or in /docs if using that folder option); GitHub Pages needs it in the expected location.
• Add a .nojekyll file if your project uses files or folders Jekyll would ignore (anything starting with underscore or dot).
• Test locally before pushing by opening files in a browser or running a local server; catch errors before they reach the live site.

When to Seek Further Help or Advanced Deployment Support

Most static site deployments on GitHub Pages are straightforward, but some scenarios require more advanced tools or workflows. If your site needs to be built from source files (for example, a React app created with create-react-app or a static site generator like Eleventy or Hugo), you’ll need to run a build step before deploying. GitHub Actions can automate this by running your build commands every time you push and then deploying the output to the gh-pages branch. Setting up a GitHub Actions workflow requires creating a .github/workflows/deploy.yml file with the correct configuration, which is beyond basic Git and Pages setup.

If you’ve correctly configured DNS and waited 48 hours but your custom domain still won’t resolve, the issue might be at your registrar or with your DNS provider’s propagation systems. At that point, contact your registrar’s support team or consult their documentation. Similarly, if you need advanced features like custom redirects, server-side logic, or database integration, GitHub Pages won’t support those. It only hosts static files. You’d need to switch to a different hosting service or use a serverless backend alongside GitHub Pages.

Consider seeking advanced help or exploring CI/CD automation if you encounter these scenarios:

• Your project requires a build step (npm run build, bundling, transpiling) before deployment. Look into GitHub Actions or third-party CI tools.
• Custom domain DNS issues persist beyond 48 hours after correct configuration. Contact your domain registrar’s support team.
• You need server-side code, form handling, or database connections. GitHub Pages can’t do this; explore serverless functions or alternative hosting.
• Your site uses client-side routing (single-page apps with React Router or similar) and users get 404s on deep links. Requires custom 404.html handling or server configuration GitHub Pages doesn’t fully support.

Final Words

in the action, we mapped the whole path: set up Git, created the repo, placed index.html at the root, pushed commits, enabled Pages, and checked the live URL. We also covered common failures—wrong branch, missing file, Jekyll, and DNS.

Use the prep steps, git commands, and troubleshooting tips to keep deployments smooth. For a hands-on guide you can follow right now, use this step by step tutorial to deploy a static site using Git and GitHub Pages. You’ll see progress fast and build a repeatable workflow.

FAQ

Q: How to host or deploy a static website on GitHub Pages?

A: To host or deploy a static website on GitHub Pages, create a repo, add index.html at the root, commit and push, enable Pages (choose branch or /docs), wait a few minutes, then visit the URL.

Q: Can GitHub Pages host a website?

A: GitHub Pages can host a static website for free, serving HTML/CSS/JS from your repo; it publishes to username.github.io/repo-name and usually goes live within minutes.