GitHub Actions Workflow Conventions

Naming, structure, and organizational patterns for workflows

Language / Topic

GitHub Actions

Rules

GitHub Actions Workflow Conventions · balanced balanced

- Name workflows descriptively: "CI" for continuous integration, "Deploy Production", "Release"

- Use kebab-case for workflow filenames: ci.yml, deploy-production.yml, release-please.yml

- Group related steps with clear name labels: name: "Install dependencies", name: "Run tests"

- Set timeout-minutes on every job to prevent hung workflows from consuming runner minutes

- Use workflow_dispatch with inputs for manual triggers that need parameters

- Descriptive workflow names: CI, Deploy to Production, Release, Security Scan — visible in Actions tab and PR checks

- File naming: kebab-case .yml files: ci.yml, deploy-staging.yml, codeql-analysis.yml

- Step naming: every step gets a name: for readability in logs and failure identification

- timeout-minutes on all jobs: 10 for lint/test, 30 for builds, 60 for E2E tests — prevent runaway costs

- workflow_dispatch with typed inputs for manual operations: environment, version, dry-run flag

- Use job dependency chain: needs: [lint, test] for build job; parallelize independent jobs

- Consistent trigger patterns: push to main, pull_request to main, schedule for nightly, workflow_dispatch for manual

- Environment variables: define at workflow level for shared values, job level for job-specific, step level for step-specific

- Use YAML anchors or env blocks at the top for shared configuration: node version, registry URLs

- Fail fast: set fail-fast: true on matrix jobs (default); false when you want all combinations to complete

- Cache aggressively: actions/cache for node_modules, pip, go modules — restore key with hash of lockfile