Workflow Development

Workflow Development Skill

Design, debug, and optimize GitHub Actions workflows with security best practices.

Trigger Phrases

• "create a CI workflow"
• "add a release workflow"
• "my workflow is failing"
• "make this workflow reusable"
• "workflow security audit"
• "add [language] CI"

Security Requirements (Non-Negotiable)

SHA Pinning

# CORRECT
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

# WRONG - Never use tags
- uses: actions/checkout@v4

Minimal Permissions

permissions:
  contents: read  # Start with minimum

# Only add what's needed:
# pull-requests: write  # For PR comments
# packages: write       # For container registry

Reusable Workflow Pattern

Caller (in project)

name: CI
on: [push, pull_request]

jobs:
  ci:
    uses: zircote/.github/.github/workflows/reusable-ci-python.yml@main
    with:
      python-version: '3.12'
      coverage-threshold: 80
    secrets: inherit

Reusable Definition (in .github repo)

name: Reusable Python CI

on:
  workflow_call:
    inputs:
      python-version:
        required: false
        type: string
        default: '3.12'
      coverage-threshold:
        required: false
        type: number
        default: 80

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: zircote/.github/actions/setup-python-uv@main
        with:
          python-version: ${{ inputs.python-version }}
      - run: uv run ruff check .

Available Reusable Workflows

Composite Action Pattern

# action.yml
name: 'Setup Python with uv'
description: 'Install Python and uv with caching'

inputs:
  python-version:
    required: false
    default: '3.12'

runs:
  using: 'composite'
  steps:
    - uses: astral-sh/setup-uv@v4
      with:
        enable-cache: true
    - shell: bash
      run: uv python install ${{ inputs.python-version }}

Debugging Workflows

Common Failures

Debug Step

- name: Debug
  run: |
    echo "Event: ${{ github.event_name }}"
    echo "Ref: ${{ github.ref }}"
    echo "Actor: ${{ github.actor }}"

Validation

# Validate SHA pinning
./scripts/validate-sha-pinning.sh .github/workflows/

# Check for unpinned actions
grep -rn "uses:.*@v[0-9]" .github/workflows/

# Validate workflow structure
./scripts/validate-workflows.sh .github/workflows/

Performance Optimization

Caching

- uses: actions/cache@0c907a75c2c80ebcb7f088228285e798b750cf8f
  with:
    path: ~/.cache/uv
    key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}

Matrix Builds

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest]
    python: ['3.11', '3.12']

Concurrency

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