GitHub Pages
Static site hosting that publishes HTML, CSS and JavaScript straight from a GitHub repository.
- Always free
- Non-commercial only
- No card required
Free tier
Free for public repositories on GitHub Free; sites up to 1 GB with a 100 GB/month soft bandwidth limit.
- 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/workflowsfiles needs theworkflowOAuth scope; gh's default scopes are repo, read:org and gist (add it withgh 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 you do
- Sign up at https://github.com/signup and verify your email address.
- Approve the GitHub CLI login in the browser when the agent runs
gh auth login, or create a fine-grained personal access token.
How your agent gets access
CLI login
- Install
brew install gh- Run
gh auth login --web --scopes workflow
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
- github.com/settings/personal-access-tokens/new
- Env var
GH_TOKEN
Fine-grained token for the site repo with Contents, Pages, Administration and Workflows write; gh uses GH_TOKEN instead of stored credentials.
Check it worked
gh auth statusSources
- docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits
- docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages
- docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
- docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- docs.github.com/en/pages/quickstart
- docs.github.com/en/get-started/learning-about-github/githubs-plans
- github.com/pricing
- docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github
- docs.github.com/en/github-cli/github-cli/quickstart
- docs.github.com/en/github-cli/github-cli/authenticating-with-github-cli
- cli.github.com
- cli.github.com/manual/gh_auth_login
- cli.github.com/manual/gh_auth_refresh
- cli.github.com/manual/gh_auth_status
- docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
- docs.github.com/en/rest/pages/pages
- docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens
- docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
- docs.github.com/llms.txt