GitHub Actions 速查表
可搜索、可打印的 GitHub Actions 参考——工作流触发器、job、step、表达式、matrix、缓存和可复用工作流。免费。
Workflow skeleton & triggers
12.github/workflows/ci.yml
Where workflow files live
name: CI
Workflow display name
on: push
Run on every push
on: { push: { branches: [main] } }
Only pushes to main
on: { push: { tags: ["v*"] } }
Run on version tags
on: pull_request
Run on PR open/update
on: { pull_request: { paths: ["src/**"] } }
Only when paths change
on: { schedule: [{ cron: "0 6 * * 1" }] }
Cron: Mondays 06:00 UTC
on: workflow_dispatch
Manual "Run workflow" button
workflow_dispatch: { inputs: { env: { type: choice, options: [dev, prod] } } }
Manual run with inputs
on: { release: { types: [published] } }
Run when a release ships
on: workflow_call
Make workflow reusable
Jobs & runners
12jobs: { build: { runs-on: ubuntu-latest } }
Define a job and its runner
runs-on: [macos-latest / windows-latest]
Other hosted runner images
runs-on: [self-hosted, linux, x64]
Route to self-hosted by labels
needs: build
Run after another job
needs: [lint, test]
Wait for several jobs
if: github.ref == 'refs/heads/main'
Conditional job
container: node:22
Run job inside a Docker image
services: { redis: { image: redis:7, ports: ["6379:6379"] } }
Sidecar service container
outputs: { sha: ${{ steps.vars.outputs.sha }} }
Expose job outputs
needs.build.outputs.sha
Read another job's output
defaults: { run: { working-directory: app } }
Default dir for run steps
strategy: { fail-fast: false }
Keep matrix jobs running
Steps & popular actions
14- uses: actions/checkout@v4
Clone the repository
- uses: actions/checkout@v4 with fetch-depth: 0
Full history (tags, blame)
- uses: actions/setup-node@v4 with node-version: 22
Install Node.js
- uses: actions/setup-python@v5 with python-version: "3.12"
Install Python
- uses: shivammathur/setup-php@v2 with php-version: "8.3"
Install PHP
- run: npm ci && npm test
Run shell commands
- run: | (multiline)
Multi-line script step
- name: Build
Readable step name in logs
- id: vars
Reference step outputs later
echo "sha=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
Set a step output
echo "PATH_EXTRA=/opt/bin" >> "$GITHUB_ENV"
Set env for later steps
- uses: actions/upload-artifact@v4
Save build outputs
- uses: actions/download-artifact@v4
Fetch artifacts in later jobs
continue-on-error: true
Don't fail the job on error
Expressions & contexts
14${{ github.ref }}
Full ref, e.g. refs/heads/main
${{ github.ref_name }}
Branch or tag name only
${{ github.sha }}
Commit SHA being built
${{ github.event_name }}
Trigger: push, pull_request...
${{ github.actor }}
User who triggered the run
${{ github.repository }}
owner/repo string
${{ github.event.pull_request.number }}
Dig into the event payload
${{ secrets.API_KEY }}
Encrypted repo/org secret
${{ vars.SITE_URL }}
Non-secret config variable
${{ env.NODE_ENV }}
Environment variable
${{ runner.os }} / ${{ runner.temp }}
Runner OS and temp dir
${{ steps.vars.outputs.sha }}
Output of an earlier step
contains(), startsWith(), format()
Expression helper functions
GITHUB_TOKEN
Auto-provided per-run token
Conditionals & matrix
11if: success() / failure() / always()
Run based on prior status
if: cancelled()
Only when the run is cancelled
if: github.event_name == 'push'
Trigger-specific step
if: startsWith(github.ref, 'refs/tags/')
Only for tag builds
if: contains(github.event.head_commit.message, '[skip e2e]')
Commit-message switches
strategy: { matrix: { node: [20, 22] } }
One job per matrix value
matrix: { os: [ubuntu-latest, macos-latest], node: [20, 22] }
Cross-product matrix (4 jobs)
${{ matrix.node }}
Use the matrix value
matrix: { include: [{ os: ubuntu-latest, node: 23, experimental: true }] }
Add extra combos
matrix: { exclude: [{ os: macos-latest, node: 20 }] }
Drop combos
max-parallel: 2
Throttle concurrent matrix jobs
Caching & artifacts
11- uses: actions/cache@v4
Generic dependency cache
key: npm-${{ hashFiles('package-lock.json') }}
Cache key from lockfile hash
restore-keys: | npm-
Fallback prefix on miss
path: ~/.npm
What directory to cache
setup-node@v4 with cache: npm
Built-in npm cache (easiest)
setup-python@v5 with cache: pip
Built-in pip cache
upload-artifact@v4 with name/path
Store files for download
upload-artifact: retention-days: 5
Auto-delete artifacts
download-artifact@v4 (no name)
Download all artifacts
if-no-files-found: error
Fail if the path is empty
Cache limit: 10 GB per repo
Old caches get evicted
Environments & permissions
11permissions: { contents: read }
Least-privilege GITHUB_TOKEN
permissions: { contents: write, pull-requests: write }
Allow pushes + PR comments
permissions: { id-token: write }
OIDC for cloud auth (no keys)
environment: production
Use a deploy environment
environment: { name: prod, url: https://app.example.com }
Link shown on the run
Environment protection rules
Required reviewers, wait timer
env: { NODE_ENV: production }
Env at workflow/job/step level
secrets.GITHUB_TOKEN
Scoped to the current repo
Settings > Secrets and variables > Actions
Where to define secrets
Org secrets with repo allowlists
Share secrets across repos
pull_request_target — use with care
Runs with secrets on fork PRs
Reusable workflows & composite actions
11on: { workflow_call: { inputs: ..., secrets: ... } }
Declare a reusable workflow
jobs: { ci: { uses: org/repo/.github/workflows/ci.yml@v1 } }
Call a reusable workflow
uses: ./.github/workflows/ci.yml
Call one from the same repo
with: { node-version: 22 }
Pass inputs to the callee
secrets: inherit
Forward all caller secrets
${{ inputs.node-version }}
Read inputs in the callee
action.yml with runs: { using: composite }
Define a composite action
steps: - run: ... shell: bash
Composite steps need shell:
uses: ./.github/actions/setup
Use a local composite action
inputs/outputs in action.yml
Action interface definition
Nesting limit: 4 levels of reusable calls
Plan the call depth
Concurrency & timeouts
9concurrency: { group: deploy, cancel-in-progress: true }
Kill superseded runs
group: ${{ github.workflow }}-${{ github.ref }}
One run per branch
cancel-in-progress: false
Queue instead of cancel
timeout-minutes: 15 (job level)
Kill runaway jobs (default 360)
timeout-minutes: 5 (step level)
Cap a single step
retry via nick-fields/retry@v3
Retry flaky steps
jobs.<id>.strategy.max-parallel
Limit parallel matrix legs
if: always() on cleanup steps
Cleanup even after failure
Scheduled runs can be delayed/skipped
Cron is best-effort, not exact
Common recipes
12on: push: tags: ["v*"] + softprops/action-gh-release@v2
Release on version tag
on: push: paths: ["apps/api/**"]
Monorepo: build only what changed
dorny/paths-filter@v3
Per-job change detection
peaceiris/actions-gh-pages@v4
Deploy static site to Pages
docker/build-push-action@v6
Build and push Docker images
docker/login-action@v3 with ghcr.io
Log in to GitHub registry
aws-actions/configure-aws-credentials@v4 (OIDC)
Keyless AWS deploys
appleboy/ssh-action@v1
Run commands on a server
codecov/codecov-action@v4
Upload coverage reports
github/codeql-action
Code scanning / security
dependabot.yml + auto-merge workflow
Auto-update dependencies
schedule + stale action
Auto-close stale issues
Debugging
12Secret ACTIONS_STEP_DEBUG = true
Verbose step debug logs
Secret ACTIONS_RUNNER_DEBUG = true
Runner diagnostic logs
Re-run jobs > Enable debug logging
One-off debug re-run
act
Run workflows locally in Docker
act -j build
Run a single job locally
act -s GITHUB_TOKEN=$(gh auth token)
Pass secrets to act
echo "::debug::message"
Emit a debug log line
echo "::error file=app.js,line=1::Oops"
Annotate code with errors
echo "::group::Install" ... "::endgroup::"
Collapsible log sections
$GITHUB_STEP_SUMMARY
Write Markdown run summary
mxschmitt/action-tmate@v3
SSH into a live runner
cat "$GITHUB_EVENT_PATH"
Inspect the raw event JSON
gh CLI for Actions
13gh run list
Recent workflow runs
gh run list --workflow ci.yml
Runs for one workflow
gh run watch
Live-follow the latest run
gh run view 123456 --log
Full logs of a run
gh run view --log-failed
Only the failed steps' logs
gh run rerun 123456 --failed
Re-run failed jobs only
gh run cancel 123456
Cancel a run
gh run download 123456
Download run artifacts
gh workflow list
List workflows in the repo
gh workflow run ci.yml -f env=prod
Trigger workflow_dispatch
gh workflow disable ci.yml
Disable a workflow
gh secret set API_KEY
Set a repo secret
gh cache list / gh cache delete
Inspect and prune caches
没有条目匹配“:q”。
关于 GitHub Actions 速查表
这份 GitHub Actions 速查表将工作流 YAML 压缩到一个可搜索的页面上：工作流骨架和触发器、Job 和运行器、Step 和常用 Action、表达式和上下文、条件和 Matrix 构建、缓存和 Artifact、环境和权限、可复用工作流和复合 Action、并发和超时、常用配方、调试，以及 Actions 相关的 gh CLI 命令。
工作流文件基本上是靠记忆的语法——哪个触发器在 tag 上触发、如何引用 secret、在 fork 上跳过 step 的 if 表达式、基于 lockfile 的缓存 key 模式——因此每一行都展示了 YAML 片段和一行说明。
本速查表免费且在客户端运行：使用搜索框实时过滤行，通过固定目录在章节间跳转，点击即可复制任何片段，还可以打印页面作为桌边参考。
如何使用 GitHub Actions 速查表
- 浏览各章节，从“工作流骨架和触发器”和“Job 和运行器”到“gh CLI”。
- 搜索关键词如 matrix、secrets 或 cache 以实时过滤每一行。
- 跳转到“常用配方”获取现成的构建、测试或部署 Job 来改编使用。
- 点击 YAML 片段或其复制图标，复制到工作流文件中。
- 打印本速查表获取离线 GitHub Actions 参考。
常见问题
十二个章节：工作流骨架和触发器、Job 和运行器、Step 和常用 Action、表达式和上下文、条件和 Matrix、缓存和 Artifact、环境和权限、可复用和复合工作流、并发和超时、常用配方、调试，以及 gh CLI。
是的——push、pull_request、带 cron 的 schedule、带输入的 workflow_dispatch、release，以及缩小每个触发器范围的 path 和 branch 过滤器。
两者都有专门的章节：带 include、exclude 和 fail-fast 的 Matrix 策略，以及带基于 lockfile 的 key 和 restore-keys 的 actions/cache。
可以。点击任意行或其复制图标，片段即可复制到剪贴板并显示简短确认。
是的，完全免费——可搜索、可打印，在浏览器中渲染，无需注册。
热门搜索
github actions 速查表
github actions 工作流语法
github actions yaml 示例
github actions 矩阵构建
github actions 缓存
工作流触发器列表
github 可复用工作流
需要帮助？
使用此工具时遇到问题？请告诉我们的团队。