ci-cd

GitHub Actions CI/CD Patterns

Quick Reference

Task	Approach
New workflow	Choose template below by project type
CI failing	Check logs -> match common failure patterns below
Slow builds	Add caching, use matrix for parallelism
Release	Tag-triggered workflow with changelog
Secrets	Repository secrets + environment protection rules
Reusable logic	Composite actions or reusable workflows

Workflow Structure

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup runtime
        # Language-specific setup
      - name: Install dependencies
        # Package manager install
      - name: Lint
        # Linter run
      - name: Test
        # Test suite
      - name: Build
        # Build step (if applicable)

Language-Specific Templates

Node.js (pnpm)

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22  # Check https://nodejs.org for current LTS
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

Python (uv)

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"  # Check https://python.org for current stable
      - run: uv sync
      - run: uv run ruff check .
      - run: uv run pytest

Python (pip)

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"  # Check https://python.org for current stable
          cache: pip
      - run: pip install -r requirements.txt
      - run: ruff check .
      - run: pytest

Docker Build + Push

jobs:
  docker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

Caching Strategies

Package Manager	Cache Key
pnpm	pnpm/action-setup + setup-node with cache: pnpm
npm	setup-node with cache: npm
pip	setup-python with cache: pip
uv	setup-uv handles caching automatically
cargo	actions/cache with target/ and Cargo.lock hash
go	setup-go with cache: true
Docker	cache-from: type=gha in build-push-action

Custom cache example:

- uses: actions/cache@v4
  with:
    path: ~/.cache/custom
    key: ${{ runner.os }}-custom-${{ hashFiles('**/lockfile') }}
    restore-keys: ${{ runner.os }}-custom-

Matrix Builds

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [20, 22]
        exclude:
          - os: windows-latest
            node-version: 20
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

Use fail-fast: false to see all failures, not just the first.

Secrets Management

# Use repository or environment secrets - never hardcode
env:
  API_KEY: ${{ secrets.API_KEY }}

# Protect production deployments with environments
jobs:
  deploy:
    environment: production  # Requires approval
    steps:
      - run: deploy --token ${{ secrets.DEPLOY_TOKEN }}

Rules:

• Never echo or log secrets
• Use environment protection for production deployments
• Rotate secrets if exposed in logs
• Use GITHUB_TOKEN for GitHub API calls (auto-provided)

Release Automation

name: Release
on:
  push:
    tags: ["v*"]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create ${{ github.ref_name }} --generate-notes

Debugging CI Failures

Common Failure Patterns

Symptom	Likely Cause	Fix
"Permission denied"	Missing permissions block	Add required permissions to job
"Resource not accessible"	GITHUB_TOKEN scope too narrow	Add permissions: contents: write etc.
"Cache not found"	Changed lockfile or wrong cache key	Check hashFiles() pattern matches lockfile
"Out of disk space"	Large build artifacts or Docker layers	Add cleanup step or use larger runner
Flaky tests (pass/fail randomly)	Race conditions or timing deps	Add retries or fix test isolation
"Node.js version not found"	Version string format	Use quotes: node-version: "22"
Different behavior on PR vs push	Different trigger contexts	Check github.event_name conditions

Reading Workflow Logs

1. Go to the Actions tab -> click the failing run
2. Expand the failing step
3. Look for the first error (not the last) - cascading failures are common
4. Check the "Set up job" step for environment issues
5. Use ACTIONS_STEP_DEBUG secret set to true for verbose logging

Reusable Workflows

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: "22"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

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

Anti-Patterns

Don't	Do Instead
Use actions/checkout@v2	Use @v4 (latest major)
npm install in CI	npm ci (clean install from lockfile)
Skip permissions block	Always declare minimum required permissions
Cache node_modules/ directly	Let setup-node cache the package manager store
Run deploys on every push	Use tag triggers or environment protection
Use continue-on-error: true to hide failures	Fix the underlying issue
Duplicate steps across workflows	Extract to reusable workflow or composite action