0xDarkMatter/ci-cd-ops

CI/CD Operations

Comprehensive patterns for continuous integration, delivery, and deployment using GitHub Actions, release automation tools, and testing pipelines.

GitHub Actions Quick Reference

Workflow File Anatomy

name: CI                          # Display name in Actions tab
on:                               # Trigger events
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:                      # GITHUB_TOKEN scope (least privilege)
  contents: read
  pull-requests: write

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

env:                              # Workflow-level environment variables
  NODE_VERSION: "20"

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

Core Syntax Elements

| Element | Purpose | Example | |---------|---------|---------| | on | Event triggers | push, pull_request, schedule | | jobs.<id>.runs-on | Runner selection | ubuntu-latest, self-hosted | | jobs.<id>.needs | Job dependencies | needs: [build, lint] | | jobs.<id>.if | Conditional execution | if: github.event_name == 'push' | | jobs.<id>.strategy.matrix | Parallel variants | node-version: [18, 20, 22] | | jobs.<id>.environment | Deployment target | environment: production | | jobs.<id>.permissions | Token scope | contents: write | | steps[*].uses | Use an action | uses: actions/checkout@v4 | | steps[*].run | Run a command | run: npm test | | steps[*].env | Step environment | env: { CI: true } |

Trigger Decision Tree

| Scenario | Trigger | Config | |----------|---------|--------| | Run tests on every PR | pull_request | branches: [main] | | Deploy on merge to main | push | branches: [main] | | Release on version tag | push | tags: ['v*'] | | Nightly builds | schedule | cron: '0 2 * * *' | | Manual deployment | workflow_dispatch | inputs: { environment: ... } | | Called by another workflow | workflow_call | inputs:, secrets: | | On PR label change | pull_request | types: [labeled] | | On issue comment | issue_comment | types: [created] | | On release published | release | types: [published] | | On package push | registry_package | types: [published] |

Trigger Filter Patterns

on:
  push:
    branches: [main, 'release/**']      # Branch patterns
    paths: ['src/**', '!src/**/*.test.*'] # Path filters (ignore tests)
    tags: ['v*']                          # Tag patterns
  pull_request:
    types: [opened, synchronize, reopened] # Default types
    paths-ignore: ['docs/**', '*.md']     # Ignore docs-only changes

Caching Strategies

| Ecosystem | Action / Key | Path | Restore Key | |-----------|-------------|------|-------------| | Node (npm) | actions/setup-node with cache: npm | Auto | Auto | | Node (pnpm) | actions/setup-node with cache: pnpm | Auto | Auto | | Go modules | actions/setup-go with cache: true | Auto | Auto | | Cargo | actions/cache@v4 | ~/.cargo/registry, target | cargo-${{ runner.os }}-${{ hashFiles('Cargo.lock') }} | | pip / uv | actions/setup-python with cache: pip | Auto | Auto | | Docker layers | docker/build-push-action | Uses buildx cache | type=gha or type=registry | | Gradle | actions/setup-java with cache: gradle | Auto | Auto | | Composer | actions/cache@v4 | vendor | composer-${{ hashFiles('composer.lock') }} |

Manual Cache Example

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/bin
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}
    restore-keys: |
      cargo-${{ runner.os }}-

Matrix Strategy

strategy:
  fail-fast: false                    # Don't cancel siblings on failure
  max-parallel: 4                     # Limit concurrent jobs
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node-version: [18, 20, 22]
    include:                          # Add specific combos
      - os: ubuntu-latest
        node-version: 22
        coverage: true
    exclude:                          # Remove specific combos
      - os: windows-latest
        node-version: 18

Dynamic Matrix

prepare:
  runs-on: ubuntu-latest
  outputs:
    matrix: ${{ steps.set.outputs.matrix }}
  steps:
    - id: set
      run: echo "matrix=$(jq -c . matrix.json)" >> "$GITHUB_OUTPUT"

test:
  needs: prepare
  strategy:
    matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}

Secrets Management

| Scope | Access | Use Case | |-------|--------|----------| | Repository secrets | All workflows in repo | API keys, tokens | | Environment secrets | Jobs targeting that environment | Production credentials | | Organization secrets | Selected repos in org | Shared service accounts | | OIDC tokens | Federated identity | Cloud deployment (no stored secrets) |

Secrets Best Practices

# Reference secrets - NEVER echo or log them
- run: deploy --token ${{ secrets.DEPLOY_TOKEN }}

# Mask custom values
- run: echo "::add-mask::$CUSTOM_SECRET"

# Use environments for deployment secrets
jobs:
  deploy:
    environment: production           # Requires approval + has secrets
    steps:
      - run: deploy --key ${{ secrets.PROD_API_KEY }}

OIDC for Cloud (No Stored Secrets)

permissions:
  id-token: write
  contents: read

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

Common Workflow Patterns

Test on Pull Request

name: Test
on:
  pull_request:
    branches: [main]
concurrency:
  group: test-${{ github.head_ref }}
  cancel-in-progress: true
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage

Deploy on Merge to Main

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

Release on Tag

name: Release
on:
  push:
    tags: ['v*']
permissions:
  contents: write
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: |
          gh release create ${{ github.ref_name }} \
            --generate-notes \
            --title "${{ github.ref_name }}"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gotchas Table

| Gotcha | Problem | Fix | |--------|---------|-----| | Shallow clone | git describe fails, history missing | actions/checkout@v4 with fetch-depth: 0 | | Default permissions | GITHUB_TOKEN is read-only by default | Set permissions: explicitly | | Action pinning | @main can break without warning | Pin to SHA: @abc123 or @v4 | | Fork PR secrets | Secrets unavailable on fork PRs | Use pull_request_target carefully | | Concurrent deploys | Race condition on production | Use concurrency: groups | | Stale caches | Cache grows unbounded | Include lockfile hash in key | | Node.js version | setup-node defaults vary | Always specify node-version | | Docker layer cache | Rebuilds everything without cache | Use cache-from: type=gha | | Matrix + environment | Each matrix job needs approval | Use a single deploy job after matrix | | Path filters + required checks | Skipped jobs block merge | Use paths-filter action or make checks non-required | | GITHUB_TOKEN in PRs | Cannot trigger other workflows | Use a PAT or GitHub App token | | Windows line endings | Scripts fail with \r\n | Use .gitattributes or core.autocrlf |

Expression Syntax Quick Reference

| Expression | Result | |------------|--------| | ${{ github.event_name }} | push, pull_request, etc. | | ${{ github.ref_name }} | Branch or tag name | | ${{ github.sha }} | Full commit SHA | | ${{ github.actor }} | User who triggered | | ${{ runner.os }} | Linux, Windows, macOS | | ${{ contains(github.event.head_commit.message, '[skip ci]') }} | Check commit message | | ${{ needs.build.outputs.version }} | Output from prior job | | ${{ fromJson(steps.meta.outputs.json) }} | Parse JSON output | | ${{ hashFiles('**/package-lock.json') }} | Hash for cache keys | | ${{ format('refs/heads/{0}', matrix.branch) }} | String formatting | | ${{ toJson(matrix) }} | Debug: print matrix config |

Step Outputs

steps:
  - id: version
    run: echo "value=$(cat VERSION)" >> "$GITHUB_OUTPUT"

  - run: echo "Version is ${{ steps.version.outputs.value }}"

Job Outputs (for Cross-Job Communication)

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-id: ${{ steps.upload.outputs.artifact-id }}
    steps:
      - id: upload
        run: echo "artifact-id=abc123" >> "$GITHUB_OUTPUT"

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.artifact-id }}"

Reference Files

| File | Contents | |------|----------| | references/github-actions.md | Complete workflow syntax, reusable workflows, composite actions, OIDC, runners, debugging | | references/release-automation.md | Semantic versioning, semantic-release, changesets, goreleaser, changelog, publishing | | references/testing-pipelines.md | Test stages, parallelism, coverage, service containers, e2e in CI, deployment pipelines |