| 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"} |
| user-invocable | false |
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 | |
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
