The Ultimate GitHub Actions & CI/CD Cheatsheet

# ── Basic CI Workflow ──
name: CI Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

# Environment variables at workflow level
env:
  NODE_VERSION: "20"
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# Permissions
permissions:
  contents: read
  packages: write

# Concurrency — cancel in-progress runs
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    timeout-minutes: 30

    # Job-level environment
    environment: staging

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0    # Full git history
          lfs: true         # Git LFS support
          submodules: recursive

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linting
        run: npm run lint

      - name: Run type check
        run: npm run type-check

      - name: Run tests
        run: npm test -- --coverage

      - name: Build
        run: npm run build

      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/
          retention-days: 7

# ── Push Triggers ──
on:
  push:
    branches:
      - main
      - 'releases/**'          # Glob pattern
      - '!dev-branch'           # Exclude
    tags:
      - 'v*'                    # All version tags
    paths:
      - 'src/**'
      - 'package.json'
      - '.github/workflows/**'
      - '!README.md'            # Exclude

# ── Pull Request Triggers ──
on:
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches: [main]
    paths:
      - 'src/**.ts'

# ── Schedule (Cron) ──
on:
  schedule:
    - cron: '0 6 * * 1-5'    # 6 AM UTC, weekdays only
    - cron: '0 0 1 * *'      # Monthly on 1st

# ── Workflow Dispatch (manual trigger) ──
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false
      version:
        description: 'Version to deploy'
        required: false
        type: string

# ── Multiple Triggers ──
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:     # Manual trigger as well
  schedule:
    - cron: '0 6 * * *'  # Plus nightly build

# ── Job Configuration ──
jobs:
  # Job 1: Build
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    needs: [lint]                # Run after lint job
    if: github.event_name == 'push'  # Conditional execution
    outputs:
      artifact-name: ${{ steps.meta.outputs.name }}  # Job outputs
    environment: staging           # Deployment environment
    continue-on-error: false       # Don't fail workflow if this fails
    concurrency:
      group: deploy-staging
      cancel-in-progress: true

    steps:
      # Checkout
      - uses: actions/checkout@v4

      # Run shell commands
      - name: Install deps
        run: npm ci

      - name: Run multi-line script
        run: |
          echo "Building project..."
          npm run build
          echo "Build complete!"
          ls -la dist/

      # Step with environment
      - name: Set env vars for step
        env:
          DATABASE_URL: postgres://localhost/mydb
          NODE_ENV: test
        run: npm test

      # Conditional step
      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: npm run deploy

      # Step that produces output
      - name: Set metadata
        id: meta
        run: echo "name=production-build-${{ github.sha }}" >> $GITHUB_OUTPUT

      # Step that always runs (even on failure)
      - name: Cleanup
        if: always()
        run: rm -rf node_modules

  # Job 2: Deploy (depends on build)
  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: needs.build.result == 'success'
    steps:
      - name: Deploy to production
        run: echo "Deploying artifact: ${{ needs.build.outputs.artifact-name }}"

# ── GitHub-Hosted Runners ──
jobs:
  ubuntu:
    runs-on: ubuntu-latest          # Ubuntu 22.04
    # ubuntu-22.04, ubuntu-20.04

  windows:
    runs-on: windows-latest          # Windows Server 2022
    # windows-2022, windows-2019

  macos:
    runs-on: macos-latest            # macOS 14 (M1)
    # macos-14, macos-13, macos-12

  # Specific version
  specific:
    runs-on: ubuntu-22.04

  # ── Self-Hosted Runner (requires setup) ──
  self-hosted:
    runs-on: [self-hosted, linux, x64]
    # Labels: self-hosted, linux, macos, windows,
    #         x64, arm64, gpu

  # ── Larger Runner (more resources) ──
  large:
    runs-on: ubuntu-latest-4-cores   # 4 cores, 16 GB RAM
    # ubuntu-latest-8-cores, ubuntu-latest-16-cores

# ── Cache Dependencies ──
steps:
  # Auto-caching with setup-node
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'            # Automatically caches npm

  # Manual cache
  - uses: actions/cache@v4
    with:
      path: |
        ~/.npm
        node_modules
      key: npm-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        npm-

  # Cache pip (Python)
  - uses: actions/cache@v4
    with:
      path: ~/.cache/pip
      key: pip-${{ hashFiles('requirements.txt') }}

  # Cache Docker layers
  - uses: actions/cache@v4
    with:
      path: /tmp/.buildx-cache
      key: buildx-${{ github.sha }}
      restore-keys: buildx-

  # ── Artifacts (share data between jobs) ──
  - name: Upload build artifact
    uses: actions/upload-artifact@v4
    with:
      name: build-output
      path: dist/
      retention-days: 5
      if-no-files-found: error
      compression-level: 6

  - name: Download artifact in another job
    uses: actions/download-artifact@v4
    with:
      name: build-output
      path: dist/
      github-token: ${{ secrets.GITHUB_TOKEN }}

# ── Using Secrets ──
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Access repository secrets
      - name: Deploy with secret
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: aws s3 sync dist/ s3://my-bucket/

      # Access organization secrets
      - name: Use org secret
        env:
          API_KEY: ${{ secrets.ORG_API_KEY }}
        run: make deploy

      # Access environment secrets (higher priority)
      - name: Use environment secret
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}  # From environment
        run: echo "Using deploy key"

      # Pass secret to action
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

  # ── Secrets Scopes ──
  # Repository secrets: available in all workflows of the repo
  # Environment secrets: available only when targeting that environment
  # Organization secrets: available in all repos of the org
  # Variables (non-secret): available via vars context

# ── Basic Matrix ──
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci && npm test

# ── Multi-Dimension Matrix ──
  test-full:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20]
        os: [ubuntu-latest, windows-latest, macos-latest]
        # Exclude specific combinations
        exclude:
          - os: windows-latest
            node-version: 18
        # Include additional combinations
        include:
          - os: ubuntu-latest
            node-version: 22
            experimental: true

# ── Matrix with Failure Strategy ──
  test-resilient:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false      # Continue all jobs even if some fail
      max-parallel: 4        # Limit parallel jobs
      matrix:
        version: [v1, v2, v3]
    steps:
      - run: npm test

# ── Matrix Output Aggregation ──
  build:
    runs-on: ubuntu-latest
    outputs:
      results: ${{ toJSON(steps.result.outputs) }}
    strategy:
      matrix:
        platform: [linux, mac, win]
    steps:
      - id: result
        run: echo "result=${{ matrix.platform }}-success" >> $GITHUB_OUTPUT

# ── Reusable Workflow (called by others) ──
name: Reusable Deploy
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
        description: 'Target environment'
      version:
        required: false
        type: string
        default: 'latest'
    outputs:
      url:
        description: 'Deployment URL'
        value: ${{ jobs.deploy.outputs.url }}
    secrets:
      deploy-key:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying version ${{ inputs.version }} to ${{ inputs.environment }}"
      - run: echo "url=https://${{ inputs.environment }}.app.example.com" >> $GITHUB_OUTPUT
        id: deploy

# ── Calling a Reusable Workflow ──
name: Deploy Pipeline
on:
  push:
    branches: [main]

jobs:
  # Call reusable workflow
  deploy-staging:
    uses: ./.github/workflows/called.yml
    with:
      environment: staging
      version: ${{ github.sha }}
    secrets: inherit    # Pass all secrets

  deploy-production:
    needs: deploy-staging
    uses: ./.github/workflows/called.yml
    with:
      environment: production
      version: ${{ github.sha }}
    secrets:
      deploy-key: ${{ secrets.PROD_DEPLOY_KEY }}   # Pass specific secret
    # You can also use: secrets: inherit

  # Call workflow from another repo
  external:
    uses: my-org/shared-actions/.github/workflows/deploy.yml@main
    with:
      environment: staging
    secrets: inherit