github-actions-guide

name	github-actions-guide
description	Guide for writing GitHub Actions workflows with triggers, reusable workflows, matrix strategies, caching, secrets, and composite actions. Use when the user creates or modifies GitHub Actions workflows, asks about CI/CD on GitHub, or needs help with workflow syntax. Trigger whenever GitHub Actions, .github/workflows, or CI pipelines on GitHub are mentioned.

GitHub Actions Guide

Write efficient, secure, and maintainable GitHub Actions workflows with proper caching, secret management, reusable components, and matrix testing strategies.

When to Use

• User creates or modifies files in .github/workflows/
• User asks about CI/CD pipelines on GitHub
• User needs matrix testing across versions or platforms
• User wants to share workflow logic across repositories
• User asks about GitHub Actions caching or secrets

Core Patterns

Standard CI Workflow

A well-structured CI workflow with caching, linting, testing, and building.

name: CI

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

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

permissions:
  contents: read

jobs:
  lint:
    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 run typecheck

  test:
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        if: matrix.node-version == 20
        with:
          name: coverage
          path: coverage/

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

Matrix Strategy

Test across multiple dimensions -- versions, operating systems, or configurations.

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12"]
        exclude:
          - os: windows-latest
            python-version: "3.10"
        include:
          - os: ubuntu-latest
            python-version: "3.12"
            coverage: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: pytest --cov=${{ matrix.coverage && '--cov-report=xml' || '' }}

Reusable Workflow

Extract common workflow logic into callable workflows.

# .github/workflows/reusable-deploy.yml
name: Deploy

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      image-tag:
        required: true
        type: string
    secrets:
      AWS_ROLE_ARN:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1
      - run: |
          aws ecs update-service \
            --cluster ${{ inputs.environment }} \
            --service api \
            --force-new-deployment

Caller workflow:

jobs:
  deploy-staging:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: staging
      image-tag: ${{ github.sha }}
    secrets:
      AWS_ROLE_ARN: ${{ secrets.STAGING_AWS_ROLE_ARN }}

Composite Action

Bundle multiple steps into a reusable action for shared setup logic.

# .github/actions/setup-project/action.yml
name: Setup Project
description: Install dependencies and configure environment

inputs:
  node-version:
    description: Node.js version
    default: "20"

runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash
    - run: cp .env.example .env.test
      shell: bash

Usage: - uses: ./.github/actions/setup-project

Anti-Patterns

• Not pinning action versions: Use @v4 at minimum, or pin to a full SHA for critical actions. Never use @main or @latest.
• Storing secrets in code: Use GitHub Secrets or OIDC. Never hardcode credentials in workflow files.
• No concurrency control: Without concurrency, multiple pushes trigger redundant runs. Always cancel in-progress runs on PRs.
• Overly broad permissions: Set permissions at the workflow or job level. Default contents: read and add only what is needed.
• Not caching dependencies: Every job starts fresh. Use built-in caching (cache: npm) or actions/cache to avoid reinstalling deps every run.
• Running everything sequentially: Use needs to parallelize independent jobs. Lint and test can run in parallel.

Quick Reference

# Triggers
on:
  push: { branches: [main] }           # Push to main
  pull_request: { branches: [main] }   # PR targeting main
  schedule: [{ cron: "0 6 * * 1" }]    # Weekly Monday 6am
  workflow_dispatch: {}                  # Manual trigger
  workflow_call: {}                      # Called by another workflow

# Conditions
if: github.event_name == 'push'
if: contains(github.event.head_commit.message, '[skip ci]') == false
if: github.actor != 'dependabot[bot]'

# Common caching
- uses: actions/setup-node@v4
  with: { cache: npm }
- uses: actions/setup-python@v5
  with: { cache: pip }
- uses: actions/setup-go@v5
  with: { cache: true }