GitHub Actions CI/CD Agent Rules
Project Context
You are building GitHub Actions workflows for continuous integration and deployment. Workflows live in `.github/workflows/` and must be fast, secure, and cost-efficient.
Workflow Structure
- Name workflows clearly: the `name:` field describes purpose, not the trigger — `"CI"` not `"on push"`.
- Separate CI (lint, test, build) and CD (deploy) into distinct workflow files.
- Use specific triggers with path filters to avoid unnecessary runs: `on: push: paths: ["src/**", "package.json"]`.
- Set `concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true` to cancel redundant branch runs.
- Set `timeout-minutes:` on every job — a reasonable default is 15 minutes; increase only when justified.
- Pin runner images: use `ubuntu-22.04` over `ubuntu-latest` for reproducibility.
- Use `if:` conditions to skip unnecessary jobs: skip deploy on draft PRs with `if: github.event.pull_request.draft == false`.
Security & Permissions
- Set `permissions: contents: read` at the workflow level as the default — grant additional permissions per-job only.
- Pin all third-party actions to a full commit SHA, not a tag: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`.
- Enable Dependabot for GitHub Actions (`dependabot.yml` with `package-ecosystem: github-actions`).
- Use OIDC (`permissions: id-token: write`) for cloud authentication instead of long-lived credentials stored as secrets.
- Never use `pull_request_target` trigger with `actions/checkout` of the PR head — this is a supply chain attack vector.
- Use `${{ secrets.TOKEN }}` never `${{ env.TOKEN }}` for secret injection — env vars are logged more easily.
Caching
- Use `actions/setup-node` with `cache: "pnpm"` (or `npm`/`yarn`) for automatic dependency caching.
- Use `actions/cache` for custom paths: `key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}`.
- Include OS and architecture in cache keys: `${{ runner.os }}-${{ runner.arch }}-...`.
- Use `restore-keys:` as a fallback pattern when the exact key misses: `restore-keys: ${{ runner.os }}-cargo-`.
- Cache Docker layers with `cache-from: type=gha` and `cache-to: type=gha,mode=max` in `docker/build-push-action`.
Matrix Builds
- Use `strategy.matrix` to test across OS, language versions, or configurations.
- Use `include:` and `exclude:` to limit the matrix to meaningful combinations only.
- Set `fail-fast: false` when you want all matrix jobs to complete to see the full failure picture.
- Keep matrix dimensions small — prefer targeted coverage over exhaustive permutations.
Reusable Workflows & Composite Actions
- Extract shared multi-job logic into reusable workflows with `on: workflow_call:` triggers.
- Use composite actions in `.github/actions/<name>/action.yml` for multi-step sequences reused across workflows.
- Define explicit `inputs:` and `outputs:` on reusable workflows and actions with `description:` and `required:` fields.
- Use `secrets: inherit` cautiously — prefer explicitly passing only the required secrets via `secrets:` mapping.
- Prefer composite actions over Docker container actions for speed unless containerization is required.
Docker Integration
- Use `docker/setup-buildx-action` and `docker/build-push-action` for all Docker image builds.
- Build multi-platform images with `platforms: linux/amd64,linux/arm64` using QEMU emulation.
- Push to GitHub Container Registry `ghcr.io/${{ github.repository }}` using `GITHUB_TOKEN` — no extra credentials needed.
- Tag images with `${{ github.sha }}` for traceability and semantic version tags for releases.
- Scan images in CI with `aquasecurity/trivy-action` or `docker/scout-action` before pushing to production.
Environments & Deployments
- Define environments in repository settings (Settings > Environments) with protection rules.
- Require manual approval for production deployments using environment reviewers.
- Restrict which branches can deploy to production via deployment branch policies.
- Use environment-scoped secrets and variables to separate configuration between staging and production.
- Reference environments in workflow jobs with `environment: production` to unlock secrets and trigger audit logging.
Debugging & Monitoring
- Set the `ACTIONS_STEP_DEBUG` repository secret to `true` to enable verbose runner logging for troubleshooting.
- Use `actions/upload-artifact` to persist test reports, logs, and screenshots from failed runs.
- Add `::add-mask::$SECRET_VALUE` in scripts to prevent dynamic values from leaking into logs.
- Monitor workflow run duration and failure rates via the Actions tab insights page.
- Use `act` (local GitHub Actions runner) for iterating on workflow changes without pushing every attempt.
YAML/
GitHub Actions