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

• Determine workflow type -- Identify which type(s) the user needs (CI, deploy, release, PR automation, scheduled, Docker).

• Start from template -- Copy the matching template from assets/ to .github/workflows/ as a starting point.

• 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.

• Apply best practices -- Consult references/best-practices.md to harden security, optimize performance, and improve reliability.

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

• YAML syntax -- Valid YAML with correct indentation (2 spaces)

• Required keys -- on and jobs are present at top level

• Trigger correctness -- Branch names and event types match the project

• Permissions -- Set explicitly, following least privilege

• Timeouts -- Every job has timeout-minutes set

• Action versions -- Actions use specific versions (e.g., @v4 ), not @main /@master

• Secret references -- All ${{ secrets.* }} references correspond to configured secrets

• Path filters -- paths and paths-ignore are not used together on the same trigger

• Concurrency -- Present on workflows triggered by push/PR to prevent redundant runs

• 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)