GitHub Actions CI/CD Best Practices

Build robust, secure, and efficient CI/CD pipelines using GitHub Actions.

Quick Reference

Topic	Reference
Security	Secrets, OIDC, least privilege, SAST, SCA, secret scanning
Optimization	Caching, matrix strategies, self-hosted runners, artifacts
Testing	Unit, integration, E2E, performance, test reporting
Deployment	Staging, production, blue/green, canary, rollback
Review Checklist	Comprehensive workflow review checklist
Troubleshooting	Common issues and fixes

Workflow Structure

Naming: Use descriptive file names (build-and-test.yml, deploy-prod.yml).

Triggers (on): push, pull_request, workflow_dispatch (manual), schedule (cron), repository_dispatch (external), workflow_call (reusable).

Concurrency: Prevent simultaneous runs for specific branches/groups:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Permissions: Define at workflow level, override at job level. Default to least privilege:

permissions:
  contents: read

Reusable workflows: Use workflow_call to abstract common CI/CD patterns across projects.

Jobs

Jobs represent distinct pipeline phases: build, test, lint, deploy
Use needs for dependencies between jobs
Use outputs to pass data between jobs
Use if for conditional execution

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact_path: ${{ steps.package.outputs.path }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci && npm run build
      - id: package
        run: |
          zip -r dist.zip dist
          echo "path=dist.zip" >> "$GITHUB_OUTPUT"
      - uses: actions/upload-artifact@v3
        with:
          name: app-build
          path: dist.zip

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: app-build
      - run: echo "Deploying ${{ needs.build.outputs.artifact_path }}"

Steps and Actions

Version pinning: Pin actions to commit SHA or major version tag (@v4). Never use main or latest.
Descriptive names: Every step needs a clear name for log readability.
Multi-line scripts: Use | for complex commands, combine with && for efficiency.
Audit actions: Prefer actions from actions/ org. Use Dependabot for version updates.

Key Patterns

Secret management

env:
  API_KEY: ${{ secrets.API_KEY }}

Never hardcode secrets. Use environment-specific secrets for deployment.

OIDC cloud authentication

Use short-lived credentials instead of stored access keys:

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::role/deploy
    aws-region: us-east-1

Caching dependencies

- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: ${{ runner.os }}-node-

Matrix testing

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18.x, 20.x]

Fast checkout

- uses: actions/checkout@v4
  with:
    fetch-depth: 1  # Shallow clone for speed

Deployment Types

Strategy	When to use
Rolling	Default, stateless apps. Configure `maxSurge`/`maxUnavailable`
Blue/Green	Zero-downtime, instant rollback. Two identical environments
Canary	Controlled blast radius. Route 5-10% traffic to new version
Dark Launch	Decouple deploy from release. Feature flags control exposure

Troubleshooting

Common issues: workflow not triggering (check on triggers, if conditions, concurrency), permission errors (check permissions block, secret access), cache misses (validate keys with hashFiles), long runtimes (profile steps, add caching, parallelize with matrix).

See Troubleshooting for detailed fixes.

github-actions