github-actions

When to Use

• Creating or editing GitHub Actions workflow files (.github/workflows/*.yml)
• Reviewing CI/CD pipelines for security, performance, or correctness
• Setting up automated testing, building, or deployment pipelines
• Troubleshooting failing or flaky GitHub Actions workflows
• Designing deployment strategies (staging, production, blue/green, canary)

Critical Patterns

• Pin Actions to Commit SHA: Always use full commit SHA, never mutable tags (@v4, @main). Add version as comment: uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1. Tags can be silently moved to compromised commits (supply chain attack).
• Least Privilege GITHUB_TOKEN: Set permissions: contents: read at workflow level. Grant write only where explicitly needed, per-job.
• Secrets via secrets Context Only: Never hardcode sensitive data. Use ${{ secrets.NAME }}. Use environment secrets for deployment targets with manual approvals.
• OIDC Over Static Credentials: Use OpenID Connect for cloud auth (AWS, Azure, GCP) instead of long-lived access keys.
• Cache Dependencies: Use actions/cache with hashFiles() keys for node_modules, pip, Maven, etc. to dramatically speed up builds.
• Shallow Clone: Use fetch-depth: 1 in actions/checkout unless full history is needed.
• Fail Fast on Security: Integrate dependency review and SAST (CodeQL) as blocking checks.
• Environment Protection: Use GitHub Environments with required reviewers and branch restrictions for staging/production deploys.

Workflow Structure

name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy target'
        required: false
        default: 'staging'
        type: choice
        options: [ staging, production ]

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

permissions:
  contents: read  # Least privilege default

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          fetch-depth: 1
      - uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
      - uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        if: always()
        with:
          name: test-results
          path: coverage/
          retention-days: 14

  build:
    runs-on: ubuntu-latest
    needs: test
    outputs:
      artifact_name: ${{ steps.package.outputs.name }}
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
      - uses: actions/setup-node@3235b876344d2a9aa001b8d1453c930bba69e610 # v3.9.1
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Package application
        id: package
        run: |
          zip -r dist.zip dist
          echo "name=dist.zip" >> "$GITHUB_OUTPUT"
      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: app-build
          path: dist.zip
          retention-days: 30

  deploy-staging:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: app-build
      - name: Deploy to staging
        env:
          DEPLOY_TOKEN: ${{ secrets.STAGING_DEPLOY_TOKEN }}
        run: |
          unzip dist.zip
          echo "Deploying to staging..."
          # ./deploy.sh --env staging