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