Astro GitHub Actions

This skill helps you set up a comprehensive CI/CD pipeline for Astro sites using GitHub Actions. The goal is to help authors ship higher-quality sites with less manual effort: type errors caught before merge, broken links flagged, builds verified, and deploys automated.

What this skill covers

There are several categories of workflows that a healthy Astro project should have. Not every site needs all of them — the right mix depends on whether the project has TypeScript, custom components, content collections, tests, and where it deploys. Your job is to figure out which ones are relevant and set them up.

The workflows fall into these categories:

1. Type/content checking — astro check (TypeScript + content collection schema validation)
2. Code quality — ESLint and Prettier
3. Build verification — astro build runs cleanly
4. Testing — Vitest for unit and component tests
5. Quality gates — Lighthouse CI (performance, a11y, SEO, best practices)
6. Link checking — broken-link detection on the built site
7. Security — npm audit for dependency vulnerabilities
8. Deployment — GitHub Pages, Cloudflare Pages, Netlify, or Vercel

Read references/workflows.md for the detailed configuration of each workflow, including ready-to-use YAML templates and configuration files.

How to approach a request

Step 1: Understand the project

Before writing any workflow files, figure out what you're working with:

• Is it TypeScript? Check for tsconfig.json and .ts/.astro files. Almost every Astro project should run astro check, but the value is highest when there's TypeScript in .astro frontmatter, content collection schemas, or src/.
• Does it use content collections? Check for src/content/config.ts or src/content.config.ts. If yes, astro check validates the schemas — extra valuable.
• Does it have tests? Check for tests/, __tests__/, *.test.ts, or vitest.config.ts. If yes, set up the Vitest workflow. If not, mention that adding tests would be valuable but don't force it.
• What's the package manager? Look for pnpm-lock.yaml, yarn.lock, or package-lock.json. Match the workflow's install command (pnpm i --frozen-lockfile, yarn install --frozen-lockfile, or npm ci).
• Where does it deploy? Look for a wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel), or just ask. Most hosts have their own GitHub app that auto-deploys without Actions — only set up a deploy workflow if the user actually wants Actions to handle it (typically GitHub Pages or self-hosted).
• Does it have a build step? Astro always does (astro build) — but verify the script in package.json is the standard astro build and not something custom.
• Is it SSR or static? Check astro.config.* for an output: 'server' or an adapter import. SSR projects deploy differently (Cloudflare/Netlify/Vercel adapters) and may not be deployable to GitHub Pages at all.

Step 2: Recommend a set of workflows

Based on what you found, recommend which workflows to set up. A good default for most Astro sites:

• astro check (almost always — this is the most valuable check for Astro)
• Build verification (almost always — catches integration regressions astro check can miss)
• ESLint + Prettier (if config files exist or the user wants them)
• Lighthouse CI (great for content sites with public URLs)
• Link checker (great for content-heavy sites)
• npm audit (cheap, almost always worth it)

And conditionally:

• Vitest tests (if tests exist)
• Deploy workflow (only if the user wants Actions-driven deploys — most Astro hosts use their own GitHub app)

Step 3: Create the workflow files

Create each workflow as a separate YAML file in .github/workflows/. Using separate files rather than one monolithic workflow gives clearer feedback in PRs (each check shows independently) and makes it easier to enable/disable individual checks.

Use the templates from references/workflows.md as starting points, but adapt them to the specific project. Common adaptations include adjusting the package manager, the Node version, the build artifact path, and the deploy target.

Step 4: Create supporting config files

Depending on which workflows you set up, you may also need:

• eslint.config.js — ESLint flat config with eslint-plugin-astro
• .prettierrc and .prettierignore — Prettier config with prettier-plugin-astro
• lighthouserc.json — Lighthouse CI assertions
• lychee.toml — link checker config (if using lychee)
• vitest.config.ts — Vitest configuration

Step 5: Set up secrets reminder

If you're adding a deploy workflow, remind the user which repository secrets are needed:

• GitHub Pages — none (uses GITHUB_TOKEN)
• Cloudflare Pages — CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

Walk them through: Repository Settings > Secrets and variables > Actions > New repository secret.

For Cloudflare, Netlify, and Vercel: also remind them that those platforms ship their own GitHub apps that handle build + deploy + PR previews automatically. Actions-based deploys are usually only worth it when you need to gate the deploy on test results, run a build with secrets the platform doesn't have, or deploy from a path other than the repo root.

Naming conventions

Use descriptive workflow file names that make it obvious what each one does:

• astro-check.yml — astro check (type + content schema)
• lint.yml — ESLint
• format.yml — Prettier check
• build.yml — Build verification
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — Broken link checker
• security.yml — npm audit
• deploy.yml — Deploy to host

Important details

Node.js version: Astro requires Node 18.20.8+, 20.3.0+, or 22.0.0+. Use Node 22 as the default — it matches Astro's stable target and many adapters are tested against it. Use actions/checkout@v5 and actions/setup-node@v5.

Package manager detection: Always match the lockfile. pnpm-lock.yaml → use pnpm/action-setup@v4 and pnpm install --frozen-lockfile. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. Don't use npm install in CI (non-deterministic, slower).

Branch naming: Most Astro repos use main as the default branch, but check the actual repo before writing triggers.

Astro adapters and SSR: If the project uses @astrojs/cloudflare, @astrojs/netlify, or @astrojs/vercel, the build output may not be a static dist/ directory. The Cloudflare adapter outputs dist/ plus a _worker.js; Vercel outputs .vercel/output/; Netlify outputs .netlify/. Adjust deploy artifact paths accordingly.

astro check requires @astrojs/check and typescript: Both must be installed. If they're not in devDependencies, the workflow will fail. Add them as part of npm ci only if they're already in package.json — otherwise the workflow should install them explicitly.

Lighthouse CI on PRs: Running Lighthouse on every PR catches performance regressions early. The treosh/lighthouse-ci-action is the standard. For a public preview URL (Cloudflare Pages, Netlify, Vercel), point Lighthouse at the deploy preview URL — that gives realistic numbers. For internal-only setups, build and serve locally inside the runner.

Link checking on built output, not source: Run the link checker on the built dist/ directory (or against a deployed preview URL) — running it on Markdown source misses generated routes and sitemap links.

Prefer the platform's GitHub app over Actions deploys: Cloudflare Pages, Netlify, and Vercel all have first-party GitHub apps that handle PR previews, branch deploys, and rollbacks better than a hand-rolled Action. Recommend the GitHub app first; only suggest an Actions deploy when the user has a specific reason to do it that way.