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
References
- Workflow syntax, triggers, jobs, steps, and concurrency
- Caching strategies and artifact management
- Matrix strategies, reusable workflows, and composite actions
- Security, secrets, OIDC, and permissions hardening
1---2name: github-actions3description: 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.4license: MIT5---6
7# GitHub Actions
8
9## Overview
10
11GitHub 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.
12
13**When to use:** Automated testing, continuous deployment, release automation, scheduled tasks, multi-platform builds, dependency updates, container publishing, code quality checks, security scanning.
14
15**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).
16
17## Quick Reference
18
19| Pattern | Syntax / Action | Key Points |
20| ------------------- | ------------------------------------------------ | ------------------------------------------- |
21| Push trigger | `on: push: branches: [main]` | Filter by branch, path, or tag |
22| PR trigger | `on: pull_request: types: [opened, synchronize]` | Defaults to opened, synchronize, reopened |
23| Scheduled trigger | `on: schedule: - cron: '0 6 * * 1'` | UTC only, minimum 5-minute interval |
24| Manual trigger | `on: workflow_dispatch: inputs:` | Define typed inputs for manual runs |
25| Job dependencies | `needs: [build, test]` | Run jobs in sequence or parallel |
26| Conditional job | `if: github.ref == 'refs/heads/main'` | Expression-based job/step filtering |
27| Matrix strategy | `strategy: matrix: node: [18, 20, 22]` | Generates jobs for each combination |
28| Dependency cache | `actions/cache@v5` | Hash-based keys with restore-keys fallback |
29| Setup with cache | `actions/setup-node@v6` with `cache: 'pnpm'` | Built-in caching for package managers |
30| Upload artifact | `actions/upload-artifact@v4` | Share data between jobs or preserve outputs |
31| Download artifact | `actions/download-artifact@v4` | Retrieve artifacts from earlier jobs |
32| Reusable workflow | `uses: ./.github/workflows/reusable.yml` | Called with `workflow_call` trigger |
33| Composite action | `action.yml` with `using: composite` | Bundle multiple steps into one action |
34| Concurrency | `concurrency: group: ${{ github.ref }}` | Cancel or queue duplicate runs |
35| Environment secrets | `${{ secrets.API_KEY }}` | Scoped to repo, org, or environment |
36| OIDC authentication | `permissions: id-token: write` | Short-lived tokens for cloud providers |
37| Step outputs | `echo "key=value" >> "$GITHUB_OUTPUT"` | Pass data between steps and jobs |
38| Service containers | `services: postgres: image: postgres:16` | Sidecar containers for integration tests |
39| Timeout | `timeout-minutes: 30` | Fail fast on hung jobs or steps |
40| Attestations | `actions/attest-build-provenance@v3` | SLSA build provenance for supply chain |
41
42## Expressions and Contexts
43
44| Context | Example | Description |
45| --------- | ------------------------------- | ----------------------------------------- |
46| `github` | `github.ref_name`, `github.sha` | Event metadata, repo info, actor |
47| `env` | `env.NODE_ENV` | Environment variables at current scope |
48| `secrets` | `secrets.API_KEY` | Encrypted secrets (masked in logs) |
49| `inputs` | `inputs.environment` | Workflow dispatch or reusable inputs |
50| `matrix` | `matrix.node` | Current matrix combination values |
51| `steps` | `steps.build.outputs.version` | Outputs from previous steps |
52| `needs` | `needs.prepare.outputs.tag` | Outputs from dependent jobs |
53| `runner` | `runner.os`, `runner.arch` | Runner environment info |
54| `vars` | `vars.DEPLOY_URL` | Repository or org configuration variables |
55
56## Common Mistakes
57
58| Mistake | Correct Pattern |
59| -------------------------------------------- | -------------------------------------------------------------------------- |
60| Using outdated action major versions | Pin to current major version (`@v6`) or commit SHA |
61| Missing `persist-credentials: false` | Set on checkout when using custom tokens or OIDC |
62| Broad `permissions` at workflow level | Set `permissions: {}` at workflow level, grant per-job |
63| Cache key without dependency file hash | Include `hashFiles('**/pnpm-lock.yaml')` in cache key |
64| Secrets in `if:` conditions | Secrets cannot be used in `if:` expressions directly |
65| Using `pull_request_target` carelessly | Never run PR code with write permissions from `pull_request_target` |
66| Not cancelling stale runs | Use `concurrency` with `cancel-in-progress: true` |
67| Storing structured data as a single secret | Create individual secrets per value for proper log redaction |
68| Referencing action tags without SHA pinning | Pin third-party actions to full commit SHA for supply chain safety |
69| Hardcoding runner OS in scripts | Use `runner.os` context for cross-platform compatibility |
70| Using `actions/cache` without `restore-keys` | Always provide restore-keys for partial cache matches |
71| Interpolating user input in `run:` blocks | Pass untrusted values through `env:` to prevent script injection |
72| No `timeout-minutes` on jobs | Set explicit timeouts to fail fast on hung processes |
73| Using `always()` without scoping | Combine with status checks: `if: always() && steps.x.outcome == 'success'` |
74
75## Delegation
76
77- **Workflow debugging**: Use `Explore` agent to inspect workflow run logs
78- **Security auditing**: Use `Task` agent to review permissions and secret usage
79- **Code review**: Delegate to `code-reviewer` agent for workflow PR reviews
80
81## References
82
83- [Workflow syntax, triggers, jobs, steps, and concurrency](references/workflow-syntax.md)
84- [Caching strategies and artifact management](references/caching-and-artifacts.md)
85- [Matrix strategies, reusable workflows, and composite actions](references/matrix-and-reusable.md)
86- [Security, secrets, OIDC, and permissions hardening](references/security-and-secrets.md)
oakoss