All jobs

Add a GitHub Pages Deploy Workflow to a Hugo Site

Yes. An agent adds a workflow that builds your Hugo site with the Hugo, Go and Node versions it already pins and publishes it to GitHub Pages, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts by finding out how the site is built today, because a Hugo deploy workflow that installs the wrong Hugo fails on the first theme function it does not know. In a site made from docsy/docsy-example, hugo.yaml pulls the theme in as a Hugo module (github.com/docsy/docsy/theme, extended Hugo at least 0.160.1), go.mod names that module, package.json pins hugo-extended 0.166.0 and sass-embedded 1.106.1 as devDependencies, .nvmrc says 24.22.1, and engines asks for Node 24 and npm 11.18 or newer. There is no deploy workflow: .github/workflows/ holds links.yaml, which builds the site to check links, and zizmor.yaml, which audits workflows in pedantic mode. netlify.toml is the only deploy config, and it runs npm run _netlify:prepare && npm run build:production with GO_VERSION 1.22.2.

The npm scripts matter more than the Hugo binary. The README says to run Hugo through them because they put the Dart Sass sass CLI from node_modules on the PATH, and a direct hugo call fails without it. .npmrc sets strict-allow-scripts=true and package.json approves only hugo-extended@0.166.0's install script, so npm ci is the one install that fetches the Hugo binary, and install:safe (npm ci --ignore-scripts) does not. build:production is hugo --cleanDestinationDir --minify with no base URL, so the agent passes one through: npm run build:production -- --gc --baseURL "$BASE_URL/", which npm forwards to the inner _hugo script.

The agent then writes .github/workflows/deploy.yaml in the shape Hugo's own GitHub Pages guide uses: a build job and a deploy job, permissions of contents: read, pages: write and id-token: write, a pages concurrency group with cancel-in-progress: false, and triggers on push to main and workflow_dispatch. The build job checks out with fetch-depth: 0 because hugo.yaml sets enableGitInfo: true and a shallow clone gives every page the same last-modified date; sets up Go with actions/setup-go so hugo mod can resolve the theme; sets up Node from .nvmrc with the npm cache on; runs npm ci; calls actions/configure-pages to learn the site's base URL; builds with that URL; and uploads ./public with actions/upload-pages-artifact. The deploy job runs actions/deploy-pages in the github-pages environment. Every action is pinned to a commit SHA with a version comment, the way links.yaml already pins actions/checkout and actions/setup-node, so the zizmor workflow stays green.

Before opening the pull request the agent runs the build in its sandbox with the same commands: npm ci, then the production build with a base URL of the form https://your-org.github.io/your-app/, and checks that the stylesheet and page links in public/index.html carry that prefix rather than https://example.docsy.dev, the baseURL in hugo.yaml. It runs actionlint and zizmor on the new file. The pull request body tells the reader the one step a workflow cannot do: in the repository's Settings, under Pages, set Source to GitHub Actions.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a GitHub Actions workflow that deploys this Hugo site to GitHub Pages. Read hugo.yaml, package.json, .npmrc, .nvmrc, go.mod, netlify.toml, README.md and every file under .github/workflows first. Build the site the way the npm scripts do, with the Hugo and Sass versions package.json pins, not a separately downloaded Hugo. Use a build job and a deploy job with the pages permissions, concurrency group and actions/configure-pages, upload-pages-artifact and deploy-pages steps, pass the base URL configure-pages reports into the build, and check out with full history because enableGitInfo is on. Pin every action to a commit SHA with a version comment like links.yaml does. Run npm ci and the production build in the sandbox with a GitHub Pages style base URL and confirm the built HTML uses it, run actionlint and zizmor on the new workflow, then open a pull request whose description says how to set the Pages source to GitHub Actions.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with one new file, .github/workflows/deploy.yaml, and nothing changed under content/, hugo.yaml or package.json. The description lists the build command it runs, the base URL it checked in the sandbox build, the actionlint and zizmor output, and the Settings step the reader does once.

The run's record holds the npm ci output, which shows hugo-extended installing its binary, the Hugo build log with its page and asset counts, and the grep over public/ that found the base URL in the rendered links, so a reviewer can see the build worked before the workflow ever runs on GitHub.

Before merging, a reviewer checks the branch name in the trigger against the repository's default branch, decides whether netlify.toml and the Netlify _redirects output format in hugo.yaml stay or go now that Pages serves the site, and whether to keep the Netlify preview URL in params.mainBranchPreviewURL. The agent leaves all three alone and says so.

Run it on every Hugo site with no deploy workflow

A team with several Hugo sites starts one run per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retry returns the run already started. GET /o/{org}/github lists every repository the installation reaches, so a script can clone each, look for hugo.toml or hugo.yaml and start a run only where no workflow under .github/workflows/ runs hugo.

Each run reads its own site. One that installs Hugo straight from a GitHub release gets a workflow with Hugo's own download step and a HUGO_VERSION env; one that, like this site, gets Hugo from npm gets npm ci; one with a themes/ submodule instead of a module gets submodules: recursive on checkout instead of a Go setup. The pull requests arrive one per site, each with its own sandbox build in the record.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Pages workflow written from a template without reading the site breaks in ways that only show on the first deploy: Hugo installed from a release while the theme expects the npm-pinned one, sass missing from the PATH so every SCSS partial fails, a shallow checkout that stamps every page with today's date, or a base URL left at the Netlify domain so every stylesheet link points off the site. In a Rush sandbox the agent runs the real npm ci and the real build, with the same lockfile and the same Hugo, and reads the HTML it produced before it writes the workflow.

The build log, the base URL check and the zizmor audit stay with the run and the pull request cites them, so the reviewer reads evidence rather than a promise. Running the same job across a dozen documentation sites costs the same attention as one, because each run has its own machine, its own log and its own pull request.

Frequently asked questions

Why build through npm rather than install Hugo in the workflow?

Because this site's build only works that way. The README says a direct hugo call fails without the Dart Sass CLI the npm scripts put on the PATH, and package.json pins hugo-extended 0.166.0 so that npm ci installs exactly the Hugo the site was last tested with. A site that is not on npm gets Hugo's release download step instead; the agent reads which case it is in.

Why fetch-depth 0?

hugo.yaml sets enableGitInfo: true, which gives each page its last-modified date from the commit that touched it. On a shallow clone every page shares the one commit the runner has, so the dates are wrong but the build still passes, which is why the agent reads the config rather than trusting a green check.

Will the Netlify deploy keep working?

Yes. The workflow adds a second publisher and removes nothing: netlify.toml, the _redirects output format and the preview URL in hugo.yaml are untouched. The pull request names them so the reader can decide whether to drop Netlify once Pages serves the site.

Does the workflow pass the zizmor check already in the repository?

The agent runs zizmor on the new file in the sandbox before opening the pull request. zizmor.yaml audits in pedantic mode, so the workflow pins each action to a commit SHA, declares the minimum permissions per job and sets persist-credentials: false on checkout where the job does not push.

What about the link check that already builds the site?

links.yaml keeps running on pull requests; the deploy workflow runs only on pushes to main and by hand. The agent does not merge the two, because the link check wants a build with drafts and the deploy wants the minified production one, and the two jobs would then hold each other up.

More Hugo jobs

The same job on other stacks

Keep reading