github-actions

github-actions Best Practices

GitHub Actions is the backbone of modern CI/CD. Adhering to these best practices ensures your workflows are efficient, secure, and maintainable. This guide is your definitive reference for building high-quality pipelines.

1. Workflow Design & Code Organization

Structure your workflows for clarity, reusability, and efficiency.

1.1 Use Reusable Workflows and Composite Actions

Avoid duplication. Abstract common sequences into reusable workflows or composite actions.

❌ BAD: Duplicated Steps

# .github/workflows/build-frontend.yml
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run build

# .github/workflows/build-backend.yml
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4 # Duplicated setup
        with: { node-version: '20' }
      - run: npm ci # Duplicated install
      - run: npm run build:backend # Different build step

✅ GOOD: Reusable Workflow

# .github/workflows/reusable-build.yml
on:
  workflow_call:
    inputs:
      build-script: { required: true, type: string }
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: ${{ inputs.build-script }}

# .github/workflows/frontend.yml
jobs:
  build:
    uses: ./.github/workflows/reusable-build.yml
    with: { build-script: 'npm run build:frontend' }

# .github/workflows/backend.yml
jobs:
  build:
    uses: ./.github/workflows/reusable-build.yml
    with: { build-script: 'npm run build:backend' }

1.2 Name Jobs and Steps Consistently

Use clear, descriptive names for jobs and steps. This improves readability and debugging.

❌ BAD: Vague Naming

jobs:
  job1:
    steps:
      - run: echo "hello"
      - run: npm test

# logs will show 'Run echo "hello"' and 'Run npm test'