Github Actions

GitHub Actions Workflow Generator

Generate production-ready GitHub Actions workflow YAML files. Supports CI, CD, releases, Docker, reusable workflows, composite actions, and dependabot configs across multiple languages and frameworks.

Principles

• Secure by default: Pin actions to SHA, minimal permissions, no hardcoded secrets
• Cache everything: Dependencies, build artifacts, Docker layers — always cache
• Fail fast, fail clear: Matrix fail-fast: true for CI, false for releases
• Concurrency control: Always add concurrency groups for push/PR workflows
• DRY workflows: Extract shared logic into reusable workflows or composite actions

MODE DETECTION (FIRST STEP)

Analyze the user's request to determine workflow type:

Phase 1: Project Detection (PARALLEL)

Execute ALL in parallel:

# Group 1: Language detection
ls composer.json package.json pubspec.yaml go.mod Cargo.toml pyproject.toml setup.py requirements.txt Gemfile pom.xml build.gradle 2>/dev/null

# Group 2: Framework detection
ls artisan next.config.* nuxt.config.* angular.json vite.config.* 2>/dev/null
cat composer.json 2>/dev/null | head -20
cat package.json 2>/dev/null | head -20

# Group 3: Existing workflows
ls .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null
ls .github/actions/*/action.yml 2>/dev/null
cat .github/dependabot.yml 2>/dev/null

# Group 4: CI tooling
ls .php-cs-fixer.dist.php phpstan.neon pint.json eslint.config.* .eslintrc* biome.json analysis_options.yaml .golangci.yml .flake8 pyproject.toml 2>/dev/null

# Group 5: Docker context
ls Dockerfile docker-compose.yml docker-compose.yaml 2>/dev/null

Mandatory output:

PROJECT DETECTION
=================
Language: [PHP 8.x | Dart/Flutter | Node.js | Bun | Go | Python | Rust | Java | Multi-stack]
Framework: [Laravel | Next.js | Flutter | Express | FastAPI | None | ...]
Package manager: [composer | npm | pnpm | yarn | bun | pub | go mod | pip | cargo]
Linter: [pint | eslint | biome | golangci-lint | ruff | dart analyze | none]
Test runner: [phpunit | artisan test | jest | vitest | bun test | flutter test | go test | pytest]
Docker: [yes | no]
Existing workflows: [list or none]

Phase 2: Template Selection

Select the base template from references/language-templates.md based on detected stack. Read the reference file for the matching language section.

Multi-stack projects: Generate separate jobs per language within one workflow, using defaults.run.working-directory to isolate contexts.

Phase 3: Security Hardening

Apply ALL of these to every generated workflow. Read references/security-patterns.md for detailed patterns.

Non-negotiable rules:

1. Pin actions to SHA — uses: actions/checkout@<sha> with version comment
2. Minimal permissions — permissions: block on every workflow, default contents: read
3. Concurrency groups — Prevent duplicate runs on force-push
4. No inline secrets — Always ${{ secrets.NAME }}, never hardcoded
5. Validate inputs — workflow_dispatch inputs must have types and descriptions

Permission mapping:

Phase 4: Workflow Generation (BLOCKING OUTPUT)

Present the complete workflow YAML. Consult references/workflow-syntax.md for exact syntax of triggers, expressions, contexts, and runners. Follow the structure order:

name:                    # Clear, descriptive name
on:                      # Triggers with filters
permissions:             # Minimal required
concurrency:             # Prevent duplicates
env:                     # Shared environment variables
defaults:                # Working directory, shell
jobs:                    # Job definitions
  job-name:
    runs-on:             # Runner selection
    timeout-minutes:     # Always set
    services:            # Database, cache containers
    strategy:            # Matrix builds
    env:                 # Job-level env
    steps:               # Step sequence

Step ordering within a job:

1. Checkout code
2. Setup language runtime (with cache)
3. Install dependencies (cached)
4. Lint / static analysis
5. Build (if needed)
6. Test (with coverage)
7. Upload artifacts / coverage
8. Deploy / publish (conditional)
9. Notify (on failure)

Mandatory output:

# Generated workflow with inline comments explaining:
# - Why each permission is needed
# - What each concurrency group prevents
# - Why specific actions are chosen
# - Cache strategy rationale

Phase 5: Verification

After writing the workflow file:

1. Validate YAML syntax — yq eval '.' .github/workflows/<file>.yml > /dev/null
2. Check action versions — verify SHA pins match expected versions
3. Verify no hardcoded secrets — grep for patterns like ghp_, sk-, Bearer
4. Confirm permissions are minimal — no write-all or missing permissions: block
5. Test trigger logic — verify branch filters match project's branching strategy

Debug Flow

When fixing broken workflows:

1. Read the workflow file
2. Run gh run list --workflow=<name>.yml --limit 5 to find recent failures
3. Run gh run view <id> --log-failed to get error details
4. Classify: syntax error, action version issue, permission issue, runtime failure
5. Fix and verify

Trigger Patterns

CI (push + PR)

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

CI with path filtering (monorepo)

on:
  push:
    branches: [main]
    paths:
      - 'packages/api/**'
      - '.github/workflows/api-ci.yml'
  pull_request:
    paths:
      - 'packages/api/**'

Deploy (manual + push)

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options: [staging, production]
  push:
    branches: [main]

Release (tag)

on:
  push:
    tags: ['v*.*.*']

Scheduled

on:
  schedule:
    - cron: '0 4 * * 1'  # Every Monday 4AM UTC

Reusable (called by other workflows)

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

Concurrency Patterns

# CI: Cancel outdated runs on same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Deploy: Never cancel, queue instead
concurrency:
  group: deploy-${{ inputs.environment }}
  cancel-in-progress: false

Service Container Patterns

services:
  postgres:
    image: postgres:17
    env:
      POSTGRES_DB: testing
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
    ports:
      - 5432:5432
    options: >-
      --health-cmd="pg_isready"
      --health-interval=10s
      --health-timeout=5s
      --health-retries=5

  redis:
    image: redis:7-alpine
    ports:
      - 6379:6379
    options: >-
      --health-cmd="redis-cli ping"
      --health-interval=10s
      --health-timeout=5s
      --health-retries=5

Artifact & Caching Patterns

# Dependency caching (built into setup-* actions)
- uses: actions/setup-node@<sha>  # v4
  with:
    node-version-file: '.nvmrc'
    cache: 'npm'

# Manual cache (for custom paths)
- uses: actions/cache@<sha>  # v4
  with:
    path: ~/.pub-cache
    key: ${{ runner.os }}-pub-${{ hashFiles('**/pubspec.lock') }}
    restore-keys: ${{ runner.os }}-pub-

# Upload test artifacts
- uses: actions/upload-artifact@<sha>  # v4
  if: failure()
  with:
    name: test-results
    path: test-results/
    retention-days: 7

# Upload coverage
- uses: codecov/codecov-action@<sha>  # v5
  with:
    files: coverage/lcov.info
    fail_ci_if_error: false

Matrix Strategies

# Node.js version matrix
strategy:
  fail-fast: true
  matrix:
    node-version: [18, 20, 22]

# Platform matrix
strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]

# Complex matrix with includes/excludes
strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20]
    include:
      - os: ubuntu-latest
        node: 22
    exclude:
      - os: macos-latest
        node: 18

Integration with Other Skills

• git-master: Commit workflow file changes following detected commit style. Use git-master for the commit, not raw git commit.
• github-cli: Use gh commands for workflow debugging (gh run view, gh run list), secret management (gh secret set), and variable management (gh variable set).

Anti-Patterns

• Unpinned actions (uses: actions/checkout@v4) → Pin to SHA with version comment
• Missing permissions: block → Always declare, default contents: read
• No concurrency group → Duplicate runs waste minutes
• runs-on: ubuntu-latest without timeout-minutes → Set 15–30 min for CI
• Hardcoded versions in run: steps → Use matrix or env vars
• npm install instead of npm ci → Use lockfile-based install
• Missing if: failure() on artifact upload → Only upload on failure
• continue-on-error: true on tests → Tests must fail the build
• write-all permissions → Declare only what's needed
• --force in deploy scripts → Use --force-with-lease or idempotent deploys

References

For detailed guidance on specific topics, read references/ when needed: