/writing-github-actions

name: writing-github-actions
description: Write GitHub Actions workflows with proper syntax, reusable workflows, composite actions, matrix builds, caching, and security best practices. Use when creating CI/CD workflows for GitHub-hosted projects or automating GitHub repository tasks.

Writing GitHub Actions

Create GitHub Actions workflows for CI/CD pipelines, automated testing, deployments, and repository automation using YAML-based configuration with native GitHub integration.

Purpose

GitHub Actions is the native CI/CD platform for GitHub repositories. This skill covers workflow syntax, triggers, job orchestration, reusable patterns, optimization techniques, and security practices specific to GitHub Actions.

**Core Focus:**

• Workflow YAML syntax and structure
• Reusable workflows and composite actions
• Matrix builds and parallel execution
• Caching and optimization strategies
• Secrets management and OIDC authentication
• Concurrency control and artifact management

**Not Covered:**

• CI/CD pipeline design strategy → See `building-ci-pipelines`
• GitOps deployment patterns → See `gitops-workflows`
• Infrastructure as code → See `infrastructure-as-code`
• Testing frameworks → See `testing-strategies`

When to Use This Skill

Trigger this skill when:

• Creating CI/CD workflows for GitHub repositories
• Automating tests, builds, and deployments via GitHub Actions
• Setting up reusable workflows across multiple repositories
• Optimizing workflow performance with caching and parallelization
• Implementing security best practices for GitHub Actions
• Troubleshooting GitHub Actions YAML syntax or behavior

Workflow Fundamentals

Basic Workflow Structure

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

**Key Components:**

• `name`: Workflow display name
• `on`: Trigger events (push, pull_request, schedule, workflow_dispatch)
• `jobs`: Job definitions (run in parallel by default)
• `runs-on`: Runner type (ubuntu-latest, windows-latest, macos-latest)
• `steps`: Sequential operations (uses actions or run commands)

Common Triggers

# Code events
on:
  push:
    branches: [main, develop]
    paths: ['src/**']
  pull_request:
    types: [opened, synchronize, reopened]

# Manual trigger
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, staging, production]

# Scheduled
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

For complete trigger reference, see `references/triggers-events.md`.

Decision Frameworks

Reusable Workflow vs Composite Action

**Use Reusable Workflow when:**

• Standardizing entire CI/CD jobs across repositories
• Need complete job replacement with inputs/outputs
• Want secrets to inherit by default
• Orchestrating multiple steps with job-level configuration

**Use Composite Action when:**

• Packaging 5-20 step sequences for reuse
• Need step-level abstraction within jobs
• Want to distribute via marketplace or private repos
• Require local file access without artifacts

| Feature | Reusable Workflow | Composite Action | |---------|------------------|------------------| | Scope | Complete job | Step sequence | | Trigger | `workflow_call` | `uses:` in step | | Secrets | Inherit by default | Must pass explicitly | | File Sharing | Requires artifacts | Same runner/workspace |

For detailed patterns, see `references/reusable-workflows.md` and `references/composite-actions.md`.

Caching Strategy

**Use Built-in Setup Action Caching (Recommended):**

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # or 'yarn', 'pnpm'

Available for: Node.js, Python (pip), Java (maven/gradle), .NET, Go

**Use Manual Caching when:**

• Need custom cache keys
• Caching build outputs or non-standard paths
• Implementing multi-layer cache strategies

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

For optimization techniques, see `references/caching-strategies.md`.

Self-Hosted vs GitHub-Hosted Runners

**Use GitHub-Hosted Runners when:**

• Standard build environments sufficient
• No private network access required
• Within budget or free tier limits

**Use Self-Hosted Runners when:**

• Need specific hardware (GPU, ARM, high memory)
• Require private network/VPN access
• High usage volume (cost optimization)
• Custom software must be pre-installed

Common Patterns

Multi-Job Workflow with Dependencies

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v5
        with:
          name: dist
      - run: npm test

  deploy:
    needs: [build, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v5
      - run: ./deploy.sh

**Key Elements:**

• `needs:` creates job dependencies (sequential execution)
• Artifacts pass data between jobs
• `if:` enables conditional execution
• `environment:` enables protection rules and environment secrets

Matrix Builds

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      -