CI/CD / 知识点
GitHub Actions 工作流语法速查
工作流基础
使用顶层 name 为工作流设置显示名称,便于 Actions 列表、运行记录和排障时区分多个流水线;未设置时 GitHub 可根据文件名显示默认名称。
name:配置工作流名称
当仓库中存在多个工作流、需要在 Actions 页面快速区分构建、测试和部署流水线时,查看或设置顶层 name。它只负责工作流的显示名称,不决定触发条件或单次运行名称。
值与含义
| 写法 | 含义 | 建议动作 |
|---|---|---|
name: CI |
将工作流显示名称设为 CI |
为长期维护的工作流使用稳定、易检索的名称 |
未设置 name |
GitHub 使用工作流文件路径标识工作流 | 多个文件用途接近时建议显式设置 |
run-name |
设置单次 workflow run 的显示名称 | 不要把它与顶层 name 混用 |
name 位于工作流 YAML 顶层,与 on、jobs 同级。
快速确认
将下面内容保存为 .github/workflows/manual-check.yml 并提交到仓库默认分支:
name: Manual Check
on:
workflow_dispatch:
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Print workflow name
run: echo "workflow is running"预期结果:打开仓库的 Actions 页面后,可以看到名为 Manual Check 的工作流;手动运行后,verify 作业成功,步骤日志包含:
workflow is running判读与常见误用
如果 Actions 页面显示的工作流名称不符合预期,先确认 name 是否位于 YAML 顶层,而不是写进某个 job 或 step。若目标是让每次运行显示分支、部署环境或触发人,应使用 run-name,而不是动态修改 name。
适用范围
适用于存放在 .github/workflows 下的 GitHub Actions 工作流 YAML。GitHub 当前文档规定:省略 name 时,界面使用工作流文件相对仓库根目录的路径作为名称。GitHub Docs
使用顶层 on 定义工作流何时创建运行,可配置 push、pull_request、workflow_dispatch 等事件及其分支、路径过滤条件。
on:配置触发事件
需要确认工作流为什么运行、为什么没有运行,或限制它只响应特定分支和文件变化时,查看顶层 on。它定义哪些 GitHub 事件会创建 workflow run,以及事件需要满足哪些过滤条件。
常用触发方式
| 配置 | 出现条件 | 建议动作 |
|---|---|---|
push |
仓库发生符合条件的推送 | 用 branches、tags 或 paths 缩小范围 |
pull_request |
Pull Request 发生受支持的活动 | branches 用于匹配 PR 的目标分支 |
workflow_dispatch |
用户手动触发工作流 | 适合部署、维护或临时验证 |
| 多个事件并列 | 任一配置事件发生 | 分别为需要过滤的事件配置子项 |
当同一事件同时配置 branches 和 paths 时,两类过滤条件都需要满足才会触发。例如,推送既要进入指定分支,又要包含匹配路径的变更。
快速确认
下面的完整工作流支持三种触发方式:推送到 main 且修改 src/**,向 main 发起且修改 src/** 的 Pull Request,以及手动运行。
name: CI Trigger Check
on:
push:
branches:
- main
paths:
- "src/**"
- ".github/workflows/ci.yml"
pull_request:
branches:
- main
paths:
- "src/**"
workflow_dispatch:
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Show trigger
run: echo "trigger=${{ github.event_name }}"预期结果:符合条件的推送产生日志 trigger=push;符合条件的 Pull Request 产生 trigger=pull_request;从 Actions 页面手动运行时产生 trigger=workflow_dispatch。
trigger=<push|pull_request|workflow_dispatch>尖括号表示三种可能值之一,实际日志只会显示本次运行对应的事件名。
没有触发时怎么判读
先确认事件类型,再检查过滤条件。对于 push,branches 匹配被推送的分支;对于 pull_request,branches 匹配 PR 的目标分支。若同时设置分支和路径过滤,任一条件不满足都会跳过该事件对应的运行。
多个事件使用映射形式且其中某些事件带配置时,应给每个事件保留冒号,包括没有额外配置的 workflow_dispatch:。手动触发使用 workflow_dispatch 时,工作流文件需要存在于默认分支才能接收该事件。
适用范围
适用于 GitHub Actions 工作流的顶层 on 配置。事件支持的活动类型、过滤字段和行为可能因事件种类而异,应以目标事件的 GitHub Actions 文档为准。GitHub Docs
在 push 或 pull_request 下使用 branches 与相关过滤字段缩小触发范围,适合只让主干、发布分支或指定模式参与 CI/CD。
限制分支触发
当 CI/CD 只应响应主干、发布分支或特定分支模式时,给 push 或 pull_request 配置分支过滤。判读时先区分事件:push 匹配被推送的分支;pull_request 匹配 PR 的目标分支。
怎么判读
| 写法 | 含义 | 建议动作 |
|---|---|---|
branches |
只允许匹配的分支触发 | 用于白名单,支持 glob 模式 |
branches-ignore |
匹配的分支不触发 | 只需要排除时使用 |
!pattern |
在 branches 中排除已包含的模式 |
需要同时包含和排除时使用,顺序会影响结果 |
branches + paths |
两类过滤必须同时满足 | 适合限定“指定分支且指定文件变更” |
同一个事件里不能同时使用 branches 与 branches-ignore。若使用 ! 排除模式,必须至少有一个非负模式;后出现的模式可以覆盖前面的匹配结果。
快速配置
下面的完整工作流让 push 只响应 main 和正式发布分支,同时让指向 main 的 PR 运行检查。
name: branch-filter
on:
push:
branches:
- main
- 'releases/**'
- '!releases/**-alpha'
pull_request:
branches:
- main
jobs:
confirm:
runs-on: ubuntu-latest
steps:
- name: Confirm trigger
run: echo "branch-filter matched"预期结果:推送到 main 或 releases/1.2 会创建运行;推送到 releases/1.2-alpha 不会创建运行;PR 只有在目标分支为 main 时才会创建运行。已创建的运行中,Confirm trigger 步骤输出如下。
branch-filter matched常见误判
pull_request.branches 看的是目标分支,不是提交 PR 的源分支。若规则要求限制源分支,需要在作业或步骤条件中结合事件上下文另行判断,不能把 branches 当作源分支过滤器。
如果只为 push 配置 branches 而没有配置 tags,标签推送不会因为这些分支模式而触发该事件配置。分支名中若包含 glob 特殊字符并希望按字面匹配,需要按 GitHub Actions 的模式规则转义。
适用范围
适用于 GitHub Actions 工作流中的 push、pull_request 等支持分支过滤的事件。不同事件支持的过滤字段并不完全相同,配置前应以当前 GitHub Actions Workflow syntax 的对应事件说明为准。 GitHub Docs
使用 paths 或 paths-ignore 根据变更文件决定是否触发工作流,适合前后端分目录仓库或只在部署相关文件变化时运行。
限制文件路径触发
当仓库按目录拆分前后端、服务或部署文件时,用 paths 或 paths-ignore 根据本次变更文件决定是否创建工作流运行。核心判断不是“当前目录是什么”,而是 GitHub 为该事件计算出的变更文件列表是否命中过滤模式。
怎么判读
| 写法 | 含义 | 建议动作 |
|---|---|---|
paths |
至少有一个变更路径匹配时触发 | 用于只关注某目录或文件类型 |
paths-ignore |
所有变更路径都被忽略时才跳过 | 用于排除纯文档等变更 |
!pattern |
在 paths 中排除已包含的路径 |
需要同时包含和排除时使用,模式顺序有影响 |
branches + paths |
分支与路径过滤必须同时满足 | 适合部署或单体仓库中的精确触发 |
同一个事件里不能同时使用 paths 与 paths-ignore。如果既要包含又要排除,应在 paths 中先写正模式,再用 ! 写负模式;若后面再次出现正模式,还可以把路径重新包含进来。
快速配置
下面的完整工作流只在 frontend/** 有变更时运行,但纯 frontend/docs/** 变更不会触发 push;PR 则只要改动 frontend/** 就运行。
name: path-filter
on:
push:
paths:
- 'frontend/**'
- '!frontend/docs/**'
pull_request:
paths:
- 'frontend/**'
jobs:
confirm:
runs-on: ubuntu-latest
steps:
- name: Confirm trigger
run: echo "path-filter matched"预期结果:推送修改 frontend/src/app.js 会创建运行;如果一次推送只修改 frontend/docs/readme.md,不会创建 push 运行;PR 中只要变更列表包含 frontend/** 路径,就会满足这里的路径条件。已创建的运行中,步骤输出如下。
path-filter matched边界与排查
paths-ignore 的语义容易读反:只有当所有变更文件都匹配忽略模式时才跳过;只要有一个文件不在忽略范围内,工作流仍会运行。路径过滤不会用于标签推送。
GitHub 会先根据事件生成变更文件列表再做匹配:PR 使用三点比较,既有分支的 push 使用两点比较。差异计算也有平台限制,例如超大提交批次、比较超时和超大文件变更集合可能使过滤结果与直觉不同;遇到“明明改了文件却没触发”时,应先核对事件的 diff 和官方当前限制。
适用范围
适用于 GitHub Actions 中支持路径过滤的 push、pull_request 等事件。路径过滤的 diff 计算方式和平台限制可能调整,排查边界行为时以当前 Workflow syntax 文档为准。 GitHub Docs
使用 workflow_dispatch.inputs 为手动运行提供参数,可声明 string、choice、boolean、number 和 environment 等输入类型。
配置 workflow_dispatch.inputs
需要让用户从 Actions 页面手动运行工作流并填写参数时查这一项。把输入声明在 on.workflow_dispatch.inputs 后,可从 inputs.<name> 读取;其中布尔值在 inputs 上下文中保持布尔类型,适合直接用于条件判断。
值与含义
| 配置 | 含义 | 判读与动作 |
|---|---|---|
string |
任意文本输入 | 用 inputs.<name> 读取字符串 |
choice |
从 options 中单选 |
结果按字符串使用 |
boolean |
真/假开关 | 优先读取 inputs,避免把字符串 "false" 当成真值 |
number |
数值输入 | 需要数值参数时使用 |
environment |
选择仓库 Environment | 选中名称不会自动绑定 job;需要时再写到 jobs.<id>.environment |
required |
是否要求填写 | 必填项设为 true |
default |
未修改时采用的默认值 | 默认值应与声明的 type 匹配 |
完整配置
下面的工作流可保存为 .github/workflows/manual-deploy.yml。手动运行时选择 staging、保持 dry_run=true、填写 replicas=2。
name: Manual deploy
on:
workflow_dispatch:
inputs:
target:
description: 'Target environment'
required: true
type: choice
options:
- staging
- production
dry_run:
description: 'Only validate'
required: true
default: true
type: boolean
replicas:
description: 'Replica count'
required: true
default: 2
type: number
jobs:
inspect:
runs-on: ubuntu-latest
steps:
- name: Show inputs
env:
TARGET: ${{ inputs.target }}
DRY_RUN: ${{ inputs.dry_run }}
REPLICAS: ${{ inputs.replicas }}
run: |
echo "target=$TARGET"
echo "dry_run=$DRY_RUN"
echo "replicas=$REPLICAS"预期结果:在仓库 Actions 页选择该工作流后会出现 Run workflow 输入控件;按上述值运行时,job 日志包含:
target=staging
dry_run=true
replicas=2出现条件与常见误用
workflow_dispatch 只在工作流文件位于默认分支时接收手动触发事件。若看不到 Run workflow,先确认文件已提交到 .github/workflows/ 且默认分支上的版本包含 workflow_dispatch。
environment 输入只负责让用户选择 Environment 名称,不等于自动为 job 配置 environment。需要环境保护规则、环境 secrets 或部署记录时,应在对应 job 上显式引用该输入。
适用范围
GitHub.com 当前工作流语法支持 boolean、choice、number、environment、string 五种输入类型;顶层输入数量与负载大小存在平台限制。GitHub Enterprise Server 的限制可能随版本不同,应以目标服务器对应版本的工作流语法文档为准。
在 schedule 中使用 POSIX cron 定义周期运行任务,适合夜间检查、定期清理或巡检;cron 按 GitHub Actions 规则解释时间,不按本地时区直接填写。
配置 schedule
需要让工作流按周期自动运行时查这一项。on.schedule 使用五段 POSIX cron;未声明时区时默认按 UTC 解释,并在默认分支最新提交上运行。
常用值速查
| cron | 含义 | 建议动作 |
|---|---|---|
17 2 * * * |
每天 02:17 UTC | 适合每日巡检 |
17 2 * * 1-5 |
周一到周五 02:17 UTC | 适合工作日任务 |
17 */6 * * * |
每 6 小时一次,在第 17 分钟触发 | 适合周期同步 |
*/5 * * * * |
每 5 分钟一次 | 已达到 GitHub Actions 当前支持的最短调度间隔 |
五个字段依次是分钟、小时、月中日期、月份、星期。常用操作符为 *、,、-、/;GitHub Actions 不支持 @daily、@hourly 这类非标准简写。
完整配置
下面的工作流会在周一到周五的 02:17 UTC 计划运行,并把 runner 看到的 UTC 时间写入日志。
name: Scheduled check
on:
schedule:
- cron: '17 2 * * 1-5'
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Show UTC time
run: date -u '+%Y-%m-%dT%H:%M:%SZ'预期结果:满足 cron 的工作日会创建一次计划运行,日志输出一个 UTC 时间戳;实际时间值会变化。
<TIME>判读与处理
计划任务没有出现时,先确认工作流文件存在于默认分支;schedule 不会按功能分支上的独立版本触发。若运行时间偶尔晚于 cron,不要把 cron 当作实时调度器:高负载时计划事件可能延迟,整点附近尤其容易拥塞,因此示例故意使用第 17 分钟。
GitHub.com 当前语法还允许在单个 schedule 项中使用 IANA 时区字符串配置 timezone。如果使用这一能力,应按目标时区直接写 cron,并考虑夏令时切换;GitHub Enterprise Server 是否支持该字段应按目标版本文档核对。
适用范围
以上规则针对 GitHub Actions 的 schedule 事件。它适合定期检查、清理和巡检,不适合要求秒级、严格准点或绝不漏执行的调度任务。
权限与安全
顶层 permissions 用于统一控制 GITHUB_TOKEN 的访问范围,可将不需要的权限设为 none,并按最小权限原则减少工作流操作面。
定义工作流权限
查找顶层 permissions 时,可以确认工作流默认授予 GITHUB_TOKEN 的能力范围,并通过显式权限声明限制自动化任务可执行的 GitHub 操作。
值与含义
| 配置值 | 含义 | 建议动作 |
|---|---|---|
read |
允许读取对应资源 | 仅需要查询仓库信息时使用 |
write |
允许修改对应资源 | 发布、创建评论、更新内容时按需开启 |
none |
禁止该权限 | 不需要访问时优先关闭 |
contents: read |
读取仓库内容 | 常用于构建和测试任务 |
出现条件
顶层 permissions 位于工作流 YAML 根级别,用于为该工作流中的 Job 设置默认令牌权限。Job 未单独覆盖时,会继承这里的权限配置。
name: build
on:
push:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: echo "run tests"预期结果
工作流启动时,GITHUB_TOKEN 仅拥有读取仓库内容权限。判读线索
检查工作流失败信息时,如果操作 GitHub API 返回权限不足,优先查看对应资源的 permissions 是否缺少 read 或 write。
建议动作
先将权限设置为最小可用范围,再针对失败步骤增加单项权限。不要直接使用宽泛授权覆盖所有资源,以减少令牌泄露后的影响范围。
具体可用权限名称和行为以 GitHub Actions 官方文档当前版本为准。
在具体 Job 内再次声明 permissions,让不同作业拥有不同的令牌能力;适合把构建、发布、评论等高低风险任务隔离授权。
覆盖单个 Job 权限
查找 Job 级 permissions 时,可以判断某个具体作业是否需要覆盖工作流默认权限,并将高风险任务与普通任务分开授权。
值与含义
| 配置位置 | 含义 | 建议动作 |
|---|---|---|
工作流顶层 permissions |
所有 Job 的默认权限 | 设置基础最小权限 |
Job 内 permissions |
当前 Job 专用权限 | 为特殊任务增加或减少能力 |
none |
禁止该资源访问 | 不需要时关闭 |
write |
允许修改资源 | 仅发布、写入等步骤开启 |
出现条件
当同一个工作流包含多个职责不同的 Job 时,可以在单个 Job 内重新声明权限。例如测试 Job 只读仓库,而发布 Job 需要写入发布资源。
name: ci
on:
push:
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- run: echo "test"
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- run: echo "release"预期结果
test Job 继承 contents: read。
release Job 使用自己的 contents: write 配置。判读线索
如果只有某个 Job 执行 GitHub 操作失败,检查该 Job 是否覆盖了顶层权限,以及覆盖后是否遗漏原本需要的权限。
建议动作
优先在顶层关闭不必要权限,再为确有需要的 Job 单独开放权限。多个 Job 使用不同令牌能力时,应保持权限声明靠近实际使用位置,方便审查。
权限名称和支持范围可能随 GitHub Actions 功能变化,实际配置应以当前 GitHub Actions 文档为准。
通过 secrets 上下文读取仓库或环境中的敏感凭据,避免把密码、令牌和私钥直接写入工作流文件;权限边界仍需结合使用场景检查。
引用 Secret
需要在工作流里使用令牌、密码或私钥时,查 secrets 上下文;目标是把敏感值注入 Action 输入或环境变量,同时确认该 Secret 在当前触发方式和作用域下确实可用。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
${{ secrets.NAME }} |
读取当前 Job 可访问的 Secret | 将 NAME 替换为已配置的 Secret 名称 |
| 表达式结果为空字符串 | Secret 未设置或当前上下文不可用 | 检查名称、仓库/组织/环境作用域和触发来源 |
| Job 绑定了 Environment | 可读取该 Environment 的 Secret,但要先满足适用的保护规则 | 确认 environment 名称与环境配置一致 |
| 工作流由 fork 触发 | 除 GITHUB_TOKEN 外,普通 Secret 不会传给 Runner |
不要让不受信任代码依赖敏感凭据运行 |
| Dependabot 事件触发 | Secret 不提供给该工作流 | 将需要凭据的操作与 Dependabot 触发路径分离 |
| 调用 reusable workflow | Secret 不会自动跨工作流传递 | 在调用 Job 中显式使用 secrets,或在适用范围内使用 secrets: inherit |
快速确认
前置条件是在仓库或目标 Environment 中创建名为 API_TOKEN 的 Secret。下面的工作流只判断是否拿到值,不打印 Secret 本身。
name: secret-check
on:
workflow_dispatch:
jobs:
check:
runs-on: ubuntu-latest
env:
API_TOKEN: ${{ secrets.API_TOKEN }}
steps:
- name: Check secret without printing it
shell: bash
run: |
if [[ -z "$API_TOKEN" ]]; then
echo "API_TOKEN is not configured"
exit 1
fi
echo "API_TOKEN is configured"预期结果
API_TOKEN is configured若 Secret 不存在或在当前运行中不可访问,日志显示 API_TOKEN is not configured,该步骤以非零状态结束。
安全边界
不要把 Secret 直接写进仓库文件,也不要为了调试把它输出到日志。GitHub 会对已知 Secret 做日志脱敏,但运行时生成的其他敏感值应先使用 ::add-mask::VALUE 标记;命令行参数还可能被进程列表或审计信息捕获,能用环境变量或标准输入时优先使用它们。
Secret 不能直接用于 if: 条件。需要条件判断时,可先映射到 Job 级环境变量,再让步骤基于环境变量判断。对支持 OIDC 的云平台,可优先考虑短期联合身份令牌,减少长期云凭据作为 Secret 保存。
适用范围
以上行为适用于 GitHub Actions 当前官方工作流语法。普通 Secret 在 fork 触发、Dependabot 事件、reusable workflow 传递和 Environment 保护规则下有额外限制;组织级 Secret 还受仓库访问策略与 GitHub 方案限制。
在 Job 上使用 environment 绑定部署环境,可关联环境变量、Secret 与保护规则;部署保护规则通过后,Job 才会被发送到 Runner。
配置环境保护
需要让部署 Job 在进入 Runner 前经过审批、等待时间、分支限制或其他保护规则时,查 jobs.<job_id>.environment。绑定 Environment 后,可以把部署门禁与 Environment Secret、变量和部署记录放在同一边界内。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
environment: production |
Job 引用名为 production 的 Environment |
确认仓库中该 Environment 已按预期配置 |
Job 状态为 Waiting |
Required reviewers 等保护规则尚未通过 | 在工作流运行页完成审批或等待规则结束 |
| 保护规则未通过 | Job 不会被发送到 Runner | 检查审批、等待时间、分支或标签限制及自定义保护规则 |
| Environment Secret 读取不到 | 保护规则可能尚未通过,或 Secret 不属于该 Environment | 先确认门禁状态,再检查 Secret 名称与作用域 |
environment 使用对象形式 |
可同时提供 name,并按需设置部署 URL 等字段 |
只配置实际需要的字段 |

最小配置
先在仓库 Settings → Environments 中创建 production,并按需要配置 required reviewers、wait timer、允许的部署分支或标签等保护规则。然后让部署 Job 引用这个 Environment。
name: environment-gate-check
on:
workflow_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
steps:
- name: Verify environment gate
run: echo "environment gate passed"预期结果
environment gate passed如果 production 配置了 required reviewers,运行会先等待审批;审批及其他适用保护规则全部通过后,Job 才开始执行并出现上述日志。若审批被拒绝,工作流不会执行该 Job 的步骤。
检查与恢复
确认门禁是否生效时,不要只看 YAML。应同时检查工作流运行页的 Job 状态和仓库 Environment 配置;如果 Job 直接运行,通常表示该 Environment 没有配置会阻塞本次运行的保护规则,或当前规则对这次部署来源不适用。
如果部署被错误阻塞,先核对 Job 引用的 Environment 名称、允许的分支或标签、审批人和等待规则。不要通过删除 Environment 或把 Secret 移到仓库级来绕过问题;应修正保护规则或部署来源,使权限边界保持一致。
适用范围
jobs.<job_id>.environment 支持仅写环境名称,也支持对象形式。GitHub Actions 规定,引用 Environment 的 Job 必须先通过适用的 deployment protection rules,之后才会发送到 Runner;Environment Secret 也要在规则通过后才可访问。具体保护规则的可用性会随仓库可见性、GitHub 方案和当前产品能力而不同,应以目标仓库的 Environment 设置为准。
作业与执行控制
顶层 env 为工作流中的步骤提供共享环境变量,适合定义不会随单个 Job 改变的公共配置;同名变量可在更具体层级覆盖。
定义全局环境变量
当多个 Job 或步骤都要读取同一组固定配置时,查顶层 env。它把键值注入工作流中的 Runner 步骤环境;若 Job 或步骤定义同名变量,更具体的层级覆盖工作流级值。
值与作用域
| 写法 | 含义 | 建议动作 |
|---|---|---|
顶层 env |
工作流级共享变量 | 放不会随单个 Job 改变的公共配置 |
jobs.<job_id>.env |
只对该 Job 生效 | 用于 Job 专属配置或覆盖全局值 |
jobs.<job_id>.steps[*].env |
只对当前步骤生效 | 用于最小作用域的临时覆盖 |
${{ env.NAME }} |
在 Actions 表达式中读取 | 用于 if、with 等表达式位置 |
| Shell 环境变量 | 在 Runner 命令中读取 | Bash 使用 $NAME,PowerShell 使用 $env:NAME |
同名变量按“步骤 > Job > 工作流”的具体程度生效。顶层 env 的各项不要互相依赖展开;需要派生值时,在表达式或步骤中组合。
快速确认
下面的完整工作流可保存为 .github/workflows/env-check.yml,然后从 Actions 页面手动运行:
name: env-check
on:
workflow_dispatch:
env:
APP_ENV: staging
LOG_LEVEL: info
jobs:
verify:
runs-on: ubuntu-latest
env:
LOG_LEVEL: debug
steps:
- name: Read workflow and job env
run: |
echo "APP_ENV=$APP_ENV"
echo "LOG_LEVEL=$LOG_LEVEL"
- name: Override at step level
env:
APP_ENV: test
run: |
echo "APP_ENV=$APP_ENV"预期输出:
APP_ENV=staging
LOG_LEVEL=debug
APP_ENV=test实际日志还会包含 GitHub Actions 的步骤包装信息,但这三行变量值应与上面一致。
判读与建议
如果多个步骤需要相同常量,优先放到顶层 env;只在单个 Job 或步骤需要差异时再局部覆盖。不要把密码、令牌或私钥直接写进 env,敏感值应从 secrets 上下文注入。需要跨 Job 传递运行时计算结果时,使用 Job 输出,而不是把顶层 env 当作可变共享状态。
适用范围:GitHub Actions 工作流 YAML。变量是否可用于某个字段,还取决于该字段是否支持表达式或是否在 Runner 上执行。
顶层 jobs 下的每个键代表一个独立 Job,可分别选择 Runner、设置依赖和权限,并通过 needs、输出或策略与其他 Job 建立关系。
定义 Job
当一个工作流需要把构建、测试、部署等任务拆成独立执行单元时,查顶层 jobs。jobs 下每个键是 Job ID;Job 可单独指定 Runner、权限、依赖、输出和执行策略。
关键字段
| 字段 | 含义 | 建议动作 |
|---|---|---|
jobs.<job_id> |
定义一个 Job,键名就是 Job ID | 使用稳定、可读且不含空格的标识 |
runs-on |
选择运行该 Job 的 Runner | 按操作系统、架构或自托管标签选择 |
steps |
定义 Job 内按顺序执行的步骤 | 把同一 Runner 上连续执行的任务放在一起 |
needs |
声明必须先完成的 Job | 用于建立 Job 依赖和读取上游输出 |
permissions |
限定该 Job 的 GITHUB_TOKEN 权限 |
按最小权限原则显式配置 |
outputs |
暴露 Job 结果给下游 Job | 通过 needs.<job_id>.outputs.<name> 读取 |
strategy |
定义矩阵等多组合执行策略 | 需要多版本或多平台并行时使用 |
没有 needs 关系的 Job 通常可以并行调度;声明 needs 后,下游 Job 会等待依赖 Job 成功完成。依赖 Job 失败或被跳过时,下游 Job 默认也不会继续执行,除非显式调整条件。
快速确认
下面的完整工作流定义 build 和 test 两个 Job,并让 test 读取 build 的输出:
name: job-check
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
outputs:
artifact_name: ${{ steps.meta.outputs.name }}
steps:
- id: meta
run: echo "name=demo-app" >> "$GITHUB_OUTPUT"
test:
needs: build
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Read upstream output
run: echo "artifact=${{ needs.build.outputs.artifact_name }}"预期输出:
artifact=demo-app在工作流运行图中,test 应显示为依赖 build,并且只会在 build 满足依赖条件后开始。
判读与建议
需要独立 Runner、不同权限边界、并行执行或显式依赖时拆成多个 Job;必须共享同一工作目录或进程状态的连续动作则更适合留在同一个 Job 的多个步骤中。跨 Job 不要假定文件系统自动共享,文件需要通过 artifact、缓存或外部存储显式传递。
适用范围:GitHub Actions 工作流 YAML。runs-on 可用标签、Runner 规模和某些高级选项取决于仓库、组织和 GitHub 计划配置。
使用 runs-on 指定 Job 的执行环境,可选择 GitHub 托管 Runner 或匹配标签的自托管 Runner;整个 Job 的步骤都在选定 Runner 上执行。
runs-on 选择 Runner
需要决定 Job 在什么操作系统、Runner 标签或 Runner 组上执行时查 runs-on。确认写法后,可以把 Job 路由到 GitHub 托管 Runner,或满足指定标签条件的自托管 Runner。
常用写法
| 写法 | 含义 | 建议动作 |
|---|---|---|
runs-on: ubuntu-latest |
使用对应标签的 GitHub 托管 Runner | 通用 Linux CI 可直接使用;要求环境稳定时考虑固定具体系统标签 |
runs-on: [self-hosted, linux, x64] |
使用自托管 Runner,且必须同时匹配列出的标签 | 先确认目标 Runner 已注册并具有全部标签 |
group 配合 labels |
同时限制 Runner 组和标签 | 适合组织内有多个 Runner 池时缩小调度范围 |
数组形式不是“任选一个标签”,而是要求同一个 Runner 满足数组中的全部条件。找不到符合条件的自托管 Runner 时,Job 不会换到 GitHub 托管 Runner,而会等待可用的匹配 Runner。
快速确认
下面的工作流可直接放入仓库的 .github/workflows/runner-check.yml,再从 Actions 手动触发。
name: runner-check
on:
workflow_dispatch:
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Show runner properties
run: |
echo runner.os=${{ runner.os }}
echo runner.arch=${{ runner.arch }}预期结果
runner.os=Linux
runner.arch=<ARCH><ARCH> 是实际 Runner 架构,例如常见的 X64;应以本次运行日志中的值为准。Job 详情同时会显示实际获得的 Runner,可据此确认 runs-on 是否命中了预期环境。
排查线索
| 现象 | 优先检查 | 建议动作 |
|---|---|---|
| Job 长时间排队 | 自托管 Runner 是否在线、标签是否全部匹配 | 对照 Runner 已配置标签修正 runs-on |
| 命中了错误的 Runner | 标签过宽或 Runner 组范围不正确 | 增加更具体的标签,或同时限定 group 与 labels |
| 环境升级后行为变化 | 使用了 *-latest 标签 |
对可重复构建要求较高的任务改用可用的具体系统版本标签 |
适用范围
runs-on 是 Job 级配置,Job 中的步骤默认都在该 Job 获得的 Runner 环境中执行。可用的 GitHub 托管标签、较大型 Runner 和自托管 Runner 组取决于当前 GitHub 产品与组织配置;GitHub Enterprise Server 应以对应服务器版本的 Actions 文档和 Runner 配置为准。
使用 needs 表示 Job 之间的执行依赖,默认要求被依赖 Job 成功后再运行;适合把构建、测试、部署组织成明确的阶段链路。
needs 设置 Job 依赖
需要让一个 Job 等待其他 Job 完成并成功后再开始时查 needs。它可以把构建、测试、部署等独立 Job 串成明确的依赖链,也可以让一个 Job 同时等待多个前置 Job。
值与执行关系
| 写法 | 含义 | 默认行为 |
|---|---|---|
needs: build |
当前 Job 直接依赖一个 Job | build 成功后才运行 |
needs: [build, test] |
当前 Job 直接依赖多个 Job | 列出的 Job 都成功后才运行 |
不写 needs |
与其他 Job 没有显式依赖 | Runner 可用时可并行调度 |
如果被依赖的 Job 失败或被跳过,依赖它的 Job 默认也会被跳过;这种影响会沿后续依赖链继续传播。确实需要在失败后仍执行清理、汇总等 Job 时,应显式添加合适的 Job 级 if 条件,而不是假设 needs 会自动继续。
快速确认
下面的工作流形成 build → test → deploy 三阶段链路,可直接放入 .github/workflows/job-needs.yml 后手动触发。
name: job-dependency-check
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo build-ok
test:
needs: build
runs-on: ubuntu-latest
steps:
- run: echo test-ok
deploy:
needs: test
runs-on: ubuntu-latest
steps:
- run: echo deploy-ok预期结果
build: build-ok
test: test-ok
deploy: deploy-ok这些内容分别出现在三个 Job 的日志中,而不是同一个连续终端输出。Actions 的 Job 关系应表现为先完成 build,随后运行 test,最后才运行 deploy;如果 build 失败,后两者默认不会执行。
判读线索
| 现象 | 含义 | 建议动作 |
|---|---|---|
| 下游 Job 显示跳过 | 某个依赖失败、跳过,或当前 Job 的条件不成立 | 先检查直接依赖的结果,再检查 Job 级 if |
| 两个 Job 同时开始 | 两者之间没有形成 needs 依赖 |
在必须等待的一方声明前置 Job ID |
| 需要读取前置 Job 输出 | 当前 Job 必须直接依赖产生该输出的 Job | 声明 needs,再通过 needs.<job_id>.outputs 读取 |
needs 上下文只包含当前 Job 的直接依赖,不会因为依赖链存在就自动包含更上游的间接依赖。需要访问某个上游 Job 的结果或输出时,应明确确认它是否属于当前 Job 的直接 needs。
适用范围
needs 使用的是 jobs 下定义的 Job ID,而不是界面显示名称。上述默认成功依赖、失败或跳过后的传播行为适用于 GitHub Actions 工作流语法;若结合 Job 级条件表达式改变执行策略,应同时检查 if 与 needs.<job_id>.result,GitHub Enterprise Server 的可用表达式和行为以对应版本文档为准。
使用 if 根据上下文和表达式决定 Job 或 Step 是否执行,常用于按分支、事件、输出或前置结果控制发布、清理和失败处理路径。
条件执行 Job 或 Step
需要让某个 Job 或 Step 只在指定分支、事件、前置结果或输出满足条件时运行,就查 if。条件为真时执行,为假时该 Job 或 Step 被跳过。
怎么判读
| 写法或线索 | 含义 | 建议动作 |
|---|---|---|
if: github.ref == 'refs/heads/main' |
仅 main 分支满足条件 |
用完整 refs/heads/... 值比较 |
if: github.event_name == 'pull_request' |
仅 Pull Request 事件执行 | 与 on 的触发范围配合使用 |
if: needs.build.result == 'success' |
根据前置 Job 结果分支 | Job 必须先通过 needs 建立依赖 |
if: failure() |
前序失败时执行 | 常用于收集日志或失败通知 |
if: always() |
即使前序失败或取消也尝试执行 | 只用于确实需要无条件收尾的步骤 |
未显式写状态检查函数时,GitHub Actions 会对多数 if 条件隐式应用成功状态检查,因此失败后的清理或通知通常要显式使用 failure()、cancelled() 或 always()。
快速确认
下面的工作流在推送到 main 时执行部署 Step;其他分支会运行 Job,但跳过该 Step。
name: if-check
on:
push:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- name: Show branch
run: echo "ref=${{ github.ref }}"
- name: Deploy on main
if: github.ref == 'refs/heads/main'
run: echo "deploy"预期结果:推送到 main 时日志包含 deploy;推送到其他分支时 Deploy on main 显示为 skipped。可在工作流运行详情中查看该 Step 的状态。
使用边界
if 可用于 Job 和 Step,但两者可访问的上下文并不完全相同;引用 needs、matrix、steps 等上下文前,应确认它在当前位置可用。表达式通常可直接写在 if: 后;若表达式以 ! 开头,为避免 YAML 把它解释为标签,应使用 ${{ ... }} 或合适的引号包裹。
if 只决定是否执行,不会改变触发器 on 本身。若整个工作流根本不应被触发,应优先收紧 on;若工作流需要启动后再按运行时信息分支,再使用 if。
将 continue-on-error 设为 true 可让指定 Step 或 Job 在失败后继续工作流,其余状态判断仍需单独设计,适合实验性检查或非阻断任务。
允许失败继续运行
某个检查允许失败、但不应立即阻断后续 Step 或整个工作流时,就查 continue-on-error。它适合实验性检查、兼容性测试或非关键诊断,不应拿来掩盖必须成功的构建与发布步骤。
怎么判读
| 配置位置 | 含义 | 建议动作 |
|---|---|---|
Step 上 continue-on-error: true |
该 Step 命令失败后,Job 仍可继续执行后续 Step | 后续需要识别真实失败时,给 Step 设置 id 并检查 steps.<id>.outcome |
Job 上 continue-on-error: true |
该 Job 失败时允许工作流继续,不让它单独决定整个工作流失败 | 对依赖该 Job 的逻辑显式设计条件,不要只凭最终工作流状态推断内部结果 |
continue-on-error: false 或省略 |
保持默认阻断行为 | 用于构建、测试门禁、部署等必须成功的任务 |
对 Step 而言,steps.<id>.outcome 表示应用 continue-on-error 之前的原始结果,steps.<id>.conclusion 表示应用之后的结论。需要记录“实际失败但已放行”时,应读取 outcome。
快速确认
下面的第一个 Step 会以退出码 1 失败,但 Job 继续执行,并在下一步读取原始结果。
name: continue-check
on:
workflow_dispatch:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- name: Optional check
id: optional_check
continue-on-error: true
run: exit 1
- name: Read result
run: |
echo "outcome=${{ steps.optional_check.outcome }}"
echo "conclusion=${{ steps.optional_check.conclusion }}"预期输出:
outcome=failure
conclusion=success这说明失败被放行,但原始失败仍可被后续逻辑识别。
使用边界
continue-on-error 只改变失败后的控制行为,不等于“这一步成功了”,也不会自动替你发送告警、重试或回滚。若失败仍需要处理,应结合 if、Step 输出、日志或通知步骤显式编排。
对矩阵 Job,可以用表达式决定哪些组合允许失败,例如将实验版本标记为非阻断;具体表达式可用的上下文取决于配置位置。生产发布、数据库迁移、安全扫描门禁等关键步骤通常不应无条件设置为 true。
使用 timeout-minutes 为 Job 或 Step 设置最大执行时间,超时后 GitHub Actions 会停止执行;适合防止测试、部署或等待脚本无限挂起。
限制执行时间
当某个 Job 或 Step 可能因测试、部署、网络等待或脚本阻塞而长时间不返回时,查 timeout-minutes。设置后,GitHub Actions 会在达到上限时终止对应的执行单元,避免工作流无限占用 Runner。
值与含义
| 位置 | 值与默认 | 含义 | 建议动作 |
|---|---|---|---|
jobs.<job_id>.timeout-minutes |
Job 默认 360 分钟 | 限制整个 Job 的最长运行时间 | 给可能挂起的测试或部署设置业务可接受的上限 |
jobs.<job_id>.steps[*].timeout-minutes |
正整数分钟,最大 360 | 只限制当前 Step;到期后终止该 Step 的进程 | 对外部命令、轮询或长时间等待单独设更短上限 |
Job 的实际运行时间还受所用 Runner 的执行时限约束;如果 Runner 的限制更短,会先按 Runner 限制结束。timeout-minutes 不是重试机制,需要重试时应另行设计重试策略。
快速确认
下面的工作流把 Job 上限设为 2 分钟,同时把第一个 Step 上限设为 1 分钟。保存为 .github/workflows/timeout-demo.yml 后手动触发。
name: timeout-demo
on:
workflow_dispatch:
jobs:
guarded:
runs-on: ubuntu-latest
timeout-minutes: 2
steps:
- name: Slow step
timeout-minutes: 1
run: sleep 90
- name: Never reached
run: echo "done"预期结果:
Slow step 在约 1 分钟达到超时上限后被终止。
guarded Job 因该 Step 失败而结束,不会等到 2 分钟的 Job 上限。
Never reached 默认不会执行。实际终止时刻可能因 Runner 调度与进程清理略有偏差,判读时以 Actions 页面中该 Step 的超时失败记录为准。
判读与适用范围
如果整组步骤必须共同受一个总时限约束,设置 Job 级 timeout-minutes;如果只有某个命令存在挂起风险,再给该 Step 设置更短上限。Step 级限制不会延长 Job 级限制。
GitHub 当前工作流语法明确规定 Step 级 timeout-minutes 为正整数分钟,GitHub-hosted 与 self-hosted Runner 的最大值均为 360。GitHub Enterprise Server 的可用行为应以对应版本文档为准。
在单个 Job 中设置 env,让该 Job 的所有步骤共享变量;同名变量会覆盖工作流级变量,但不会改变其他 Job 的环境。
配置 Job 环境变量
当一个 Job 的多个 Step 需要共享同一组非敏感配置,但其他 Job 不应受到影响时,查 jobs.<job_id>.env。这里定义的变量会进入该 Job 的各个 Step,并按作用域规则覆盖同名的工作流级变量。
作用域与覆盖顺序
| 定义位置 | 可见范围 | 同名时的优先级 | 建议动作 |
|---|---|---|---|
顶层 env |
工作流内各 Job 的 Step | 最低 | 放跨 Job 通用配置 |
jobs.<job_id>.env |
当前 Job 的所有 Step | 覆盖工作流级 env |
放 Job 专属配置 |
jobs.<job_id>.steps[*].env |
当前 Step | 最高 | 仅在单个 Step 临时改值 |
同名变量遵循“作用域越具体,优先级越高”。Job 级 env 不会修改其他 Job 的环境;Step 级覆盖也只在该 Step 执行期间生效。
快速确认
下面的工作流先定义工作流级 DEPLOY_ENV,再在 Job 级覆盖为 staging,最后在第二个 Step 中临时覆盖为 canary。
name: job-env-demo
on:
workflow_dispatch:
env:
DEPLOY_ENV: workflow
jobs:
show-env:
runs-on: ubuntu-latest
env:
DEPLOY_ENV: staging
API_BASE_URL: https://api.example.test
steps:
- name: Read job env
run: |
echo "DEPLOY_ENV=$DEPLOY_ENV"
echo "API_BASE_URL=$API_BASE_URL"
- name: Override in this step
env:
DEPLOY_ENV: canary
run: echo "DEPLOY_ENV=$DEPLOY_ENV"预期输出:
DEPLOY_ENV=staging
API_BASE_URL=https://api.example.test
DEPLOY_ENV=canary示例使用 ubuntu-latest 的 Bash 变量语法;Windows Runner 默认 PowerShell 时应使用 $env:NAME 读取环境变量。
判读与边界
env 适合保存普通配置,不应把密码、令牌等敏感值直接写进工作流文件;这类值应来自 secrets 上下文。另一个常见误区是在某个 run Step 中执行普通 export 后期待后续 Step 继承:各 Step 运行在独立进程中,普通进程环境修改不会自动跨 Step 保留;需要动态传递时应使用 GitHub 提供的环境文件机制。
适用范围为 GitHub Actions 工作流中的顶层、Job 级和 Step 级 env。GitHub Enterprise Server 的具体可用性与行为应以对应版本文档为准。
使用 defaults.run 为工作流或 Job 统一指定 shell 与 working-directory 默认值,减少重复配置;具体 Step 仍可声明更具体设置。
设置默认 Shell
多个 run Step 需要使用同一种 Shell 或执行目录时,查 defaults.run;把默认值放在工作流或 Job 层即可减少重复声明,Step 上的具体配置仍可覆盖它。
怎么判读
| 写法 | 作用范围 | 建议动作 |
|---|---|---|
defaults.run |
整个工作流中的 run Step |
多个 Job 共用同一默认值时使用 |
jobs.<job_id>.defaults.run |
指定 Job 的 run Step |
只有单个 Job 需要不同默认值时使用 |
Step 的 shell 或 working-directory |
当前 Step | 需要例外时在 Step 上覆盖 |
defaults.run 只影响执行脚本的 run Step,不会给 uses Action 注入 Shell。工作流级和 Job 级同时存在时,应以更具体的 Job 配置为准。
快速确认
下面的工作流把 Bash 设为默认 Shell,并在第二个 Step 显式改用 sh:
name: defaults-run-demo
on:
workflow_dispatch:
defaults:
run:
shell: bash
jobs:
demo:
runs-on: ubuntu-latest
steps:
- name: Use default shell
run: echo default-shell
- name: Override shell
shell: sh
run: echo step-shell预期结果:手动运行后,两个 Step 均成功,日志分别包含:
default-shell
step-shell使用边界
defaults.run 可同时设置 shell 和 working-directory,适合稳定、重复的执行约定。若不同操作系统需要不同 Shell,通常应在对应 Job 或 Step 分别配置,避免把平台差异隐藏在全局默认值中。
步骤与 Action
使用 working-directory 指定 run 命令执行时所在目录,适合单仓库多项目结构;路径应相对于 Runner 工作区或使用可访问的绝对路径。
声明执行目录
仓库包含多个子项目、命令必须从特定目录启动时,查 working-directory;它会让对应 run Step 先切换到目标目录,再执行脚本。
怎么判读
| 位置 | 含义 | 建议动作 |
|---|---|---|
Step 的 working-directory |
只改变当前 run Step 的目录 |
单个命令需要切目录时使用 |
jobs.<job_id>.defaults.run.working-directory |
给该 Job 的 run Step 设置默认目录 |
一个 Job 始终操作同一子项目时使用 |
defaults.run.working-directory |
给工作流中的 run Step 设置默认目录 |
多个 Job 使用同一仓库布局时使用 |
相对路径以 Runner 为当前作业准备的工作区为基础。Step 上声明的值比 Job 或工作流默认值更具体,因此适合处理少量例外。
快速确认
下面先创建 demo 子目录,再让下一步从该目录执行 pwd:
name: working-directory-demo
on:
workflow_dispatch:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- name: Prepare directory
run: mkdir -p demo
- name: Run inside directory
working-directory: demo
run: pwd预期结果:第二个 Step 成功,并输出以 /demo 结尾的绝对路径,例如:
<GITHUB_WORKSPACE>/demo<GITHUB_WORKSPACE> 的实际绝对路径由 Runner 和仓库名称决定,日志中的具体前缀可能不同。
失败时先看什么
如果 Step 在脚本执行前就失败,先检查目标目录是否已经存在,以及路径大小写是否与 Runner 文件系统一致。对于需要检出仓库后才出现的目录,应确保 actions/checkout 或创建目录的 Step 已经先执行。