prulloac/github-workflows

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/:

| Template | File | Use Case | |---|---|---| | CI | assets/ci.yml | Build, lint, and test on push/PR | | Deploy | assets/deploy.yml | Deploy to staging/production environments | | Release | assets/release.yml | Create releases on tag push, publish packages | | PR Checks | assets/pr-checks.yml | Auto-label, size checks, PR automation | | Scheduled | assets/scheduled.yml | Cron-based maintenance, cleanup, reports | | Docker | assets/docker.yml | Build and push container images to GHCR |

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:

| Indicator File | Setup Action | Cache | Lockfile | |---|---|---|---| | package.json | actions/setup-node@v4 | npm/yarn/pnpm | package-lock.json, yarn.lock, pnpm-lock.yaml | | pyproject.toml, requirements.txt | actions/setup-python@v5 | pip/poetry | requirements.txt, poetry.lock | | go.mod | actions/setup-go@v5 | true | go.sum | | Cargo.toml | dtolnay/rust-toolchain@stable | manual | Cargo.lock | | pom.xml | actions/setup-java@v4 | maven | N/A | | build.gradle | actions/setup-java@v4 | gradle | N/A | | Dockerfile | docker/setup-buildx-action@v3 | type=gha | N/A |

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)