All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading