collaboration-github-actions-workflows

Setting up CI/CD pipelines with GitHub Actions

GitHub Actions Workflows

Scope: Workflow syntax, triggers, jobs, steps, matrix builds, caching, and artifacts for GitHub Actions CI/CD pipelines

Lines: 380

Last Updated: 2025-10-18

Format Version: 1.0 (Atomic)

When to Use This Skill

Use this skill when:

Setting up CI/CD pipelines with GitHub Actions
Configuring workflow triggers (push, pull_request, schedule, workflow_dispatch)
Implementing matrix builds for multi-platform or multi-version testing
Optimizing workflows with caching strategies
Managing artifacts between jobs
Setting up reusable workflows and composite actions
Configuring job dependencies and conditions

Don't use this skill for:

Platform-specific deployment configurations (see cd-deployment-patterns.md)
Testing strategies and optimization (see ci-testing-strategy.md and ci-optimization.md)
Security and secret management (see ci-security.md)

Core Concepts

Workflow Structure

name: Workflow Name
on: [triggers]
env:
  GLOBAL_VAR: value
jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - name: Step name
        uses: actions/checkout@v4

Key Components

Triggers (on): Events that start workflows
Jobs: Independent execution units that can run in parallel
Steps: Sequential commands or actions within a job
Runners: Virtual machines that execute jobs
Actions: Reusable units of code (marketplace or custom)
Contexts: Variables available in expressions (${{ github.event.name }})

Execution Model

Trigger Event
  ↓
Workflow Starts
  ↓
Jobs Run (Parallel by default)
  ↓
Each Job: Steps Execute Sequentially
  ↓
Workflow Completes

Patterns

Basic Workflow Structure

name: CI Pipeline

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

env:
  NODE_VERSION: '20'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

Advanced Triggers

on:
  # Multiple events
  push:
    branches:
      - main
      - 'releases/**'
    paths:
      - 'src/**'
      - '!src/docs/**'

  pull_request:
    types: [opened, synchronize, reopened]

  # Scheduled runs (cron)
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

  # Manual trigger with inputs
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        type: choice
        options:
          - staging
          - production
      dry_run:
        description: 'Run in dry-run mode'
        required: false
        type: boolean
        default: false

  # Trigger from other workflows
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string

Matrix Builds

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          # Don't test Node 18 on Windows
          - os: windows-latest
            node: 18
        include:
          # Add experimental combinations
          - os: ubuntu-latest
            node: 23
            experimental: true

      # Continue other jobs even if one fails
      fail-fast: false

      # Limit concurrent jobs
      max-parallel: 4

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

      - name: Run tests
        run: npm test
        continue-on-error: ${{ matrix.experimental || false }}

Job Dependencies

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy-staging:
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh staging

  deploy-prod:
    needs: deploy-staging
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh production

Caching Dependencies

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      # Node.js with automatic caching
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # Manual cache for custom paths
      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      # Python with pip cache
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'

      # Rust with cargo cache
      - uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/bin/
            ~/.cargo/registry/index/
            ~/.cargo/registry/cache/
            ~/.cargo/git/db/
            target/
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

Artifacts

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build artifacts
        run: npm run build

      # Upload artifacts
      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-files
          path: dist/
          retention-days: 7
          if-no-files-found: error

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      # Download artifacts
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: dist-files
          path: dist/

      - name: Run integration tests
        run: npm run test:integration

Conditional Execution

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      # Step-level condition
      - name: Deploy to staging
        if: github.ref == 'refs/heads/develop'
        run: ./deploy.sh staging

      # Multiple conditions
      - name: Deploy to production
        if: |
          github.ref == 'refs/heads/main' &&
          github.event_name == 'push' &&
          !contains(github.event.head_commit.message, '[skip deploy]')
        run: ./deploy.sh production

      # Check previous step status
      - name: Notify on failure
        if: failure()
        run: ./notify-slack.sh "Deployment failed"

      # Always run (cleanup)
      - name: Cleanup
        if: always()
        run: ./cleanup.sh

Reusable Workflows

Caller workflow:

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

on:
  push:
    branches: [main]

jobs:
  deploy-prod:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      environment: production
      region: us-east-1
    secrets:
      api-key: ${{ secrets.PROD_API_KEY }}

Reusable workflow:

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

on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
      region:
        required: true
        type: string
    secrets:
      api-key:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}

    steps:
      - uses: actions/checkout@v4

      - name: Deploy to ${{ inputs.environment }}
        env:
          API_KEY: ${{ secrets.api-key }}
          REGION: ${{ inputs.region }}
        run: ./deploy.sh

Composite Actions

# .github/actions/setup-node-app/action.yml
name: 'Setup Node.js Application'
description: 'Checkout, setup Node.js, install dependencies'

inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '20'

runs:
  using: 'composite'
  steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - name: Install dependencies
      shell: bash
      run: npm ci

Usage:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: ./.github/actions/setup-node-app
        with:
          node-version: '20'

      - run: npm run build

Environment Variables and Contexts

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      # Job-level environment variable
      BUILD_ENV: production

    steps:
      - name: Print contexts
        env:
          # Step-level environment variable
          STEP_VAR: value
        run: |
          echo "Event: ${{ github.event_name }}"
          echo "Ref: ${{ github.ref }}"
          echo "SHA: ${{ github.sha }}"
          echo "Actor: ${{ github.actor }}"
          echo "Repository: ${{ github.repository }}"
          echo "Run ID: ${{ github.run_id }}"
          echo "Runner OS: ${{ runner.os }}"
          echo "Job status: ${{ job.status }}"
          echo "Build env: $BUILD_ENV"
          echo "Step var: $STEP_VAR"

Quick Reference

Common Triggers

on:
  push:                    # Code pushed
  pull_request:           # PR opened/updated
  schedule:               # Cron schedule
  workflow_dispatch:      # Manual trigger
  release:                # Release created
  issue_comment:          # Comment on issue/PR
  workflow_call:          # Called from another workflow

Runner Options

runs-on: ubuntu-latest          # Linux (fastest, cheapest)
runs-on: macos-latest           # macOS
runs-on: windows-latest         # Windows
runs-on: [self-hosted, linux]   # Self-hosted runner

Useful Actions

actions/checkout@v4              # Clone repository
actions/setup-node@v4            # Setup Node.js
actions/setup-python@v5          # Setup Python
actions/cache@v4                 # Cache dependencies
actions/upload-artifact@v4       # Upload artifacts
actions/download-artifact@v4     # Download artifacts
github/codeql-action@v3          # Code scanning

Context Variables

${{ github.event_name }}         # Event that triggered workflow
${{ github.ref }}                # Branch or tag ref
${{ github.sha }}                # Commit SHA
${{ github.actor }}              # User who triggered
${{ runner.os }}                 # Runner OS (Linux, macOS, Windows)
${{ secrets.SECRET_NAME }}       # Access secrets
${{ env.VAR_NAME }}              # Environment variable

Status Check Functions

if: success()       # Previous steps succeeded (default)
if: failure()       # Previous step failed
if: always()        # Run regardless of status
if: cancelled()     # Workflow was cancelled

Anti-Patterns

❌ Hardcoded Secrets

# WRONG: Secrets in plain text
env:
  API_KEY: abc123xyz
  DATABASE_URL: postgresql://user:pass@host/db

# CORRECT: Use GitHub Secrets
env:
  API_KEY: ${{ secrets.API_KEY }}
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

❌ No Caching

# WRONG: Install dependencies every time
- run: npm install

# CORRECT: Cache dependencies
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm ci

❌ Sequential Jobs (When Parallel is Possible)

# WRONG: Sequential tests
jobs:
  test-unit:
    runs-on: ubuntu-latest
    steps: [...]

  test-integration:
    needs: test-unit
    runs-on: ubuntu-latest
    steps: [...]

# CORRECT: Parallel tests
jobs:
  test-unit:
    runs-on: ubuntu-latest
    steps: [...]

  test-integration:
    runs-on: ubuntu-latest
    steps: [...]

  deploy:
    needs: [test-unit, test-integration]
    steps: [...]

❌ Using `npm install` Instead of `npm ci`

# WRONG: Non-deterministic installs
- run: npm install

# CORRECT: Reproducible installs
- run: npm ci

❌ Rebuilding Artifacts

# WRONG: Build in multiple jobs
jobs:
  test:
    steps:
      - run: npm run build
      - run: npm test

  deploy:
    steps:
      - run: npm run build
      - run: ./deploy.sh

# CORRECT: Build once, share artifacts
jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  test:
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
      - run: npm test

❌ No Matrix for Multi-Platform

# WRONG: Separate jobs for each platform
jobs:
  test-ubuntu:
    runs-on: ubuntu-latest
    steps: [...]

  test-macos:
    runs-on: macos-latest
    steps: [...]

# CORRECT: Use matrix
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps: [...]

Related Skills

collaboration/github/github-pull-requests.md - PR workflow and code review integration with workflows
collaboration/github/github-security-features.md - Security scanning and dependency management in Actions
collaboration/github/github-repository-management.md - Repository settings and configuration
cicd/ci-testing-strategy.md - Test execution patterns in CI
cicd/cd-deployment-patterns.md - Deployment strategies and rollbacks
cicd/ci-optimization.md - Speed and efficiency improvements
cicd/ci-security.md - Secret management and security best practices

Level 3: Resources

Overview

Comprehensive resources for GitHub Actions CI/CD implementation including complete reference documentation, validation and optimization tools, and production-ready workflow examples.

Resources Structure

REFERENCE.md (3,843 lines)

Complete GitHub Actions reference covering:

Fundamentals: GitHub Actions architecture, workflow lifecycle, pricing/limits
Workflow Syntax: Complete YAML syntax, triggers, permissions, concurrency
Triggers and Events: All event types with examples (push, PR, schedule, workflow_dispatch)
Jobs and Steps: Configuration, dependencies, conditions, service containers
Runners: GitHub-hosted and self-hosted runners, environments
Contexts and Expressions: All context objects, expression syntax, functions
Actions: Using marketplace actions, creating composite actions
Caching Strategies: Language-specific caching, Docker layer caching
Artifacts: Upload/download patterns, release assets
Matrix Builds: Multi-platform/version testing, exclusions, inclusions
Reusable Workflows: Creation and usage patterns with inputs/outputs
Security: OIDC authentication, permissions, secret management, pull_request_target safety
Performance Optimization: Parallelization, path filters, concurrency control
Monorepo Strategies: Path-based change detection, selective testing
Common Patterns: Complete CI/CD pipelines, Docker builds, security scanning
Anti-Patterns: Security, performance, and workflow anti-patterns with fixes
Debugging: Enable debug logging, inspect contexts, troubleshoot common issues

Location: ./resources/REFERENCE.md

Scripts

validate_workflow.py (576 lines) Validates GitHub Actions workflow files for syntax, security, and best practices.

Features:

Parse and validate YAML syntax
Detect security issues (hardcoded secrets, dangerous pull_request_target usage)
Check for outdated action versions
Identify caching opportunities
Validate permissions configuration
Suggest best practices (concurrency control, npm ci vs npm install)
JSON and human-readable output

Usage:

# Validate single workflow
./resources/scripts/validate_workflow.py .github/workflows/ci.yml

# Validate directory with JSON output
./resources/scripts/validate_workflow.py .github/workflows/ --json

# Recursive validation with fix suggestions
./resources/scripts/validate_workflow.py . --recursive --fix-suggestions

optimize_pipeline.py (669 lines) Analyzes workflows and suggests optimizations for performance and cost.

Features:

Identify parallelization opportunities
Detect duplicate builds and artifact rebuilding
Suggest caching improvements
Find matrix build opportunities
Calculate cost optimization potential
Recommend performance enhancements (path filters, shallow checkouts)
Estimate time and cost savings

Usage:

# Analyze single workflow
./resources/scripts/optimize_pipeline.py .github/workflows/ci.yml

# JSON output with implementation details
./resources/scripts/optimize_pipeline.py workflow.yml --json --suggestions

test_actions.sh (416 lines) Tests GitHub Actions workflows locally using act (nektos/act).

Features:

Run workflows locally with Docker
Test different event triggers
Measure execution time
Validate workflow outputs
List available workflows
Support for dry-run mode
JSON output for CI integration

Usage:

# Test workflow with push event
./resources/scripts/test_actions.sh --workflow ci.yml --event push

# Test specific job
./resources/scripts/test_actions.sh --workflow ci.yml --job build

# List all workflows
./resources/scripts/test_actions.sh --list

# Dry run
./resources/scripts/test_actions.sh --workflow ci.yml --dry-run

Dependencies:

act: brew install act or gh extension install nektos/gh-act
Docker (required by act)

Examples

workflows/python-ci.yml Complete Python CI pipeline with:

Lint and format checking (ruff, black, isort, mypy)
Multi-version testing (Python 3.10, 3.11, 3.12)
Service containers (PostgreSQL, Redis)
Security scanning (Safety, Bandit)
Build and distribution packaging
Documentation build
Coverage reporting with Codecov
Status check job for branch protection

workflows/nodejs-ci-cd.yml Full Node.js CI/CD pipeline with:

Multi-stage pipeline (install, lint, test, build, docker, e2e)
Multi-version testing (Node 18, 20, 22)
Docker image build and push to GHCR
E2E tests with Playwright
Deployment to staging and production environments
Artifact management and cleanup
GitHub Packages integration

workflows/monorepo-matrix.yml Monorepo CI with efficient change detection:

Path-based change detection using dorny/paths-filter
Matrix builds for multiple packages
Conditional job execution (only run if package changed)
Integration and E2E tests for affected services
Parallel deployment of changed services
Service containers for integration tests

workflows/reusable-workflow.yml Reusable deployment workflow demonstrating:

Workflow inputs and secrets
Environment configuration
Health checks and validation
Deployment timing and outputs
Rollback on failure
Slack notifications
Smoke tests after deployment

actions/custom-action/action.yml Composite action for multi-language setup:

Support for Node.js, Python, Go, Rust
Automatic caching configuration
Version detection and validation
Custom install commands
Timing and performance metrics
GitHub step summary output

workflows/security-scan.yml Security scanning workflow with:

CodeQL analysis for multiple languages
Dependency vulnerability scanning with Trivy
Secrets detection with Gitleaks
Docker image scanning
SARIF upload to GitHub Security
Scheduled weekly scans

workflows/caching-strategy.yml Advanced caching patterns for:

Multi-layer Node.js caching (npm + node_modules + build cache)
Docker layer caching with GitHub Actions cache
Rust incremental build caching
Python pip and venv caching
Monorepo selective caching

Quick Start

Validate existing workflows:

./resources/scripts/validate_workflow.py .github/workflows/ --recursive

Optimize pipeline:

./resources/scripts/optimize_pipeline.py .github/workflows/ci.yml

Test locally:

./resources/scripts/test_actions.sh --workflow ci.yml --event push

Use as template:

Copy examples from ./resources/examples/workflows/ to your .github/workflows/ directory.

Create composite action:

Copy and customize ./resources/examples/actions/custom-action/ to .github/actions/.

Reference Links

Complete documentation: REFERENCE.md
Official GitHub Actions docs: https://docs.github.com/en/actions
Workflow syntax: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
Actions Marketplace: https://github.com/marketplace?type=actions
act tool: https://github.com/nektos/act

Last Updated: 2025-10-27

Format Version: 1.0 (Atomic)

collaboration-github-actions-workflows

GitHub Actions Workflows

When to Use This Skill

Core Concepts

Workflow Structure

Key Components

Execution Model

Patterns

Basic Workflow Structure

Advanced Triggers

Matrix Builds

Job Dependencies

Caching Dependencies

Artifacts

Conditional Execution

Reusable Workflows

Composite Actions

Environment Variables and Contexts

Quick Reference

Common Triggers

Runner Options

Useful Actions

Context Variables

Status Check Functions

Anti-Patterns

❌ Hardcoded Secrets

❌ No Caching

❌ Sequential Jobs (When Parallel is Possible)

❌ Using npm install Instead of npm ci

❌ Rebuilding Artifacts

❌ No Matrix for Multi-Platform

Related Skills

Level 3: Resources

Overview

Resources Structure

REFERENCE.md (3,843 lines)

Scripts

Examples

Quick Start

Reference Links

❌ Using `npm install` Instead of `npm ci`