# Add a GitHub Pages Deploy Workflow to a Starlight Docs Site

Yes. An agent sets site and base in astro.config.mjs, commits a lockfile, adds a workflow on withastro/action and deploy-pages, previews it and opens a PR.

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

## What the agent does

The agent reads the Astro config before touching CI, because a Starlight site deploys to GitHub Pages fine and then serves every stylesheet from the wrong path if `base` is missing. In a site laid out like the `examples/basics` project in withastro/starlight, `package.json` depends on `@astrojs/starlight` `^0.42.7`, `astro` `^7.2.10` and `sharp` `^0.35.3` with the `dev`, `build` and `preview` scripts and no lockfile committed, `astro.config.mjs` calls `starlight()` with a `title`, one `social` GitHub link and a `sidebar` of a `Guides` group naming `guides/example` and a `Reference` group that autogenerates from `src/content/docs/reference`, and sets neither `site` nor `base`. `src/content.config.ts` wires `docsLoader()` and `docsSchema()`, the content is `index.mdx` with a splash hero whose first action links to `/guides/example/`, plus one guide and one reference page, and `.gitignore` already excludes `dist/` and `.astro/`. There is no `.github` directory.

Two config values decide whether the deployed site works. For a project repository the site is served at `https://<owner>.github.io/<repo>/`, so the agent reads the repository name from the clone's `origin` and sets `site` to `https://<owner>.github.io` and `base` to `/<repo>`; a repository named `<owner>.github.io` needs no `base`, and a custom domain gets a one-line `public/CNAME` file, `site` set to that domain and no `base`. `site` also matters because Starlight adds `@astrojs/sitemap` to the build unless one is already present, and a sitemap needs an absolute origin. Starlight prefixes its own sidebar links, assets and search index with `base` through its `pathWithBase` helper, but the hero `link` in `index.mdx` is written as a root-relative path, so the agent runs `astro preview` after the build and prefixes that link if it answers `404` under the base.

The workflow goes in `.github/workflows/deploy.yml` with two jobs. `build` runs on pushes to the default branch and on `workflow_dispatch`, checks out with `actions/checkout@v7` and runs `withastro/action@v6`, which installs with the package manager it detects from the lockfile, defaults to Node 24, runs the `build` script and uploads `dist` as the Pages artifact; the agent passes no inputs because the site lives at the repository root and builds with the default command. `deploy` needs `build`, runs in the `github-pages` environment and calls `actions/deploy-pages@v5`. The permissions block grants `contents: read`, `pages: write` and `id-token: write`, and a `concurrency` group on `pages` with `cancel-in-progress: false` stops two pushes from racing a deployment. Because the action reads the lockfile to choose npm, pnpm, yarn or bun, the agent runs `npm install` once and commits the `package-lock.json` it produces; the `postinstall`-free `package.json` makes that the only change to dependencies.

Pull requests get a build check from the same file: a `pull_request` trigger is added and the `deploy` job carries `if: github.event_name == 'push'`, so a contributor's change proves it builds without touching the live site. The agent runs `npm run build` in its sandbox with the new config and reads the `dist` tree to confirm the `pagefind` index that Starlight writes at build time landed under the base path, then `npm run preview` and `curl -sI` on the home page, the guide page and `pagefind/pagefind.js` to show each answers `200`. One step stays with a person: in the repository's Settings, Pages, the Source must be set to GitHub Actions before the first deployment, and the pull request says so in its first line.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a GitHub Pages deploy workflow to this Starlight documentation site. Read package.json, astro.config.mjs, src/content.config.ts, src/content/docs/index.mdx, .gitignore and the git remote first. Set site and base in astro.config.mjs for this repository's GitHub Pages URL, using no base if the repository is named owner.github.io or a public/CNAME file exists. Run npm install once and commit the lockfile so withastro/action can detect the package manager. Add .github/workflows/deploy.yml with a build job on actions/checkout and withastro/action that also runs on pull requests, and a deploy job on actions/deploy-pages that runs only on pushes to the default branch, with the pages, id-token and contents permissions and a pages concurrency group. Run npm run build, check the pagefind index is under the base path, run npm run preview and curl the home page, the example guide and pagefind.js under the base, fixing the hero link in index.mdx if it does not resolve. Open a pull request whose first line says that Pages Source must be set to GitHub Actions in the repository settings.",
  "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/deploy.yml` and `package-lock.json` and changes `astro.config.mjs` for `site` and `base`, plus `src/content/docs/index.mdx` when the hero link needed the prefix. The description opens with the Pages Source setting a person has to change, then pastes the `astro build` summary with the page count, the three `curl -sI` status lines from `astro preview` and the `dist` listing showing `pagefind/` under the base.

The `build` job runs on the pull request itself, so a reviewer sees the site build on GitHub's runner with the committed lockfile before merging, and the `deploy` job stays skipped until the merge. The run's record keeps the `npm install`, the build and every `curl`, so a reviewer can match each status line to its request.

Before merging, a reviewer confirms the `base` matches the repository name they intend to keep, decides whether Node 24 from the action's default is what the team wants pinned through the `node-version` input, and chooses whether `workflow_dispatch` should stay. The agent changes no content apart from the one hero link.

## Run it on every new documentation repository

A team that starts documentation sites from one Starlight template starts one run per new repository from its own server: one `POST /o/{org}/sessions` with the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own remote, so a repository named `<owner>.github.io` gets `site` without `base`, and one with a `CNAME` already in `public` gets its domain as `site`.

After that, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds a page or an asset with a root-relative link, check it resolves under the site's base and say so in a comment" catches the one class of link Starlight does not rewrite. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

## Why run it on Rush?

A Pages workflow that is copied from a template deploys a site that looks broken for a reason nobody sees in the diff: a missing `base` makes every stylesheet and the search index load from the site root, a missing lockfile makes the action guess the package manager, and a hero link written for `localhost` answers `404` on `github.io`. The agent builds the real site in its sandbox, serves it under the base with `astro preview` and reads the real status codes before it opens the pull request.

Every command stays with the run, from `npm install` to each `curl -sI`, and the pull request quotes them. Setting up a dozen documentation repositories the same way costs no more attention than one, because each run has its own machine, its own record and its own pull request.

## Frequently asked questions

### Why does the workflow need a committed lockfile?

Because `withastro/action` picks npm, pnpm, yarn or bun from the lockfile it finds and installs with it; without one it falls back to a default that may not match what the team uses locally. The `basics` example ships without a lockfile, so the agent runs `npm install` once and commits `package-lock.json`, or `pnpm install` if the team says so in the prompt. The action's `package-manager` input exists for the case where a lockfile cannot be committed.

### Does every link in my docs need the base prefix now?

No. Starlight builds sidebar entries, the search index, assets and the links its components render through its `pathWithBase` helper, so the `sidebar` config in `astro.config.mjs` and `slug` references work unchanged. A root-relative `href` written by hand in Markdown or in a hero `link` does not get the prefix, which is why the agent previews under the base and fixes the one in `index.mdx` if it fails. Astro's `import.meta.env.BASE_URL` is the value to use in any custom component.

### Can the agent set the Pages source to GitHub Actions for me?

No. That setting lives in the repository's Settings, Pages page and needs a person with admin rights on github.com, so the pull request puts it in its first line. Until it is set, the `deploy` job fails with a message that says Pages is not enabled, and the `build` job still proves the site compiles.

### What happens on pull requests?

The `build` job runs and uploads the artifact, so the check shows whether the site still builds with the change; the `deploy` job is skipped by its `if` on the event name, so the live site changes only on a push to the default branch. A team that wants preview deployments per pull request needs a host that serves them, which GitHub Pages does not.

## More Starlight jobs

- [Add Giscus Comments to a Starlight Site](https://getrush.ai/run/add-giscus-comments/starlight/)
- [Add i18n to a Starlight Docs Site](https://getrush.ai/run/add-i18n/starlight/)
- [Check for Broken Links in a Starlight Docs Site](https://getrush.ai/run/add-link-checking/starlight/)

## The same job on other stacks

- [Add a GitHub Pages Deploy Workflow to an Eleventy Site](https://getrush.ai/run/add-deploy-workflow/eleventy/)
- [Deploy Firebase Functions from GitHub Actions](https://getrush.ai/run/add-deploy-workflow/firebase-functions/)
- [Add a GitHub Pages Deploy Workflow to a Hugo Site](https://getrush.ai/run/add-deploy-workflow/hugo/)

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