GitHub Actions Builder

---
name: github-actions-builder
description: |
  Trigger when the user asks to write a GitHub Actions workflow, set up CI,
  run tests on PR, or automate a release. Phrases: "GitHub Actions",
  "workflow", "CI/CD", "run tests on PR", "release automation".
allowed-tools:
  - Read
  - Write
  - Grep
---

# GitHub Actions Builder

Write a minimum-viable, efficient GitHub Actions workflow. Focus on correctness,
cache reuse, and not burning minutes.

## Prerequisites

- Repo hosted on GitHub
- Project has a test command or build command worth running

## Steps

1. **Start with a small workflow.** Don't try to build the full matrix on
   day one. Get one job working on push + PR.

   ```yaml
   name: CI
   on:
     push:
       branches: [main]
     pull_request:
   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: pnpm/action-setup@v4
           with: { version: 10 }
         - uses: actions/setup-node@v4
           with:
             node-version: 20
             cache: pnpm
         - run: pnpm install --frozen-lockfile
         - run: pnpm test
   ```

2. **Enable caching on everything.** `cache: pnpm` (or `npm` / `yarn`) on
   setup-node is non-negotiable. Every workflow run without cache is minutes
   wasted.

3. **Concurrency control.** Cancel in-progress runs for the same PR when
   new commits arrive:
   ```yaml
   concurrency:
     group: ${{ github.workflow }}-${{ github.ref }}
     cancel-in-progress: true
   ```

4. **Separate jobs that can parallelize.** Typecheck, lint, test, build —
   each in its own job with its own dependencies. One red job doesn't
   block the others; you get parallel feedback.

5. **Use reusable workflows** for shared logic across repos. Don't copy-paste
   the same install steps into 8 workflow files.

6. **Pin versions.** `actions/checkout@v4` is pinned; `actions/checkout@main`
   is a supply-chain risk.

## Patterns worth knowing

- **Matrix builds** for multi-version testing (Node 18/20/22, Python 3.10/3.11/3.12)
- **Release on tag push:** `on: push: tags: ['v*']`
- **Scheduled runs:** `on: schedule: cron: '0 7 * * 1'` for weekly
- **Path filters:** `paths: ['src/**']` to skip docs-only changes

## Anti-patterns

- Single monolithic job that does install, lint, test, build, deploy
- Not using the language's built-in cache
- Secrets in plaintext (always `secrets.FOO`)
- Running e2e on every PR when they take 20 minutes; run on main only

## Output

- `.github/workflows/ci.yml` committed
- Workflow runs green on a test PR
- Wall time under 3 minutes for a typical run