Set Up GitHub Actions CI for a Gatsby Site

The agent reads what the repository declares before it writes a workflow. In a site like gatsbyjs/gatsby-starter-blog there is no .github directory, so nothing runs when a pull request opens. package.json has a package-lock.json beside it, so the package manager is npm; its scripts are build (gatsby build), develop, serve, clean, format (prettier --write over js, jsx, ts, tsx, json and md) and a test script that prints a reminder and exits 1. There is no engines field and no .nvmrc, so the agent picks a current Node LTS and pins it in one place in the workflow. gatsby is ^5.14.6, with gatsby-plugin-sharp and gatsby-transformer-sharp for the images under content/blog and src/images, and gatsby-plugin-feed and gatsby-plugin-manifest as part of the build.

Then it decides what a useful job can check. test cannot be a step, because it exits 1 by design, and the agent says so in the pull request rather than hiding it behind continue-on-error. Formatting can: the format script writes, so the agent adds a format:check script with the same glob and prettier --check, which respects the repository's .prettierrc (semi: false, arrowParens: avoid). The build is the real gate: gatsby build runs the GraphQL schema build, processes every image through Sharp, renders the three posts under content/blog and the pages under src/pages, including using-typescript.tsx, and writes public/. It needs no environment variable; gatsby-config.js hard-codes siteUrl and reads nothing from process.env.

The workflow it writes at .github/workflows/ci.yml runs on pull requests and on pushes to the default branch, with a concurrency group per ref so a new push cancels the previous run. The job checks out the repository, uses actions/setup-node with the pinned Node version and cache: npm, runs npm ci, then npm run format:check and npm run build as separate named steps so a failure points at one of them. Because a Gatsby build is incremental when .cache and public survive, the agent adds an actions/cache step keyed on the lockfile and the hash of gatsby-config.js, gatsby-node.js and the sources, restoring those two directories, which .gitignore already excludes from the repository. It uploads public/ as a workflow artifact so a reviewer can inspect the built site from the run.

Before opening anything, the agent runs the same three commands in its sandbox with the pinned Node version, npm ci, npm run format:check and npm run build, and fixes what fails: if prettier --check reports a file the repository never formatted, it runs the existing format script on that file in a separate commit so the check starts green. It then pushes the branch, opens the pull request and watches the new workflow run on it, reading the job log through the GitHub App installation until the run finishes.

What comes back is a pull request on its own branch that adds .github/workflows/ci.yml and a format:check script in package.json, sometimes with a second commit that formats files the repository had never run Prettier over. The description walks through the workflow step by step: the trigger and concurrency group, the pinned Node version and why it was chosen in the absence of engines or .nvmrc, the npm cache, the .cache and public cache and its key, the two check steps and the artifact upload, and it says plainly that the test script was left out because it exits 1 by design.

The pull request also reports what the workflow did when it ran on that very branch, read from the job log: the result of each step and whether the Gatsby cache was restored or freshly written. The session read names the repository and the pull request URL, and the transcript at GET /o/{org}/sessions/{id}/messages keeps the sandbox build output and the workflow log reads.

Before merging, a reviewer checks that the Node version pinned in the workflow is the one the team deploys with, that the cache key includes everything a Gatsby build depends on so a stale .cache cannot hide a broken change, and that the artifact retention suits the repository. The workflow will fail on any pull request that breaks the build or the formatting from then on, which is the point.

Send this request once per repository that has no workflow yet, from a script that lists them and sets resources to each one with a request_id per repository, so a retried call returns the run already started. Each run makes its own branch and pull request in its own sandbox, so a dozen sites can be set up at once.

Set a webhook URL on the key and Rush POSTs run.completed with data.session_url when each turn finishes. If a review asks to add a deploy step later, a follow-up on the same session wakes the parked sandbox with the branch and the built public/ already there.

A workflow written without running it is a guess, and the slow part of a Gatsby build, image processing with Sharp, is exactly what a laptop shortcut skips. The agent runs the full npm ci and gatsby build in its own sandbox with the pinned Node version before it writes the YAML, then watches the workflow run on the pull request, so the first green run is in the description rather than hoped for.

The record is kept: the sandbox build output, every file the agent read to choose the steps, and the workflow log it followed are all in the transcript. A follow-up on the same session changes the workflow without starting from a cold clone.

Why is the test script not a step?

Which Node version does it pin?

Does caching .cache and public risk a stale build?

Will it add a deploy step?