Latest Updates (2024-2025):

• November 2025: Nested reusable workflows increased to 10 levels (was 4), total workflows to 50 (was 20)

• November 2025: M2-powered macOS runners with GPU acceleration (macos-latest-xlarge, macos-15-xlarge)

• December 2024 - January 2025: ubuntu-latest migrating from Ubuntu 22 to Ubuntu 24

• February-March 2025: Cache storage v1-v2 retirement - must use actions/cache@v4.0.0+

Action Types:

• Workflow files: CI/CD pipelines using existing actions (.github/workflows/*.yml)

• Custom JavaScript actions: Fast, cross-platform, use @actions/toolkit

• Custom Docker actions: Full environment control, specific tooling, slower startup

• Composite actions: Combine multiple steps into reusable units

<quick_start> Create a basic workflow:

.github/workflows/ci.yml

name: CI

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

jobs: test: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v4

  - name: Run tests
    run: npm test

Ruby/Rails with RSpec:

• uses: ruby/setup-ruby@v1 with: ruby-version: .ruby-version bundler-cache: true

• name: Setup database env: RAILS_ENV: test run: bin/rails db:setup

• name: Run tests run: bundle exec rspec

TypeScript/Node.js:

• uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm'

• run: npm ci

• run: npm run build --if-present

• run: npm test

Deploy to Fly.io:

• uses: superfly/flyctl-actions/setup-flyctl@master
• run: flyctl deploy --remote-only env: FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

</quick_start>

• Identify triggers: push, pull_request, workflow_dispatch, schedule, etc.

• Define jobs: Specify runner OS, steps, and dependencies

• Add security: Set GITHUB_TOKEN permissions to read-only, pin actions to SHA

• Optimize performance: Enable caching, use matrix builds for parallelization

• Test locally: Use act or GitHub CLI to test before pushing

Evaluating Workflows:

• Security scan: Check permissions, secrets exposure, action pinning, pull_request_target usage

• Performance analysis: Identify slow steps, missing caches, parallelization opportunities

• Best practices review: Validate naming, structure, error handling, documentation

• Troubleshooting: Review logs, check dependencies, verify secrets/environment variables

• YAML syntax valid (use yamllint or GitHub's workflow validator)

• Required secrets configured in repository settings

• GITHUB_TOKEN permissions explicitly set to minimum required

• Actions pinned to specific SHA or trusted tags

• Caching configured for dependencies (bundler, npm, etc.)

• Matrix builds used for multiple versions/platforms

• Workflow triggers appropriate for use case

Post-deployment monitoring:

• First run completes successfully

• Execution time acceptable (check for optimization opportunities if >5 minutes)

• No secrets or credentials in logs

• Cache hit rate >80% after first run

<security_checklist> Critical Security Patterns:

GITHUB_TOKEN permissions: Always set to read-only by default

permissions: contents: read

Pin actions to commit SHA (most secure):

• uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

Use OIDC for cloud deployments (credential-less authentication):

permissions: id-token: write contents: read

Avoid pull_request_target with untrusted code:

• Runs in base repository context with access to secrets

• Never checkout PR code without approval workflow

Environment secrets with required reviewers:

jobs: deploy: environment: production

Never log secrets:

• Use ::add-mask:: for dynamic values

• Avoid echo or print statements with secret variables

Audit action sources:

• Prefer verified creators (GitHub, major organizations)

• Review action source code before using

• Check for recent maintenance and security issues

See references/security-checklist.md for complete security guidelines. </security_checklist>

<common_patterns> Conditional execution:

• name: Deploy to production if: github.ref == 'refs/heads/main' && github.event_name == 'push' run: ./deploy.sh

Matrix builds:

strategy: matrix: ruby-version: ['3.1', '3.2', '3.3'] os: [ubuntu-latest, macos-latest] jobs: test: runs-on: ${{ matrix.os }}

Reusable workflows:

.github/workflows/reusable.yml

on: workflow_call: inputs: environment: required: true type: string

jobs: deploy: runs-on: ubuntu-latest steps: - run: echo "Deploying to ${{ inputs.environment }}"

.github/workflows/main.yml

jobs: call-reusable: uses: ./.github/workflows/reusable.yml with: environment: production

Secrets in composite actions:

Pass secrets explicitly - they're not inherited

• uses: ./.github/actions/my-action with: api-key: ${{ secrets.API_KEY }}

See references/common-workflows.md for Ruby/Rails, TypeScript, Heroku, and Fly.io patterns. </common_patterns>

<anti_patterns> Avoid these mistakes:

• Running as root in Docker actions: Use non-root user for security

• Hardcoded secrets: Always use GitHub Secrets

• Overly broad permissions: Set minimal required permissions

• No caching: Wastes time and resources on every run

• Sequential jobs that could be parallel: Use dependencies only when needed

• Using master branch references: Pin to tags or SHAs

• Ignoring security alerts: Review and address Dependabot alerts

• No timeout-minutes: Jobs can run for 6 hours by default

• Checkout without depth control: Use fetch-depth: 0 only when needed

• Manual apt-get installs: Use setup actions when available </anti_patterns>

name: Rails CI

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

permissions: contents: read

jobs: test: runs-on: ubuntu-latest

services:
  postgres:
    image: postgres:16
    env:
      POSTGRES_PASSWORD: postgres
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5
    ports:
      - 5432:5432

steps:
  - uses: actions/checkout@v4

  - uses: ruby/setup-ruby@v1
    with:
      ruby-version: .ruby-version
      bundler-cache: true

  - name: Setup database
    env:
      RAILS_ENV: test
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
    run: |
      bin/rails db:create
      bin/rails db:schema:load

  - name: Run tests
    env:
      RAILS_ENV: test
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
    run: bundle exec rspec

  - name: Run RuboCop
    run: bundle exec rubocop

deploy: needs: test if: github.ref == 'refs/heads/main' && github.event_name == 'push' runs-on: ubuntu-latest environment: production

steps:
  - uses: actions/checkout@v4

  - uses: superfly/flyctl-actions/setup-flyctl@master

  - run: flyctl deploy --remote-only
    env:
      FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

See references/common-workflows.md for more complete examples.

"Resource not accessible by integration"

• Add required permissions to GITHUB_TOKEN

• Check if job needs contents: write or pull-requests: write

Cache not restoring

• Verify cache key matches between save and restore

• Check if cache size exceeds 10GB limit

• Ensure actions/cache@v4+ for new cache backend

Secrets not available

• Verify secret is defined in repository/organization/environment settings

• Check if job requires environment for environment secrets

• Ensure secret name matches exactly (case-sensitive)

Action fails to find command

• Ensure setup action runs before command usage

• Check PATH modifications in previous steps

• Verify runner OS matches requirements

Timeout after 6 hours

• Add timeout-minutes: 30 to jobs or steps

• Investigate why job runs so long (missing cache, inefficient scripts)

See references/troubleshooting.md for detailed debugging strategies.

<performance_optimization> Key optimization strategies:

Dependency caching (can reduce build times by 80%):

• Ruby: Use ruby/setup-ruby with bundler-cache: true

• Node.js: Use actions/setup-node with cache: 'npm'

• Custom: Use actions/cache@v4 with hash keys from lock files

Parallelization:

• Use matrix builds for multiple versions/platforms

• Split independent jobs to run concurrently

• Avoid job dependencies unless actually required

Selective triggers:

on: push: paths: - 'src/**' - 'package.json'

Concurrency control (cancel outdated runs):

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

Self-hosted runners for heavy workloads:

• Persistent caching across runs

• Faster than GitHub-hosted for large builds

• More control over environment

See references/performance-optimization.md for advanced techniques. </performance_optimization>

<reference_guides> For detailed information on specific topics:

• Workflow Syntax: Complete YAML reference, triggers, jobs, steps, expressions

• Custom Actions: Building JavaScript, Docker, and composite actions

• Security Checklist: Comprehensive security patterns and OIDC setup

• Performance Optimization: Caching strategies, parallelization, profiling

• Common Workflows: Ruby/Rails, TypeScript, Heroku/Fly.io deployment templates

• Troubleshooting: Debugging workflows, common errors, log analysis

• Evaluation Guide: Security analysis, performance review, best practices audit </reference_guides>

<success_criteria> For workflow creation:

• Workflow file is valid YAML with correct syntax

• Triggers appropriate for use case

• Jobs execute successfully with expected outputs

• Security best practices applied (permissions, pinned actions, no secrets in logs)

• Performance optimized (caching, parallelization where appropriate)

• Documentation included (comments explaining non-obvious steps)

For workflow evaluation:

• Security issues identified and prioritized

• Performance bottlenecks documented with recommendations

• Best practice violations noted with fixes

• Overall assessment: PASS/FAIL/NEEDS_IMPROVEMENT with specific action items </success_criteria>