# GitHub Pages

> Static site hosting that publishes HTML, CSS and JavaScript straight from a GitHub repository.

- Category: [Static & frontend hosting](https://freetier.tech/c/static-hosting.md)
- Free tier: Always free. Free for public repositories on GitHub Free; sites up to 1 GB with a 100 GB/month soft bandwidth limit.
- Non-commercial only
- No card required
- Pricing: https://github.com/pricing
- Last verified: 2026-10-28

## Free tier limits

- Public repositories only on GitHub Free (private repos need a paid plan)
- 1 GB max published site size
- 1 GB recommended source repository size
- 100 GB per month soft bandwidth limit
- 10 builds per hour soft limit (not applied to custom GitHub Actions workflows)
- Deployments time out after 10 minutes
- 1 user or organization site per account; 1 project site per repository
- GitHub Actions is free for public repositories on standard GitHub-hosted runners

## Gotchas

- GitHub says Pages may not be used as free hosting for an online business, e-commerce site or commercial SaaS, nor for sensitive transactions such as passwords or credit card numbers.
- The published site is public even when its repository is private (on plans that allow private Pages repos).
- Changes can take up to 10 minutes to go live after a push.
- Pushing `.github/workflows` files needs the `workflow` OAuth scope; gh's default scopes are repo, read:org and gist (add it with `gh auth refresh -s workflow`).
- A CNAME file does not set a custom domain; configure it in the repository's Pages settings or via the REST API.
- Commits pushed by a workflow using GITHUB_TOKEN do not trigger a branch-based Pages build.

## Setup

### What the human does

1. Sign up at https://github.com/signup and verify your email address.
2. Approve the GitHub CLI login in the browser when the agent runs `gh auth login`, or create a fine-grained personal access token.

### How the agent gets access

#### CLI login

- Install: `brew install gh`
- Run: `gh auth login --web --scopes workflow`
- Notes: Browser login with a one-time code; installers for other OSes are at https://cli.github.com. The workflow scope lets the agent push Pages workflow files.

#### API key

- Install: `brew install gh`
- Get it at: https://github.com/settings/personal-access-tokens/new
- Env var: `GH_TOKEN`
- Notes: Fine-grained token for the site repo with Contents, Pages, Administration and Workflows write; gh uses GH_TOKEN instead of stored credentials.

### Verify

```sh
gh auth status
```

## Docs

- Quickstart: https://docs.github.com/en/pages/quickstart
- llms.txt: https://docs.github.com/llms.txt

## Sources

- https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits
- https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages
- https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
- https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- https://docs.github.com/en/pages/quickstart
- https://docs.github.com/en/get-started/learning-about-github/githubs-plans
- https://github.com/pricing
- https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
- https://docs.github.com/en/github-cli/github-cli/quickstart
- https://docs.github.com/en/github-cli/github-cli/authenticating-with-github-cli
- https://cli.github.com/
- https://cli.github.com/manual/gh_auth_login
- https://cli.github.com/manual/gh_auth_refresh
- https://cli.github.com/manual/gh_auth_status
- https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
- https://docs.github.com/en/rest/pages/pages
- https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens
- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
- https://docs.github.com/llms.txt

JSON: https://freetier.tech/api/v1/services/github-pages.json