All jobs

Check for Broken Links in an Astro Site's CI

Yes. An agent adds a lychee step to your Astro CI that checks every link in the built site offline, moves external checks to a weekly job, 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 first learns how the site is built and checked today. In an Astro blog like satnaing/astro-paper, package.json names astro-paper-v6 at 6.1.0 on astro ^7.0.3 with @astrojs/sitemap, @astrojs/rss and pagefind, requires Node >=22.12.0, and its build script runs astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/. .github/workflows/ci.yml runs one job on every pull request with a three-minute timeout-minutes: pnpm/action-setup@v4 at 11.3.0, actions/setup-node@v4 on Node 24 with the pnpm cache, pnpm install --frozen-lockfile, then lint, format:check and build. The build produces dist/ and nothing reads it afterwards, so a post whose link points at a renamed slug ships green.

The site's own URLs tell the agent what a correct check looks like. astro-paper.config.ts sets site.url to https://astro-paper.pages.dev/, and src/layouts/Layout.astro writes a canonical <link>, og:url and the RSS autodiscovery link as absolute URLs on that host, while src/pages/robots.txt.ts points at sitemap-index.xml. So the agent adds a lycheeverse/lychee-action@v2 step after the build that runs --offline, with --root-dir set to dist so root-relative links such as /posts/... resolve against the build output, and --base-url set to the site URL from the config so absolute links to the site's own host are checked against dist too instead of over the network. The input is dist/**/*.html, and the step fails the job when a link has no file behind it.

External links get a different treatment, because a flaky third-party host should not block a pull request. The agent writes a second workflow, .github/workflows/links.yml, on a weekly schedule and workflow_dispatch, that builds once and runs lychee online with --cache and a --max-cache-age, uploads lychee's report as an artifact and prints it to the job summary. It also writes a .lycheeignore for addresses that are placeholders by design: astro-paper.config.ts lists socials at https://x.com/username and https://www.linkedin.com/in/username/ and share links such as https://wa.me/?text= that end in a query prefix, none of which should ever be fetched. .prettierignore ignores everything outside a short allowlist, so the new files pass format:check without an exemption.

Before opening the pull request the agent runs the real thing in the sandbox: pnpm install --frozen-lockfile, pnpm run build, then the offline lychee command against dist. If the first pass finds broken internal links, they go into the description with the file and the target, not silently into the ignore list. The agent also notes that drafts are not part of the check: src/utils/postFilter.ts leaves drafts such as src/content/posts/examples/example-draft-post.md out of a production build, so their links are never in dist.

Start it with one API call

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

{
  "agent": "codex",
  "input": "Add broken link checking to this Astro site's CI and open a pull request. Read package.json, .github/workflows/ci.yml, astro-paper.config.ts, src/layouts/Layout.astro, src/pages/robots.txt.ts and src/utils/postFilter.ts first. In ci.yml, after the build step, add a lycheeverse/lychee-action@v2 step that checks dist/**/*.html in --offline mode with --root-dir pointing at dist and --base-url set to the site URL from astro-paper.config.ts, failing the job on a broken internal link, and keep the job inside its existing timeout-minutes. Add a second workflow, .github/workflows/links.yml, on a weekly schedule and workflow_dispatch, that installs, builds and runs lychee online with --cache and --max-cache-age against dist, uploads lychee's report as an artifact and writes it to the job summary without failing the run. Add a .lycheeignore for the placeholder social and share-link URLs in astro-paper.config.ts and explain each entry. Run pnpm install --frozen-lockfile, pnpm run build and the offline lychee command in the sandbox and paste the summary in the pull request, listing any broken internal link you found with its page and target rather than ignoring it. Do not change the build script, the content or the existing lint and format steps.",
  "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 with one new step in .github/workflows/ci.yml, a new .github/workflows/links.yml, and a .lycheeignore whose entries are each explained in the description. The description carries the lychee summary from the sandbox build, the count of links checked and any internal link that resolved to no file in dist, named by page and target.

The existing job runs on the pull request itself, so the new offline step gives its first verdict there, inside the three-minute timeout the job already has. The weekly job has no run yet to show; its first report appears as an artifact and a summary the Monday after merge, or sooner if someone triggers it by hand.

A reviewer checks that the offline step sees the same dist the build produced, that .lycheeignore holds only intentional placeholders and not a real link somebody meant to fix, and that the weekly job cannot block a pull request. Then they decide whether the broken links the description lists are fixed in this pull request or a follow-up.

Run it on every new content site

A team with several documentation or blog repositories sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own build script and workflow, so a site that deploys from main without a pull request job gets the check added where its build already runs, and a site with a different output directory gets --root-dir pointed at that. Each run opens its own pull request.

Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request and the pasted lychee summary from, so the broken links each site already has can be triaged in one place.

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

Why run it on Rush?

Link checks are easy to add badly: online by default, failing on a rate-limited host, or pointed at the source Markdown instead of the HTML a visitor actually gets. In a Rush sandbox the agent runs the real build and the real check against dist, and the output of every command is kept in the run, so the pull request shows which links were checked and what was found rather than promising it.

Because the sandbox is the agent's own machine, the full pnpm install and astro build with pagefind indexing run without touching anyone's laptop, and the same request can go to every content repository at once. The result is a check that fails for the right reason on the next renamed post, not a green badge.

Frequently asked questions

Why run offline on pull requests?

Because a pull request should fail only for something the author can fix. --offline checks every link whose target should be a file in dist, including absolute links to the site's own host thanks to --base-url, and skips everything else. External hosts are checked weekly, where a transient failure costs nothing.

Does it check the RSS feed and the sitemap?

The pull request step checks dist/**/*.html. rss.xml and sitemap-index.xml are generated by @astrojs/rss and @astrojs/sitemap from the same pages, so their URLs are the pages already being checked; the description says how to add them to the glob if you want them covered directly.

What about links in draft posts?

They are not checked. src/utils/postFilter.ts excludes drafts from a production build, so a draft never reaches dist. The moment a post is published its links are part of the next check.

Will it slow the pull request job down?

The job keeps its timeout-minutes: 3. An offline check of the built HTML is fast because no network is involved; the agent runs it in the sandbox and reports how long it took there, and the step shows its own duration in the Actions log.

Why a .lycheeignore at all?

The theme ships placeholder social URLs like https://x.com/username and share links that end in ?text= or ?url=, which are templates rather than destinations. Listing them with a comment keeps the weekly report about real links; anything else that fails is reported, not hidden.

More Astro jobs

The same job on other stacks

Keep reading