Free GitHub Pages Publishing Workflow

Publishing with GitHub Pages is simple once it is configured, but domain rules, CNAME placement, and build output checks can cause 404s or broken deployments. This collection groups the tools that matter before and after you push.

Best for

Setting up a custom domain on GitHub Pages.
Checking static output before pushing a release.
Preparing CNAME, robots.txt, sitemap, and favicon files for a new site.

Workflow steps

Set up your repository: Create or configure your GitHub repository with the correct publishing source. Choose the branch and folder that GitHub Pages will serve from, such as main /root for user sites or gh-pages /docs for project sites.
Configure your custom domain: Prepare a CNAME file with your custom domain and place it in the published output root. Configure the custom domain field in your repository settings.
Update DNS records: Create a CNAME record for your www subdomain pointing to your GitHub Pages URL. Configure an ALIAS, ANAME, or A record for your apex domain if you use one.
Run the SEO checklist: Use the static site SEO checklist generator to review your page metadata, indexing directives, and required files before pushing.
Push and wait for HTTPS: Push your changes and wait for GitHub Pages to deploy and provision an HTTPS certificate. This can take several minutes for a new custom domain.
Verify the live site: Test the published URL over both HTTP and HTTPS. Check that CNAME, robots.txt, sitemap.xml, and all assets serve correctly from the published output.

Prerequisites

A GitHub account with a repository configured for Pages publishing.
A custom domain name with DNS management access through your registrar or DNS provider.
Static site files ready to publish, including an index.html in the output root.
A build system or CI workflow that generates a dist folder or output directory for publishing.

Publishing checklist

CNAME file exists in the published output root and contains only the custom domain name with no extra characters.
DNS records for the custom domain have propagated, confirmed with a DNS lookup tool.
Repository publishing source setting matches the branch and folder used in the build.
HTTPS certificate is active and the site redirects HTTP to HTTPS automatically.
Sitemap.xml and robots.txt exist in the published root and reference correct URLs.
All assets referenced in pages, such as CSS, images, and JavaScript, return 200 status and not 404.

Related collections

Multilingual Website Setup, Blog Publisher Toolkit

FAQ

Questions about github pages publishing workflow

What happens if I change my publishing source after the site is live?

Changing the publishing source can cause a temporary outage. GitHub Pages needs to redeploy from the new source, and your custom domain may lose its HTTPS certificate during the transition. Make this change during low traffic.

Can I use GitHub Pages with a static site generator?

Yes. GitHub Pages works with any static site generator. The CI workflow typically runs the build command and deploys the output. Just make sure the generated output folder matches the publishing source setting.

Do I need to add a .nojekyll file?

If your site uses files or folders starting with an underscore, GitHub Pages may skip them because Jekyll treats underscored paths as special. Add a .nojekyll file to the published output root to disable Jekyll processing.

Why does my custom domain show a certificate error?

Certificate errors usually mean DNS has not propagated, the custom domain is misconfigured in repository settings, or GitHub Pages has not finished provisioning the certificate. Check that the CNAME file matches the repository custom domain field and that DNS points to the correct GitHub Pages IP addresses.