GitHub Actions Workflow Standards

GitHub Actions Workflow Standards

Standards for creating and maintaining CI/CD workflows in this repository. For general GitHub Actions best practices, rely on GitHub Actions documentation.

Project Conventions

Runner and Node.js

• Runner: ubuntu-latest for all jobs
• Node.js: Version 22 with npm caching
• Dependencies: npm ci (not npm install)

Permissions

• Set permissions at workflow level (least privilege)
• Default: contents: read
• Add write permissions only when needed (e.g., issues: write for freshness checks)

Triggers

• PR validation: Trigger on pull_request to main
• Post-merge: Trigger on push to main
• Path filters: Use paths: to scope workflows to relevant files
• Manual: Include workflow_dispatch for on-demand runs
• Scheduled: Use schedule with cron for periodic checks (e.g., weekly freshness)

Action Versions

• Pin to major version tags (e.g., @v4), not @main or @latest
• Use current versions:

Naming and Structure

• Workflow file: Descriptive kebab-case (e.g., docs-freshness.yml, agent-validation.yml)
• Workflow name: Human-readable title
• Job name: Clear, concise label
• Step name: Descriptive action (e.g., "Validate agent frontmatter")
• Start with a comment block describing purpose and trigger conditions

Concurrency

Use concurrency to prevent duplicate runs:

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

Existing Workflows

Validation Scripts

Workflows run these project validators:

Security

• Use OIDC for Azure authentication (no long-lived secrets)
• Use permissions: contents: read as the default
• Enable Dependabot for action version updates
• Never print secrets or tokens in workflow logs

Patterns to Avoid