All jobs

Add a Build Check for Every Pull Request to a Zola Site

Yes. An agent adds a workflow that builds the site and checks its links on every pull request without publishing, proves it fails on a broken link, 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 with how the site is built today, because the check should run the same build the deploy does. In a site laid out like pawroman/zola-theme-terminimal, config.toml sets compile_sass = true, generate_feeds = true with rss.xml and atom.xml, a tags taxonomy, and a menu_items list under [extra] whose URLs use a $BASE_URL placeholder; content/_index.md paginates by 2; and templates/index.html renders the feed links, the menu and the paginator from those settings. The only workflow, .github/workflows/publish-pages.yml, runs on push to master and calls shalzz/zola-deploy-action@master with the repository's GITHUB_TOKEN, so a pull request gets no build at all and a broken template is found after it is merged and published. The README says the theme is tested with Zola 0.19.2.

It then adds a second workflow, .github/workflows/check.yml, on pull_request and on push to master, that runs zola build and zola check. It installs the Zola release the README names rather than whatever a floating tag gives, so a pull request is checked against the version the maintainer tested. The deploy action stays as it is, since the check is a separate job that must not publish, and the new workflow sets permissions: contents: read because it writes nothing.

Two things come from reading rather than from the Zola docs. zola check verifies internal links and, by default, external ones too, and this theme's menu points at GitHub and the demo site, so the agent runs the external check with the --skip-external-links flag off but allows the job to pass on a transient external failure only through a second, non-blocking step, keeping the internal-link check strict. And because base_url is the demo's GitHub Pages address while a pull request has none, the build runs with --base-url set to a placeholder so $BASE_URL in the menu expands to something and not to the published site.

In its sandbox the agent downloads the Zola release, runs zola build and zola check on the repository as it stands to record a clean baseline, then breaks a link in content/pages/about.md on a scratch branch, runs the check again to read the failure line naming the page and the link, and reverts it. The pull request quotes both runs. Nothing is pushed to the Pages branch and the publish workflow is not triggered, since it listens to master only.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add a build check for pull requests to this Zola site. Read config.toml, templates/index.html, content/_index.md, README.md and .github/workflows/publish-pages.yml first. Add .github/workflows/check.yml on pull_request and push to master that installs the Zola release the README names, runs zola build with a placeholder --base-url and zola check, with permissions limited to contents: read and no deploy step; keep the internal link check blocking and put the external link check in a step that does not fail the job. Do not change the publish workflow or any template. In the sandbox download that Zola release, run zola build and zola check for a clean baseline, then break one internal link in content/pages/about.md, run zola check again, revert, and quote both outputs in the pull request. Open a pull request.",
  "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 that adds .github/workflows/check.yml and nothing else: the publish workflow, config.toml and every template and page are as they were. The description quotes the clean zola build summary with its page count and the zola check pass, then the second check's failure naming about.md and the link it could not resolve, and says the external check is advisory and the internal one blocks.

The run's record keeps the Zola download, both builds and both checks, so a reviewer can read the exact release used and see that the broken link run really failed before the revert.

Before merging, a reviewer decides whether the external link step should stay advisory or block once the links are known good, and whether to pin the deploy action in publish-pages.yml to the same release, which the pull request mentions but does not do.

Run it on every pull request

Once the workflow is in, GitHub runs the check on every pull request. The review on top of it comes from an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt that reads the check's result and the diff: a run per push that, when the build or a link fails, posts a review quoting the failing line with the file and the fix, and when it passes, reads the rendered page the diff touched and reviews the output rather than the source.

Only work by an owner, member or collaborator fires the trigger; a pull request from a fork never does. Each run builds the site in its own sandbox from that pull request's branch, so two reviews never share a build directory.

The use case this job follows, with its automation and trigger: Review every pull request.

Why run it on Rush?

A static site with a deploy-on-push workflow and no pull request check finds its mistakes on the live site: a template that no longer compiles, a renamed page the menu still points at, a feed that stopped validating. In a Rush sandbox the agent builds the site the way the deploy does, with the version the maintainer tested, and proves the check catches a broken link before writing a line of the workflow.

Both check runs stay with the run and the pull request quotes them, so the reviewer sees the failure line a bad link produces rather than trusting that zola check would notice. Across every site a team keeps, the job runs in parallel, one sandbox and one pull request each.

Frequently asked questions

Will the check publish anything?

No. It runs zola build into the job's own public/ directory and zola check, with contents: read permissions and no deploy step. The existing publish workflow still runs on push to master and is not changed.

What does zola check actually verify?

That every internal link in the content resolves to a page or asset the build produced, and that external links answer. The pull request keeps the internal check blocking and makes the external one advisory, because a third-party site being down should not block a theme change.

Why pin the Zola version?

Because the README says which release the theme was tested with, and a floating tag would check a pull request against a newer Zola than the one that publishes the site. The workflow names the release so a bump is a visible one-line change.

Does this handle the $BASE_URL placeholder in the menu?

Yes. The build runs with --base-url set to a placeholder, so the menu entries expand to that address in the checked output rather than to the live demo's, and zola check treats them as internal links.

More Zola jobs

More jobs like this: Review every pull request

Keep reading