name: github-actions description: GitHub Actions workflow authoring for CI/CD pipelines. Covers workflow syntax, triggers, jobs, steps, matrix strategies, caching, artifacts, reusable workflows, composite actions, secrets management, OIDC authentication, and permissions hardening. Use when creating workflows, configuring jobs, setting up caching, or automating releases. Use for github-actions, workflow, ci, cd, actions, jobs, steps, matrix, cache, artifact, secrets, reusable-workflow. license: MIT metadata: author: oakoss version: '1.1' source: 'https://docs.github.com/en/actions'

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: [22, 24]`	Generates jobs for each combination
Dependency cache	`actions/cache@v4`	Hash-based keys with restore-keys fallback
Setup with cache	`actions/setup-node@v4` 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 `actions/checkout@v4` or older tags	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

github-actions