GitHub Workflows

Overview

Create and maintain GitHub Actions workflow YAML files in .github/workflows/. Includes starter templates for common workflow types and reference documentation for syntax, actions, and best practices.

Workflow

1. Determine workflow type — Identify which type(s) the user needs (CI, deploy, release, PR automation, scheduled, Docker).
2. Start from template — Copy the matching template from assets/ to .github/workflows/ as a starting point.
3. Customize for the project — Adapt the template to the project’s language, framework, and requirements. Detect the project’s ecosystem by examining files like package.json, go.mod, Cargo.toml, pyproject.toml, Makefile, Dockerfile, etc.
4. Apply best practices — Consult references/best-practices.md to harden security, optimize performance, and improve reliability.
5. Validate — Check for common syntax issues (see Validation section below).

Templates

Start from these templates in assets/:

Copy the relevant template, then replace TODO comments with project-specific configuration.

Customization Guide

Language/Framework Detection

Detect the project ecosystem and apply appropriate setup:

Common CI Commands by Ecosystem

Node.js: npm ci, npm run lint, npm test, npm run build Python: pip install -e ".[dev]", ruff check ., pytest, python -m build Go: go vet ./..., golangci-lint run, go test ./..., go build ./... Rust: cargo fmt --check, cargo clippy -- -D warnings, cargo test, cargo build --release

Key Patterns

Concurrency Control

Always add concurrency to prevent redundant runs:

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true  # false for deploy workflows

Minimal Permissions

permissions: read-all  # Workflow-level default

jobs:
  deploy:
    permissions:
      contents: read
      id-token: write  # Escalate only where needed

Reusable Workflows

Extract shared logic into .github/workflows/reusable-*.yml using workflow_call trigger. Callers invoke with uses: ./.github/workflows/reusable-build.yml.

Environment Protection

For deployment workflows, use GitHub environments with protection rules:

jobs:
  deploy:
    environment:
      name: production
      url: ${{ steps.deploy.outputs.url }}

Validation

After creating or editing a workflow, verify:

1. YAML syntax — Valid YAML with correct indentation (2 spaces)
2. Required keys — on and jobs are present at top level
3. Trigger correctness — Branch names and event types match the project
4. Permissions — Set explicitly, following least privilege
5. Timeouts — Every job has timeout-minutes set
6. Action versions — Actions use specific versions (e.g., @v4), not @main/@master
7. Secret references — All ${{ secrets.* }} references correspond to configured secrets
8. Path filters — paths and paths-ignore are not used together on the same trigger
9. Concurrency — Present on workflows triggered by push/PR to prevent redundant runs
10. Shell consistency — Cross-platform workflows explicitly set shell: bash

Reference Documentation

• Workflow Syntax Reference — Complete YAML syntax: triggers, jobs, steps, expressions, matrix, reusable workflows, and common pitfalls
• Common Actions Reference — Popular actions for checkout, setup, caching, artifacts, deployment, Docker, security, and cloud auth (OIDC)
• Best Practices — Security hardening, performance optimization, reliability patterns, and maintainability guidelines

Load these references when:

• Looking up specific syntax or configuration options
• Configuring actions not covered in the templates
• Applying security or performance best practices
• Setting up cloud provider authentication (OIDC)