← Back to insights
deploygithubci

Deploying Astro with GitHub Actions

How lint, build, and deploy work with GitHub Pages, Netlify, or Vercel.

Every push to main can go from commit to live site without a manual deploy step. This template supports GitHub Pages, Netlify, and Vercel — pick one host (see the README Hosting options section).

What runs in CI

On every push to main, GitHub Actions:

  1. Lint — astro check and tsc --noEmit
  2. Build — npm run build with ASTRO_SITE and ASTRO_BASE set for your URL
  3. Deploy — uploads dist/ to GitHub Pages when Pages is enabled

Pull requests run lint only — fast feedback without publishing.

GitHub Pages

  1. Go to Settings → Pages
  2. Set Source to GitHub Actions
  3. Push to main

For a project site at https://username.github.io/repo-name/, set ASTRO_BASE=/repo-name/ when building.

Netlify or Vercel

Connect your repo to Netlify or Vercel. Both detect Astro and use npm run build → dist/. Set ASTRO_SITE to your production URL in the host’s environment variables.

netlify.toml and vercel.json are included in the template.

Verify locally first

npm ci
npm run check
npm run build
npm run preview

If CI fails, reproduce with these commands, fix, and push again. Claude can read Action logs via gh run view --log if you use the GitHub CLI.