# Add Tag Pages to a Gatsby Blog from a Linear Issue

Yes. An agent adds a tags field to the Markdown schema, builds one page per tag and a tag index in gatsby-node.js, links them from each post, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-tag-pages/gatsby/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by reading how the blog is wired. In a site shaped like gatsbyjs/gatsby-starter-blog, `package.json` pins `gatsby` at ^5.14.6 with `gatsby-transformer-remark`, `gatsby-source-filesystem`, `gatsby-plugin-feed` and React 18, installs with npm from `package-lock.json`, has `prettier` as its only dev dependency, and its `test` script prints a reminder to write tests and exits 1, so there is no test suite and no workflow under `.github/`. `gatsby-config.js` points `gatsby-source-filesystem` at `content/blog`, where three posts (`hello-world`, `my-second-post`, `new-beginnings`) each carry `title`, `date` and sometimes `description` in their frontmatter, and nothing else.

`gatsby-node.js` is where the pages come from. `createPages` runs one `allMarkdownRemark` query sorted by date, creates a page per post with `src/templates/blog-post.js` and passes the previous and next post ids in `context`; `onCreateNode` adds a `slug` field with `createFilePath`; and `createSchemaCustomization` declares the `Frontmatter` type with exactly `title`, `description` and `date`, so a query for a `tags` field would fail the build until the type knows it. `src/pages/index.js` lists every post with its date and excerpt, and `src/components/seo.js` builds the head from `siteMetadata`.

The agent adds `tags: [String]` to the `Frontmatter` type first, so posts without tags keep building and the field reads as `null` rather than breaking the query. It writes `src/templates/tag.js`, a template whose page query filters `allMarkdownRemark` on `frontmatter.tags` containing the tag passed in `context` and renders the same post list the index uses, and `src/pages/tags.js`, which groups all posts by tag with a `group(field: {frontmatter: {tags: SELECT}})` query and lists each tag with its post count. In `createPages` it adds a second query for the grouped tags and a `createPage` call per tag at `/tags/<slug>/`, with the slug made by a small helper in `gatsby-node.js` rather than a new dependency. `blog-post.js` and `index.js` get a row of tag links under each title, and the three sample posts get a `tags` list in their frontmatter so the pages have something to show.

Then it proves the build. `npm ci` and `npm run build` have to finish without a GraphQL error, and `gatsby serve` lets the agent fetch `/tags/`, one tag page and one post to confirm the links resolve and the RSS feed at `/rss.xml` still renders. `npx prettier --check` runs over the changed files because the repository formats with it. The agent commits the template, the page, the `gatsby-node.js` changes, the frontmatter edits and nothing under `public/` or `.cache/`, which `.gitignore` already excludes.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for tag pages on the blog: each post may list tags in its frontmatter, every tag gets a page at /tags/<tag>/ listing its posts, /tags/ lists every tag with a count, and each post and the index show the post's tags as links. Read package.json, gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/pages/index.js, src/components/seo.js and the frontmatter of every file under content/blog first. Add tags: [String] to the Frontmatter type in createSchemaCustomization so untagged posts still build. Add src/templates/tag.js and src/pages/tags.js, create one page per tag in createPages from a grouped allMarkdownRemark query with a slug helper in gatsby-node.js, link the tags from blog-post.js and index.js, and add tags to the existing posts. Run npm ci, npm run build and gatsby serve, fetch /tags/, one tag page, one post and /rss.xml, run prettier --check on the changed files, and open a pull request that links the issue and lists the new routes.",
  "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 on its own branch. It adds `src/templates/tag.js` and `src/pages/tags.js`, changes `gatsby-node.js` in three places (the `tags` field on the `Frontmatter` type, the grouped tags query and the per-tag `createPage` loop with its slug helper), adds tag links to `src/templates/blog-post.js` and `src/pages/index.js`, and adds a `tags` list to the frontmatter of the posts under `content/blog`. The description lists the routes the build produced, with `/tags/` and each `/tags/<slug>/` named, and quotes the issue.

Because the starter has no CI workflow and its `test` script exits by design, the proof is in the run's record rather than in a check. The trajectory at `GET /o/{org}/sessions/{id}/messages` keeps the `gatsby build` output with its page count, the `curl` of each new route against `gatsby serve`, the feed fetch and the `prettier --check` result, so a reviewer reads what the build did instead of trusting a description.

Before merging, a reviewer checks the tag names in the sample posts, decides whether `/tags/` belongs in the site navigation (the starter has no nav component, so the agent links it from the tag rows only), and confirms the slug helper handles the tags their real posts will use. Nothing deploys until the pull request merges.

## Run it on every Linear issue labelled agent

Connect Linear once from Settings → Connections, then add an automation to the Project that holds the blog with this prompt and a `linear` trigger on `linear.issue.labeled`, naming the label in `config.labels`. The trigger appends the labelled issue after the prompt and fills in no placeholder, so the agent reads the routes and the tag rules from the issue itself. Each labelled issue starts its own run in its own sandbox and ends in its own pull request; `max_runs_per_hour` caps how many the automation starts in an hour.

A handler on your own server can do the same without the automation: when Linear's webhook reports the label, it sends `POST /o/{org}/sessions` with the repository and `https://linear.app/<workspace>/issue/<ID>` in `resources`, which puts the issue text in the prompt through your Linear connection, and a `request_id` that is a UUID v5 of the issue id so a redelivered webhook returns the run it already started rather than a second one.

## Why run it on Rush?

A Gatsby schema change is only known to work after a full build, and the build is what takes the time: install, source the Markdown, run every page query, write `public/`. On a laptop that loop competes with a dev server holding `.cache/`, and a wrong `createTypes` string surfaces as a GraphQL error twenty seconds in. In a Rush sandbox the agent runs `gatsby build` and `gatsby serve` on a clean checkout, reads the errors, fixes the type or the query and builds again, and the laptop stays free.

The result carries its proof. The pull request holds the files, and the transcript holds the build output and the fetched routes beside the commands that produced them, so a reviewer sees that `/tags/` rendered rather than reading that it should. A second issue, for category pages or a tag feed, is a second sandbox and a second pull request at the same time.

## Frequently asked questions

### Do my existing posts need tags for the build to pass?

No. The agent adds `tags: [String]` to the `Frontmatter` type in `createSchemaCustomization`, so a post without the field reads as `null` and the grouped query simply skips it. Only the posts the agent tags appear on a tag page. The starter already uses this pattern so that `description` can be missing without breaking `blog-post.js`.

### Does it add a dependency for the tag slugs?

No. The starter's only dev dependency is `prettier`, and the agent keeps it that way with a short slug helper in `gatsby-node.js` that lowercases the tag and replaces runs of non-alphanumeric characters with a hyphen. If you already use lodash elsewhere, the prompt can ask for its `kebabCase` instead.

### What happens to the RSS feed?

Nothing changes in `gatsby-config.js`. The `gatsby-plugin-feed` query selects `title`, `date`, `excerpt` and `html` and does not touch `tags`, so `/rss.xml` renders as before; the agent fetches it from `gatsby serve` to confirm. Adding each tag as a `category` element to the feed is a one-line follow-up if you want it.

### Why are there no checks on the pull request?

Because the starter ships without a workflow and its `test` script exits 1 by design. The run's trajectory keeps the `gatsby build` output and the fetched routes, which is what a check would have shown. If the issue asks for it, the agent can add a workflow that runs `npm ci` and `npm run build` on every pull request in the same change.

## More Gatsby jobs

- [Convert a Gatsby Site From JavaScript to TypeScript](https://getrush.ai/run/convert-javascript-to-typescript/gatsby/)
- [Migrate a Gatsby Blog from Markdown to MDX](https://getrush.ai/run/migrate-to-mdx/gatsby/)
- [Review Pull Requests on a Gatsby Site](https://getrush.ai/run/review-pull-requests/gatsby/)

## The same job on other stacks

- [Add Tag Pages to a Jekyll Blog](https://getrush.ai/run/add-tag-pages/jekyll/)

## More jobs like this: Turn a Linear label into a PR

- [Add Tailwind CSS to a Leptos App](https://getrush.ai/run/add-tailwind/leptos/)
- [Add TanStack Query to an Expo App](https://getrush.ai/run/add-tanstack-query/expo/)

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