GitHub Actions Expertise

Comprehensive knowledge for creating, reviewing, and optimizing GitHub Actions workflows with current action versions and best practices.

Environment

!command -v actionlint 2>/dev/null && echo "actionlint: installed" || echo "actionlint: not installed" !command -v act 2>/dev/null && echo "act: installed" || echo "act: not installed"

If either tool is missing, suggest the user install them:

• brew install actionlint — workflow linter that catches syntax errors, type mismatches, and expression problems offline
• brew install act — runs workflows locally in Docker without pushing

Quick Reference

Action Versions

Consult actions-index.json in this skill directory for current versions of 120+ popular actions. The index is updated daily and organized by category.

Always verify versions before recommending — use the index or fetch from GitHub releases if needed.

Core Patterns

Pattern	When to Use	Reference
Matrix builds	Test across versions/platforms	references/patterns-matrix-builds.md
Caching	Speed up dependency installation	references/patterns-caching.md
Artifacts	Share files between jobs	references/patterns-artifacts.md
Reusable workflows	Share workflows across repos	references/patterns-reusable-workflows.md
Concurrency	Prevent duplicate runs	references/patterns-concurrency.md
Environments	Deployment gates/approvals	references/patterns-environments.md
Composite actions	Create custom actions	references/patterns-composite-actions.md

Security Essentials

Topic	Key Points	Reference
Secrets	Never hardcode, use OIDC when possible	references/security-secrets.md
Permissions	Principle of least privilege	references/security-hardening.md
Supply chain	Pin actions, review dependencies	references/security-supply-chain.md

Workflow Essentials

Every workflow should include these often-missed fields:

permissions:
  contents: read

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

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30

Full JSON Schema for workflow validation: references/github-action.schema.json

Essential Workflow Patterns

Dependency Caching

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

For custom caching, see references/patterns-caching.md.

Matrix Strategy

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    node: [18, 20, 22]
    exclude:
      - os: windows-latest
        node: 18
    include:
      - os: ubuntu-latest
        node: 20
        coverage: true

Job Dependencies

jobs:
  build:
    runs-on: ubuntu-latest
    steps: [...]

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

  deploy:
    needs: [build, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps: [...]

For conditional execution patterns (if:, always(), failure()), trigger event configuration, and expression syntax, see references/triggers.md and references/expressions.md.

Security Best Practices

Minimal Permissions

permissions:
  contents: read

jobs:
  build:
    permissions:
      contents: read

  deploy:
    permissions:
      contents: read
      id-token: write
      packages: write

Pin Action Versions

# Good: Pin to full SHA
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1

# Acceptable: Pin to major version
- uses: actions/checkout@v6

# Bad: Unpinned or floating
- uses: actions/checkout@main
- uses: actions/checkout

OIDC for Cloud Authentication

Prefer OIDC over long-lived credentials. See references/security-secrets.md for setup guides for AWS, GCP, and Azure.

When reviewing workflows, generate an ASCII flowchart showing job dependencies.

Validating Workflows

Before pushing workflow changes, verify correctness:

1. Lint with actionlint — catches syntax errors, type mismatches, and expression problems that YAML parsers miss:

   actionlint .github/workflows/*.yml
   

2. Test locally with act — runs workflows in Docker without pushing:

   act push --job build
   act pull_request -e event.json
   

3. Check workflow run logs — after pushing, verify in the Actions tab:

   • Confirm expected jobs triggered
   • Check for deprecation warnings in logs
   • Verify caching is hitting (cache hit: true)

4. Validate secrets access — workflows fail silently when secrets are missing. Verify required secrets exist in repo/org settings before relying on them.

Workflow Analysis Checklist

When reviewing workflows, check:

Versions

• All actions use current major versions (consult actions-index.json)
• Consider pinning to SHA for security-critical workflows
• No deprecated action versions

Performance

• Dependencies are cached appropriately
• Parallel jobs where dependencies allow
• timeout-minutes set to prevent runaway jobs
• fail-fast: false if matrix jobs are independent

Security

• Minimal permissions declared
• No secrets in logs (add-mask for dynamic secrets)
• OIDC preferred over long-lived credentials
• Third-party actions reviewed for security

Reliability

• concurrency configured to prevent duplicate runs
• Conditional execution (if:) used appropriately
• continue-on-error only where truly needed
• Retry logic for flaky external calls

Maintainability

• Descriptive job and step names
• Reusable workflows for shared logic
• Environment variables for repeated values
• Comments for complex logic

Additional Resources

All reference files are in references/:

File	Topic
workflow-syntax.md	Complete workflow YAML reference
expressions.md	Expression syntax, contexts, functions
triggers.md	All event triggers with examples
runners.md	Runner selection, self-hosted setup
permissions.md	GITHUB_TOKEN scopes, OIDC setup
troubleshooting.md	Common errors and solutions
patterns-matrix-builds.md	Matrix strategies, include/exclude
patterns-caching.md	Cache action, custom keys, restore strategies
patterns-artifacts.md	Upload/download, retention, cross-job sharing
patterns-reusable-workflows.md	workflow_call, inputs, secrets
patterns-concurrency.md	Groups, cancel-in-progress
patterns-environments.md	Deployment environments, protection rules
patterns-composite-actions.md	Creating custom actions
security-secrets.md	Management, rotation, OIDC setup
security-hardening.md	Permissions, pinning, CodeQL
security-supply-chain.md	Dependency review, Dependabot

Working templates in examples/: ci-node.yaml, ci-rust.yaml, deploy-aws.yaml, release-please.yaml

• actions-index.json — Current versions of 120+ popular actions (updated daily)
• tracked-actions.yaml — List of tracked actions by category