Skip to content
ArtHack
GitHub Pages Website Setup: Deploying Static Sites for Free
Hosting & Performance August 11, 2026

GitHub Pages Website Setup: Deploying Static Sites for Free

WHAT YOU NEED TO KNOW

A github pages website provides free, automated hosting for static files directly from a GitHub repository, making it ideal for documentation, developer portfolios, and client-side applications.

  • Free account usage limits include 100 GB of soft monthly bandwidth and a recommended repository size cap of 1 GB.
  • Deployments process automatically using GitHub Actions within 1 to 10 minutes after pushing changes to your designated branch.
  • Every site includes automatic HTTPS encryption and a free default subdomain under github.io.

Keep in mind that GitHub Pages only serves static HTML, CSS, and JavaScript files, meaning back-end languages like PHP, Python, and SQL databases are not supported.

What Is a GitHub Pages Website?

A github pages website is a static site hosting service that fetches files directly from a repository on GitHub, compiles them if necessary, and serves them to visitors. Unlike traditional web hosting that runs web servers like Apache or Nginx with database back-ends, GitHub Pages delivers static assets straight to the user browser.

This architecture makes hosting exceptionally fast and secure. According to official GitHub Docs, public repositories on free plans receive full access to GitHub Pages hosting without requiring paid hosting subscriptions. Note that software policies, plan limits, and feature availability change over time and should be re-checked on GitHub’s pricing page.

Key Features and Limitations

  • Static File Serving: Renders HTML, CSS, JavaScript, media files, and pre-built single-page applications without dynamic server code execution.
  • Custom Domain Support: Allows pointing custom Apex domains (example.com) and subdomains (sub.example.com) directly to your project.
  • Free SSL Encryption: Enforces SSL and HTTPS encryption automatically for both default and custom domains.
  • Bandwidth and File Limits: Subject to a soft bandwidth limit of 100 GB per month, a maximum file size limit of 100 MB, and a total repository cap of 1 GB.
  • No Back-End Scripts: Server-side scripting languages like PHP, Node.js runtime environments, and databases like MySQL cannot run directly on the host server.

Prerequisites for Getting Started

Before deploying your site, you need a few fundamental tools and assets prepared. Setting up these tools in advance ensures a smooth deployment process without workflow interruptions.

  • A GitHub Account: A free account registered on GitHub is required to create repositories and manage hosting settings.
  • Git Installed Locally: Utilizing the Git version control system on your computer allows you to commit and push changes directly from your terminal or code editor.
  • Website Files: An entry point file named index.html located at the root of your project directory, alongside associated CSS and JavaScript assets.
  • A Custom Domain (Optional): A domain registered with a DNS provider if you plan to replace the default username.github.io address.

How to Host Your Website on GitHub Pages (Step-by-Step)

Learning how to host on github pages involves setting up a remote repository, pushing your site assets, and specifying a deployment source. The entire workflow can be completed in minutes using either the GitHub web interface or the Git command line interface.

Step 1: Create a GitHub Repository

Log into your GitHub account and navigate to the upper right corner to create a new repository. You have two options for naming depending on the type of site you want to publish:

For a personal or organization user site, name the repository exactly <username>.github.io, where <username> represents your exact GitHub account handle in lowercase. This site will publish directly to the root URL address.

For a project site, name the repository after your project, such as portfolio or app-docs. This site will publish to <username>.github.io/<repository-name>. Ensure the repository visibility is set to Public if you are using a free GitHub account.

Step 2: Add Your HTML and Website Files

GitHub Pages looks for a default entry file named index.html, index.md, or README.md in the publishing directory. If your primary entry point is missing, visitors will receive a 404 file not found error.

Create a simple index.html file locally with the following boilerplate structure to test your deployment:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My GitHub Pages Site</title>
</head>
<body>
  <h1>Hello World!</h1>
  <p>My website is live on GitHub Pages.</p>
</body>
</html>

Push this file to your repository’s main or master branch using Git terminal commands or by dragging and dropping files directly into the GitHub web interface.

Step 3: Configure Pages Publishing Source

Once your code is pushed to GitHub, you must instruct Pages where to find your site source files.

  1. Navigate to your repository page on GitHub and click the Settings tab located in the top navigation bar.
  2. In the left sidebar menu under the “Code and automation” section, click on Pages.
  3. Under the “Build and deployment” header, set the Source dropdown menu to “Deploy from a branch”.
  4. Select your primary branch (typically main) from the branch selection dropdown, choose the root folder (/ (root)), and click Save.

Step 4: Verify and View Your Published Site

After saving your source configuration, GitHub automatically triggers a GitHub Actions workflow that compiles and deploys your static files. As documented by MDN Web Docs, deployment pipelines usually complete within 1 to 10 minutes depending on queue traffic.

Refresh the GitHub Pages settings page after a couple of minutes. A top bar banner will appear stating “Your site is live at” followed by your public URL address. Click the link to open your live web page in a browser.

Customizing Your GitHub Pages Website

A standard static site can be expanded with automated site builders, modern styling frameworks, and personalized domain branding. Exploring the choice between WordPress vs static site generators shows how static publishing provides unmatched loading speeds and simplified maintenance.

Adding Themes and Static Site Generators (Jekyll)

GitHub Pages includes native, server-side support for Jekyll, a popular Ruby-based static site generator that transforms Markdown text files into complete HTML layouts.

  • Native Jekyll Processing: GitHub automatically builds Jekyll sites without requiring local command-line compilation when raw Markdown files and a _config.yml file are present.
  • Bypassing Jekyll with .nojekyll: If you build your site using modern frameworks like React, Vue, Vite, or Astro, place an empty file named .nojekyll in your root directory to prevent GitHub from attempting Jekyll parsing on underscore folders.
  • Custom Workflows via GitHub Actions: You can select “GitHub Actions” as your deployment source in Pages settings to automate builds for frameworks like Next.js or Hugo using pre-configured workflow templates.

Configuring a Custom Domain

This github pages custom domain tutorial section outlines how to link a domain bought through external registrars like Namecheap, Cloudflare, or GoDaddy to your repository.

  1. In your repository’s Settings > Pages section, scroll down to the “Custom domain” input box.
  2. Enter your domain name (such as www.example.com or example.com) and click Save. GitHub creates a commit adding a file named CNAME to your repository root.
  3. Log into your DNS provider dashboard and add an ALIAS, ANAME, or A record pointing your Apex domain to GitHub’s official IP addresses:
    • 185.199.108.153
    • 185.199.109.153
    • 185.199.110.153
    • 185.199.111.153
  4. For subdomains like www, create a CNAME record pointing to <username>.github.io.
  5. Return to GitHub Pages settings, wait for DNS propagation, and check the box labeled Enforce HTTPS to activate free SSL protection.

Troubleshooting Common GitHub Pages Errors

When your site fails to build or displays unexpected content, checking a few common setup details usually resolves the issue quickly.

  • 404 Not Found Errors: Verify that an index.html file exists in the exact root folder of your publishing branch. Case sensitivity matters; naming the file Index.html or INDEX.HTML will break routing on Linux build servers.
  • Styles or Images Not Loading: Check relative asset paths in your code. On project sites hosted under subpaths like username.github.io/project-name/, relative links starting with a leading slash (/style.css) resolve to the root domain instead of the project directory. Use ./style.css or relative paths instead.
  • Jekyll Build Failures: Inspect the “Actions” tab in your repository to review build logs. Broken Liquid template tags or unsupported Jekyll plugins will cause deployment workflows to fail.
  • DNS Verification Failures: DNS changes take anywhere from 5 minutes to 48 hours to propagate worldwide. If HTTPS enforcement remains greyed out, re-verify your DNS A records and wait for CAA record checks to complete.