GitHub Actions

Overview

GitHub Actions is a CI/CD platform that automates build, test, and deployment pipelines directly from GitHub repositories. Workflows are YAML files in .github/workflows/ triggered by events like pushes, pull requests, schedules, or manual dispatch. Each workflow contains one or more jobs that run on GitHub-hosted or self-hosted runners.

When to use: Automated testing, continuous deployment, release automation, scheduled tasks, multi-platform builds, dependency updates, container publishing, code quality checks, security scanning.

When NOT to use: Long-running services (use a proper hosting platform), heavy compute tasks exceeding runner limits (6-hour job timeout), tasks requiring persistent state between runs (use external storage), real-time event processing (use webhooks with a server).

Quick Reference

Pattern	Syntax / Action	Key Points
Push trigger	`on: push: branches: [main]`	Filter by branch, path, or tag
PR trigger	`on: pull_request: types: [opened, synchronize]`	Defaults to opened, synchronize, reopened
Scheduled trigger	`on: schedule: - cron: '0 6 * * 1'`	UTC only, minimum 5-minute interval
Manual trigger	`on: workflow_dispatch: inputs:`	Define typed inputs for manual runs
Job dependencies	`needs: [build, test]`	Run jobs in sequence or parallel
Conditional job	`if: github.ref == 'refs/heads/main'`	Expression-based job/step filtering
Matrix strategy	`strategy: matrix: node: [18, 20, 22]`	Generates jobs for each combination
Dependency cache	`actions/cache@v5`	Hash-based keys with restore-keys fallback
Setup with cache	`actions/setup-node@v6` with `cache: 'pnpm'`	Built-in caching for package managers
Upload artifact	`actions/upload-artifact@v4`	Share data between jobs or preserve outputs
Download artifact	`actions/download-artifact@v4`	Retrieve artifacts from earlier jobs
Reusable workflow	`uses: ./.github/workflows/reusable.yml`	Called with `workflow_call` trigger
Composite action	`action.yml` with `using: composite`	Bundle multiple steps into one action
Concurrency	`concurrency: group: ${{ github.ref }}`	Cancel or queue duplicate runs
Environment secrets	`${{ secrets.API_KEY }}`	Scoped to repo, org, or environment
OIDC authentication	`permissions: id-token: write`	Short-lived tokens for cloud providers
Step outputs	`echo "key=value" >> "$GITHUB_OUTPUT"`	Pass data between steps and jobs
Service containers	`services: postgres: image: postgres:16`	Sidecar containers for integration tests
Timeout	`timeout-minutes: 30`	Fail fast on hung jobs or steps
Attestations	`actions/attest-build-provenance@v3`	SLSA build provenance for supply chain

Expressions and Contexts

Context	Example	Description
`github`	`github.ref_name`, `github.sha`	Event metadata, repo info, actor
`env`	`env.NODE_ENV`	Environment variables at current scope
`secrets`	`secrets.API_KEY`	Encrypted secrets (masked in logs)
`inputs`	`inputs.environment`	Workflow dispatch or reusable inputs
`matrix`	`matrix.node`	Current matrix combination values
`steps`	`steps.build.outputs.version`	Outputs from previous steps
`needs`	`needs.prepare.outputs.tag`	Outputs from dependent jobs
`runner`	`runner.os`, `runner.arch`	Runner environment info
`vars`	`vars.DEPLOY_URL`	Repository or org configuration variables

Common Mistakes

Mistake	Correct Pattern
Using outdated action major versions	Pin to current major version (`@v6`) or commit SHA
Missing `persist-credentials: false`	Set on checkout when using custom tokens or OIDC
Broad `permissions` at workflow level	Set `permissions: {}` at workflow level, grant per-job
Cache key without dependency file hash	Include `hashFiles('**/pnpm-lock.yaml')` in cache key
Secrets in `if:` conditions	Secrets cannot be used in `if:` expressions directly
Using `pull_request_target` carelessly	Never run PR code with write permissions from `pull_request_target`
Not cancelling stale runs	Use `concurrency` with `cancel-in-progress: true`
Storing structured data as a single secret	Create individual secrets per value for proper log redaction
Referencing action tags without SHA pinning	Pin third-party actions to full commit SHA for supply chain safety
Hardcoding runner OS in scripts	Use `runner.os` context for cross-platform compatibility
Using `actions/cache` without `restore-keys`	Always provide restore-keys for partial cache matches
Interpolating user input in `run:` blocks	Pass untrusted values through `env:` to prevent script injection
No `timeout-minutes` on jobs	Set explicit timeouts to fail fast on hung processes
Using `always()` without scoping	Combine with status checks: `if: always() && steps.x.outcome == 'success'`

Delegation

Workflow debugging: Use Explore agent to inspect workflow run logs
Security auditing: Use Task agent to review permissions and secret usage
Code review: Delegate to code-reviewer agent for workflow PR reviews