CI CD Patterns

CI/CD Patterns

Best practices and anti-patterns for CI/CD pipelines, focusing on GitHub Actions but applicable to other CI systems. Run the linter on every workflow file before review; use this prose guidance to explain findings and propose fixes.

Purpose

• Ensure pipelines are fast, reliable, and secure
• Prevent common mistakes that cause build failures or security issues
• Establish patterns for maintainable pipeline configurations

Core Patterns

Pattern 1: Parallel Job Execution

When to use: Multiple independent tasks in pipeline.

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  # Only deploy after all checks pass
  deploy:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

Pattern 2: Dependency Caching

When to use: Repeated dependency installation across runs.

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

- name: Install dependencies
  run: npm ci

Pattern 3: Safe Deployments with Health Checks

deploy:
  steps:
    - name: Deploy
      run: kubectl apply -f deployment.yaml

    - name: Wait for rollout
      run: kubectl rollout status deployment/app --timeout=5m

    - name: Health check
      run: curl -f https://app.example.com/health || exit 1

    - name: Rollback on failure
      if: failure()
      run: kubectl rollout undo deployment/app

Anti-Patterns

Anti-Pattern 1: Hardcoded Secrets

Anti-Pattern 2: Unpinned Action Versions

Anti-Pattern 3: Missing Timeout

Anti-Pattern 4: Missing Permissions Block

Validation Checklist

Implementation

• All secrets use ${{ secrets.NAME }} syntax
• Actions pinned to full commit SHA
• Permissions block present (workflow or job level)
• Independent jobs run in parallel
• Timeouts set on jobs
• Health checks after deployments
• Rollback mechanism in place

Invocation — CI/CD Linter (L3 Script)

Run the linter on every workflow file before review. Consume its output only — the script source never enters context.

Input: JSON representation of the GitHub Actions workflow. YAML must be converted to JSON first.

YAML to JSON conversion:

python3 -c "import sys,json,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))" < .github/workflows/ci.yml \
  | python .claude/skills/devops/ci-cd-patterns/scripts/cicd_lint.py -

Or with yq:

yq -o json .github/workflows/ci.yml | python .claude/skills/devops/ci-cd-patterns/scripts/cicd_lint.py -

Run via Bash (file argument — JSON):

python .claude/skills/devops/ci-cd-patterns/scripts/cicd_lint.py workflow.json

Input format:

{
  "name": "CI",
  "on": {"push": {"branches": ["main"]}},
  "permissions": "read-all",
  "jobs": {
    "build": {
      "runs-on": "ubuntu-latest",
      "timeout-minutes": 30,
      "permissions": {"contents": "read"},
      "steps": [
        {"name": "Checkout", "uses": "actions/checkout@<sha>"},
        {"name": "Test", "run": "npm test"}
      ]
    }
  }
}

Output:

1. JSON object with findings array (each finding has id, severity, job, title, detail, reference) and summary counts.
2. Markdown findings table sorted by severity (CRITICAL → HIGH → MEDIUM).

Findings covered:

What to do with the output:

1. CRITICAL findings (hardcoded secrets, branch-pinned actions) must be blocked — these are supply-chain and credential exposure risks.
2. HIGH findings must be addressed before the workflow is merged to the default branch.
3. MEDIUM findings should be addressed; document exceptions.

Error handling: Script exits non-zero on I/O failure or if the input is missing the jobs field (required). Exits 0 for valid input including empty input and finding-present input.

Quick Reference