# 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 Rush](https://cloud.getrush.ai/run/add-deploy-workflow/hugo/). Opens 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`

```json
{
  "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.

## 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

- [Add Giscus Comments to a Hugo Blog](https://getrush.ai/run/add-giscus-comments/hugo/)
- [Add i18n to a Hugo Site](https://getrush.ai/run/add-i18n/hugo/)
- [Add Lighthouse CI to a Hugo Docs Site](https://getrush.ai/run/add-lighthouse-ci/hugo/)

## The same job on other stacks

- [Add a GitHub Pages Deploy Workflow to a Jekyll Site](https://getrush.ai/run/add-deploy-workflow/jekyll/)
- [Add a Deploy Workflow for a Lit Component's Docs Site](https://getrush.ai/run/add-deploy-workflow/lit/)
- [Add a GitHub Pages Deploy Workflow to an mdBook](https://getrush.ai/run/add-deploy-workflow/mdbook/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
