GitHub Actions Templates

When to Use

• CI/CD pipeline setup for any stack
• Automated testing with matrix builds
• Docker image builds and registry pushes
• Security vulnerability scanning
• Reusable workflow patterns for monorepos
• Deployment pipelines with approval gates

When NOT to Use

• GitLab CI, CircleCI, or Jenkins pipelines (different syntax and runners)
• Simple scripts that run locally without CI benefit
• One-off manual deployments (use gh CLI instead)
• Infrastructure provisioning (use Terraform/Pulumi, not GHA)

Quick Decision Tree

Read the matching reference file, then adapt it using references/adaptation-guide.md for the user's stack.

Core Patterns

1. Test Workflow

Runs lint, tests, and coverage on push and PR. Default: Node.js with npm.

Full template with adaptation comments: references/test-workflow.yml

2. Docker Build and Push

Builds a Docker image, tags with semver metadata, pushes to GHCR. Uses layer caching.

Full template with registry switching comments: references/deploy-workflow.yml

3. Matrix Build

Tests across multiple OS and language versions. Default: Python cross-platform.

Full template with Bun/Go/Rust/Node adaptation: references/matrix-build.yml

4. Security Scanning

Runs Trivy filesystem scan and Snyk dependency check. Uploads results to GitHub Security tab.

Full template with weekly schedule and Snyk: references/security-scan.yml

5. Reusable Workflows

Share workflow logic across repositories with workflow_call trigger.

Caller: .github/workflows/ci.yml

jobs: test: uses: ./.github/workflows/reusable-test.yml with: node-version: "22.x"

</example>

Full caller/callee examples: `references/common-workflows.md`

### 6. Monorepo Orchestration
Path filters trigger only affected packages. Turbo runs selective tasks.

<example>
```yaml
on:
  push:
    paths: ['packages/api/**', 'packages/shared/**']
jobs:
  test:
    steps:
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun turbo test --filter=...[origin/main]

Full monorepo patterns with Bun + Turbo: references/common-workflows.md

Do / Don't / Why

See references/anti-patterns.md for detailed before/after examples of each mistake.

Feedback Loops

Deployment Verification

1. Run health check after deploy: curl -f $APP_URL/health
2. On failure: roll back (kubectl rollout undo or SST rollback)
3. Notify team via Slack on success or failure
4. Block next deploy until current one passes

Test Verification

1. Fail the workflow if coverage drops below threshold
2. Upload test artifacts on failure for debugging
3. Require all matrix combinations to pass (set fail-fast: false)

Version Currency

Action versions in reference files are current as of February 2026. Check for updates:

gh api repos/OWNER/REPO/releases/latest --jq '.tag_name'

Adaptation Workflow

When generating a workflow for the user:

1. Read the matching reference file from the decision tree above
2. Read references/adaptation-guide.md for the user's tech stack
3. Apply the adaptation changes (package manager, test runner, registry)
4. Remove unused # ADAPT: comments from the final output
5. Verify all action versions match the reference files

References

• references/test-workflow.yml — Test workflow with CI steps
• references/deploy-workflow.yml — Docker build-and-push to GHCR
• references/matrix-build.yml — Cross-platform matrix build
• references/security-scan.yml — Trivy + Snyk security scanning
• references/common-workflows.md — Reusable workflows, approvals, Slack, monorepo
• references/anti-patterns.md — 8 common mistakes with fixes
• references/adaptation-guide.md — Per-stack customisation (Bun, Node, Python, Go, Docker registries)