Choose the publishing source
GitHub Pages can publish through a custom Actions workflow when the repository is configured for it. Decide whether the site is a user site or a project site because the public base path affects links and assets. A build that works at the domain root can fail when deployed under a repository subdirectory if that path was never considered.
Build in a dedicated job
Check out the intended revision, set up the runtime and install dependencies using the lockfile. Run the checks appropriate to the project, then generate the static output. For a Next.js export, this is the directory produced by the export build, not the source tree and not the development cache. Upload only the files the static host should serve.
Pass an artifact to publication
The deploy job should depend on the successful build and publish the uploaded Pages artifact. This creates an explicit relationship between tested output and deployed output. Use the documented official actions and review their current versions rather than copying an old workflow without understanding its permissions, required artifact format or environment configuration.
Trace a small example failure
Suppose the workflow uploads the repository root while the generated site lives in out/. The deployment step can succeed even though visitors see the wrong files or missing routes. Inspect the artifact before changing application code. Listing its top-level paths and checking for index.html, framework assets and a representative deep page can expose the packaging error immediately.
Scope permissions and concurrency
Give the deployment job the documented Pages and identity-token permissions it needs, keeping unrelated repository access out of scope. Use an environment for deployment visibility and applicable protections. Coordinate publishing runs so two releases do not compete for the same destination. Avoid logging sensitive variables while debugging permissions because build logs may have a broader audience than intended.
Verify the resulting URL
Use the deployment output to find the final public address, then check direct deep links, asset paths, the sitemap and a missing page. Test the site as a visitor rather than stopping at a green Actions summary. Keep the previous successful artifact or revision identifiable so a broken release can be investigated and restored through a deliberate publication step.
Further reading
Put the idea to work.
Explore free browser tools for images, text and developer workflows.