Github Actions Workflows

GitHub Actions Workflows

Expert guidance for designing reliable, secure, and performant GitHub Actions CI/CD pipelines with patterns for matrix builds, reusable workflows, caching, and deployment automation.

When to Use This Skill

• Setting up CI/CD pipelines with GitHub Actions from scratch
• Optimizing slow or expensive GitHub Actions workflows
• Implementing matrix builds for multi-environment testing
• Creating reusable workflows and composite actions for DRY pipelines
• Managing secrets securely across environments
• Configuring caching for dependency and build artifact reuse
• Setting up deployment workflows with staging and production gates
• Debugging failing or flaky workflow runs
• Implementing concurrency controls to prevent duplicate runs

Quick Reference

Core Principles

• Structured jobs: Break workflows into clear, distinct jobs with defined dependencies
• DRY configuration: Use reusable workflows and composite actions to avoid duplication
• Security first: Use GitHub secrets, OIDC, and minimum necessary permissions
• Cache aggressively: Cache dependencies, build outputs, and test fixtures
• Trigger thoughtfully: Configure event triggers to avoid unnecessary workflow runs
• Document workflows: Add comments explaining non-obvious YAML configuration

Workflow

1. Design

Plan the pipeline structure before writing YAML.

• Identify trigger events (push, pull_request, schedule, workflow_dispatch)
• Map job dependencies and what can run in parallel
• Determine caching opportunities (dependencies, build outputs)
• Plan environment promotion (dev, staging, production)

2. Implementation

Build the pipeline incrementally.

• Start with a minimal workflow and add complexity
• Use matrix builds for multi-environment testing
• Extract reusable workflows for shared patterns
• Configure secrets management with environment protection

3. Optimization

Reduce runtime and cost.

• Profile workflow timing to identify bottlenecks
• Add caching for dependencies and build artifacts
• Use concurrency controls to cancel redundant runs
• Configure path filters to skip unaffected workflows

4. Maintenance

Keep workflows healthy over time.

• Pin action versions to specific SHAs for security
• Review and update actions regularly
• Monitor workflow runtime trends and costs
• Peer-review workflow changes before merging

Common Mistakes

• Using actions/checkout@main instead of pinning to a SHA or version tag
• Not setting permissions block (defaults to overly broad read-write)
• Caching node_modules instead of the package manager cache directory
• Missing concurrency groups, leading to duplicate deploys
• Hardcoding secrets in workflow files instead of using GitHub Secrets
• Running the full test suite on every push instead of using path filters
• Not using workflow_call for shared CI logic across repositories

GitHub Actions Workflow Patterns

Matrix Builds

Multi-OS / Multi-Version Matrix

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    node: [18, 20, 22]
    exclude:
      - os: windows-latest
        node: 18
  fail-fast: false

Dynamic Matrix from JSON

jobs:
  generate:
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix=$(cat matrix.json)" >> $GITHUB_OUTPUT

  build:
    needs: generate
    strategy:
      matrix: ${{ fromJson(needs.generate.outputs.matrix) }}

Reusable Workflows

Caller Workflow

jobs:
  deploy:
    uses: ./.github/workflows/deploy-reusable.yml
    with:
      environment: production
      version: ${{ github.sha }}
    secrets: inherit

Reusable Workflow Definition

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      version:
        required: true
        type: string
    secrets:
      DEPLOY_TOKEN:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.version }}

Composite Actions

# .github/actions/setup-project/action.yml
name: Setup Project
description: Install dependencies and build
inputs:
  node-version:
    default: '20'
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
    - run: npm ci
      shell: bash
    - run: npm run build
      shell: bash

Secrets Management

Environment-Scoped Secrets

jobs:
  deploy:
    environment: production
    steps:
      - run: deploy --token ${{ secrets.DEPLOY_TOKEN }}

OIDC for Cloud Authentication

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

Best Practices

• Never echo secrets in logs
• Use add-mask for dynamic secrets
• Rotate secrets on a schedule
• Prefer OIDC over long-lived credentials
• Use environment protection rules for sensitive deployments

Caching Strategies

Dependency Caching

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

Build Cache

- uses: actions/cache@v4
  with:
    path: |
      .next/cache
      dist
    key: build-${{ runner.os }}-${{ hashFiles('src/**', 'package-lock.json') }}

Docker Layer Caching

- uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

Deployment Workflows

Staged Deployment

jobs:
  deploy-staging:
    environment: staging
    steps:
      - run: deploy --env staging

  smoke-test:
    needs: deploy-staging
    steps:
      - run: npm run test:smoke -- --url $STAGING_URL

  deploy-production:
    needs: smoke-test
    environment: production
    steps:
      - run: deploy --env production

Rollback Pattern

- name: Deploy
  id: deploy
  run: deploy --version ${{ github.sha }}
  continue-on-error: true

- name: Rollback on failure
  if: steps.deploy.outcome == 'failure'
  run: deploy --version ${{ env.PREVIOUS_VERSION }}

Conditional Execution

Path-Based Triggers

on:
  push:
    paths:
      - 'src/**'
      - 'package.json'
    paths-ignore:
      - '**.md'
      - 'docs/**'

Conditional Jobs

jobs:
  deploy:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'

Concurrency Control

Cancel In-Progress Runs

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

Queue Deployments

concurrency:
  group: deploy-production
  cancel-in-progress: false

Self-Hosted Runners

Runner Labels

jobs:
  gpu-test:
    runs-on: [self-hosted, linux, gpu]

Security

• Use runner groups for organization-level access control
• Restrict self-hosted runners to private repositories
• Use ephemeral runners for sensitive workloads
• Clean workspace between runs

Workflow Optimization

Parallel Jobs

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
  build:
    runs-on: ubuntu-latest

  deploy:
    needs: [lint, test, build]

Timeout Limits

jobs:
  test:
    timeout-minutes: 30
    steps:
      - run: npm test
        timeout-minutes: 10

Shallow Checkout

- uses: actions/checkout@v4
  with:
    fetch-depth: 1
    sparse-checkout: |
      src
      tests

Error Handling

Notifications

- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {"text": "Build failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}

- name: Always cleanup
  if: always()
  run: cleanup-resources.sh