github-actions

GitHub Actions Code Review Rules

Security (Critical)

• •Pin actions to full commit SHA (not @v1 or @main)
• •Use minimal permissions block (principle of least privilege)
• •Never echo secrets or use them in URLs
• •Use secrets.GITHUB_TOKEN instead of PATs when possible
• •Audit third-party actions before use
• •Review expressions (${{ }}) for injection risks; never interpolate untrusted user input
• •Validate all inputs to reusable workflows and custom actions

Permissions

permissions:
  contents: read  # Minimal by default
  # Add only what's needed:
  # pull-requests: write
  # issues: write

Secrets

• •Store secrets in repository/organization secrets
• •Use environments for production secrets with approvals
• •Don't pass secrets as command arguments (visible in logs)
• •Mask sensitive output with ::add-mask::
• •Never write secrets to files or artifacts (can be exposed)
• •Avoid passing secrets via environment variables unless absolutely required
• •Secrets in env vars can be visible in process listings

Performance

• •Use caching for dependencies (actions/cache or built-in)
• •Run independent jobs in parallel
• •Use concurrency to cancel redundant runs
• •Consider self-hosted runners for heavy workloads

Workflow Structure

• •Use reusable workflows for common patterns
• •Use composite actions for shared steps
• •Set appropriate timeout-minutes to prevent hung jobs
• •Use if: conditions to skip unnecessary jobs
• •Separate CI (testing), CD (deployments), and PR checks into distinct workflows
• •Use environments to distinguish between dev, staging, and production
• •Avoid mixing all concerns in a single monolithic workflow

Triggers

• •Be specific with paths and branches filters
• •Use workflow_dispatch for manual triggers
• •Consider pull_request_target security implications

Common Anti-patterns

• •Avoid actions/checkout with persist-credentials: true unless needed
• •Avoid running on push to all branches
• •Avoid hardcoding versions that need updates

Action Updates and Maintenance

• •Monitor pinned action SHAs for security fixes
• •Subscribe to security advisories for actions you use
• •Update actions regularly to get new features and fixes
• •Document why specific SHAs are pinned (security, stability)
• •Consider using Dependabot for action version updates

Testing and Validation

• •Lint workflows with tools like actionlint
• •Test complex workflows in feature branches before merging
• •Validate workflow syntax before committing
• •Use workflow templates for consistency
• •Add job-level tests for workflow logic validation

Error Handling

• •Use continue-on-error: false as default (explicit failure)
• •Set fail-fast: true for matrix jobs to stop on first failure
• •Only use continue-on-error: true when failure is acceptable
• •Provide clear error messages in job outputs
• •Use status checks to ensure critical jobs pass

Documentation

• •Add inline comments for complex workflow logic
• •Document workflow purpose and triggers
• •Maintain workflow README or documentation
• •Explain environment variables and their usage
• •Document required secret names and their purpose (never include actual secret values)