Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Pages, Packages and Releases

GitHub Pages: Hosting a Website

Publish a static site with GitHub Pages: user, organization and project sites, branch or Actions publishing, custom domains with HTTPS, Jekyll basics and limits. Includes a URL calculator.

GitHub Pages turns a repository into a website. You push HTML, CSS and JavaScript (or a source that builds to them), and GitHub serves the result over HTTPS from a global network. It is a favorite for personal sites, project documentation, portfolios and blogs, because it is free for public repositories and needs no server administration.

Pages serves static files only. There is no PHP, no database and no server-side code. If you need those, use a hosting service for apps, and keep Pages for the front end or documentation.

Three kinds of site and their URLs

Type Repository name URL
User site USERNAME.github.io https://USERNAME.github.io/
Organization site ORGNAME.github.io https://ORGNAME.github.io/
Project site any name, e.g. my-app https://USERNAME.github.io/my-app/

Every account can have one user (or organization) site and unlimited project sites. The path prefix of a project site (/my-app/) matters: links such as /style.css point to the account root and break. Use relative links (style.css) or a configured base path in your site generator.

JS Stand-in: Pages URL calculator (our own helper)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Run it and compare the last two lines: the absolute path drops the /octo-app/ prefix, which is the classic "my CSS is missing on GitHub Pages" bug.

Publishing source: branch or Actions

Under Settings -> Pages -> Build and deployment, choose a source.

Deploy from a branch. Pick a branch and a folder (/ or /docs). GitHub serves those files as they are (or builds them with Jekyll, see below). It is the simplest option for hand-written HTML.

GitHub Actions. Any workflow can build the site and deploy it. This supports every static site generator (Hugo, Astro, Vite, Docusaurus, Eleventy, MkDocs, Next.js static export). A typical workflow uploads a Pages artifact and then deploys it:

YAML
name: Deploy site

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

The pages: write and id-token: write permissions allow the deployment and prove its origin. The job targets the github-pages environment, which gives you a deployment history and optional protection rules. Remember that with a build step your tool may also need the base path (/my-app/) in its config.

Jekyll in one minute

If you choose "deploy from a branch" and your files contain Markdown, GitHub runs Jekyll, a Ruby static site generator, automatically. A small site might be:

TEXT
_config.yml          # title, theme, settings
index.md             # becomes /
about.md             # becomes /about/
_posts/2026-01-15-hello.md

with front matter on each page:

MARKDOWN
---
title: Hello
layout: default
---
# Hello, world

Jekyll ignores files and folders starting with _ or . unless configured. To skip Jekyll completely (for a plain HTML site or output from another generator), add an empty file named .nojekyll at the publishing root. Many "my folder _next is missing" problems end with this single file.

Custom domains and HTTPS

To use www.example.com instead of the github.io address:

  1. In Settings -> Pages -> Custom domain, enter the domain and save. For branch publishing, GitHub commits a CNAME file; with Actions publishing the setting alone is enough.
  2. At your DNS provider, create a CNAME record for www pointing to USERNAME.github.io.
  3. For an apex domain (example.com), create A records to GitHub's Pages IP addresses (listed in the official documentation) and/or AAAA records for IPv6, or use an ALIAS/ANAME record if your provider has it.
  4. Wait for DNS to propagate, then tick Enforce HTTPS. GitHub issues and renews a free certificate.

Verify the domain at the account or organization level (Settings -> Pages -> Add a domain) to stop others from taking over a dangling DNS record that still points at GitHub.

Limits and good practice

  • Source repositories should stay under roughly 1 GB, published sites under about 1 GB, with soft limits of around 100 GB of bandwidth per month and 10 builds per hour. Pages is not meant for running a business storefront or hosting large downloads.
  • Do not publish secrets: in a public repository everything is public, and even a private repository's published site is public unless your plan supports private Pages.
  • Add a 404.html at the root for a custom "not found" page.
  • Single-page apps with client-side routing need a fallback trick (copy index.html to 404.html) because Pages has no rewrite rules.
  • Use relative links or a base path, check the Actions tab when a deploy fails, and check the browser console for 404s.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the URL of a project site for repository my-app owned by mona?

    Project sites live under the owner's github.io domain with the repository name as a path.
  2. 2. Why does <link href="/style.css"> often break on a project site?

    Absolute paths ignore the project path prefix; use relative paths or a configured base path.
  3. 3. Which file stops GitHub from running Jekyll on your files?

    An empty .nojekyll at the publishing root turns off the Jekyll build.
  4. 4. Which workflow permissions does deploy-pages need?

    pages: write allows publishing and id-token: write verifies the deployment's origin.

Summary

  • Pages hosts static files from a user, organization or project repository; project URLs include the repository name.
  • Publish from a branch (simple, optional Jekyll) or from a GitHub Actions workflow (any generator).
  • Use relative links or a base path, .nojekyll for non-Jekyll output, and 404.html for errors.
  • Custom domains need DNS records and "Enforce HTTPS"; verify your domain for safety.

Next: GitHub Packages and Container Registry