CI/CD / 知识点
GitHub Actions 工作流语法速查
集成运行环境
在 Job 的 services 下定义数据库、Redis 等辅助容器,让测试步骤在同一 Runner 环境中访问依赖服务;适合集成测试和本地化 CI 环境。
配置服务容器
当集成测试需要 PostgreSQL、Redis、消息队列等临时依赖时,查 jobs.<job_id>.services。它让依赖随 Job 创建并在 Job 结束后销毁;访问方式取决于 Job 是直接跑在 Runner 上,还是运行在 container 中。
怎么判读
| 键 | 含义 | 建议动作 |
|---|---|---|
image |
服务容器镜像,服务定义的核心字段 | 为可重复 CI 固定主版本或镜像摘要 |
env |
传给服务容器的环境变量 | 只放服务启动所需配置,敏感值引用 Secrets |
options |
额外的 Docker 创建参数 | 常用于 --health-* 健康检查;--network 与 --entrypoint 不受支持 |
ports |
将容器端口映射到 Docker 主机 | Job 直接跑在 Runner 上时按需配置 |
credentials |
拉取私有镜像时使用的注册表凭据 | 使用 Secrets 提供用户名和密码 |
volumes |
服务容器卷挂载 | 只有确需共享 Job 内数据时再配置 |
快速配置
下面的完整工作流启动 PostgreSQL,并让 Runner 通过 GitHub 分配的随机主机端口确认 TCP 可连接。健康检查通过后,Job 步骤才继续执行。
name: Service container check
on:
workflow_dispatch:
jobs:
integration:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:16
env:
POSTGRES_PASSWORD: postgres
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
ports:
- 5432/tcp
steps:
- name: Verify PostgreSQL port
env:
PG_PORT: ${{ job.services.postgres.ports['5432'] }}
run: |
echo "PostgreSQL host port: $PG_PORT"
timeout 5 bash -c "cat < /dev/null > /dev/tcp/127.0.0.1/$PG_PORT"
echo "TCP connection OK"预期输出:
PostgreSQL host port: <PORT>
TCP connection OK<PORT> 是 Runner 上动态分配的实际端口,每次运行可能不同。
访问方式
| Job 运行位置 | 服务地址 | 是否通常需要 ports |
|---|---|---|
| 直接运行在 Linux Runner | localhost 或 127.0.0.1 加映射后的主机端口 |
需要 |
Job 使用 container |
服务标签作为主机名,例如 postgres:5432 |
不需要,同一 Docker 网络内端口可直接互通 |
服务只属于声明它的那个 Job,生命周期由 Runner 管理。若镜像健康检查失败,先看服务容器启动日志、环境变量和镜像自身要求,而不是继续重试测试步骤。
适用范围
GitHub Actions 的服务容器要求 Linux:GitHub 托管 Runner 使用 Ubuntu;自托管 Runner 需为 Linux 且安装 Docker。服务容器不能在 composite action 内部创建。具体镜像变量、健康检查命令和初始化行为以对应镜像文档为准。
在服务容器中通过 ports 暴露需要被 Job 步骤访问的端口;端口映射只解决访问路径,不能替代服务本身的健康检查与启动就绪判断。
定义服务端口
当 Job 直接运行在 Linux Runner 上、需要访问 services 中的容器时,查 jobs.<job_id>.services.<service_id>.ports。它负责把容器端口发布到 Docker 主机;端口可达不代表服务已经健康或完成初始化。
怎么判读
ports 写法 |
含义 | Job 中的访问方式 |
|---|---|---|
8080:80 |
主机 TCP 8080 映射到容器 TCP 80 | 127.0.0.1:8080 |
8080:80/udp |
主机 UDP 8080 映射到容器 UDP 80 | 使用 UDP 访问主机 8080 |
8080/udp |
容器 UDP 8080 映射到随机主机端口 | 从 job.services.<service>.ports 读取实际端口 |
6379/tcp |
容器 TCP 6379 映射到随机主机端口 | 从端口上下文读取实际端口 |
固定主机端口便于直接访问,但可能发生端口冲突;并行 Job 或自托管 Runner 上更适合让 GitHub 分配随机主机端口。
快速确认
下面的完整工作流把 Nginx 容器的 80 端口映射到 Runner 的 8080,并用 curl 等待服务可访问后读取 HTTP 状态码。
name: Service port check
on:
workflow_dispatch:
jobs:
integration:
runs-on: ubuntu-latest
services:
web:
image: nginx:alpine
ports:
- 8080:80
steps:
- name: Verify mapped port
run: |
status="$(curl --silent --output /dev/null --write-out '%{http_code}' --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/)"
test "$status" = "200"
echo "HTTP status: $status"预期输出:
HTTP status: 200如果固定端口已被占用,服务容器会因端口绑定失败而无法正常启动;改用空闲端口,或只声明容器端口并读取 GitHub 分配的随机主机端口。
运行位置差异
Job 直接跑在 Runner 上时,必须把需要访问的服务端口映射到 Docker 主机,然后通过 localhost 或 127.0.0.1 访问。Job 自身运行在 container 中时,Job 与服务处于同一 Docker 网络,通常不需要 ports;直接使用服务标签作为主机名和容器原始端口。
适用范围
这些规则适用于 GitHub Actions 服务容器的 Linux Runner 场景。ports 的协议、宿主端口冲突和随机端口读取方式遵循 GitHub Actions 对 Docker 服务容器的封装;服务自身监听哪个端口、何时可用,仍以镜像文档为准。
使用服务容器的 volumes 配置共享或持久化挂载点,适合需要文件交换的测试场景;应结合 Runner 生命周期确认数据是否需要保留。
挂载服务卷
当服务容器需要与同一 Job 中的验证步骤共享文件或挂载固定数据目录时,查 jobs.<job_id>.services.<service_id>.volumes。它把 Docker 命名卷或 Runner 上的主机路径映射到服务容器路径;不要把它当作跨 Job 的持久存储。
怎么判读
| 写法 | 含义 | 建议动作 |
|---|---|---|
name:/container/path |
挂载 Docker 命名卷 | 适合同一 Runner 环境内共享数据 |
/host/path:/container/path |
绑定 Runner 主机路径 | 仅在确实需要主机文件时使用,并确认源路径存在 |
容器侧目标必须使用绝对路径。GitHub-hosted Runner 是临时环境,因此不要依赖命名卷在后续 Job 或后续工作流中继续存在;自托管 Runner 还要考虑残留卷的清理和敏感数据暴露。

可验证配置
下面的完整工作流让一个步骤向命名卷写入 index.html,服务容器从同一卷提供该文件,再由 Runner 读取。
name: verify-service-volume
on:
workflow_dispatch:
jobs:
volume-test:
runs-on: ubuntu-latest
services:
web:
image: nginx:1.27-alpine
ports:
- 8080:80
volumes:
- shared-content:/usr/share/nginx/html
steps:
- name: Write file into shared volume
run: |
docker run --rm \
-v shared-content:/data \
alpine:3.20 \
sh -c 'printf "shared-ok\n" > /data/index.html'
- name: Read file through service container
run: curl --fail --silent http://127.0.0.1:8080/预期输出:
shared-ok如果第二步返回 404 或连接失败,先检查卷名是否完全一致,再检查目标挂载路径和 ports 映射。
适用范围
此键用于 GitHub Actions 的 service containers,要求 Runner 能运行 Docker;GitHub-hosted 场景通常使用 Ubuntu Runner。若目标是跨 Job、跨 Runner 或长期保留文件,应改用 artifact、cache 或外部存储,而不是依赖 service volume。
为服务容器配置健康检查可让依赖服务在进入使用阶段前接受可验证状态判断,适合数据库、缓存等启动时间不固定的集成测试环境。
配置服务健康检查
当数据库、缓存或其他服务容器启动后仍需要初始化时间时,查 jobs.<job_id>.services.<service_id>.options 中的 Docker health check 参数。健康检查把“容器进程已启动”和“服务已可用”分开,避免测试步骤过早连接。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
--health-cmd |
定义容器内实际执行的探测命令 | 使用能验证真实服务能力的命令 |
--health-interval |
两次探测之间的间隔 | 根据典型启动时间设置,避免过密探测 |
--health-timeout |
单次探测允许的最长时间 | 应短于整体启动容忍时间 |
--health-retries |
连续失败达到阈值后判为不健康 | 给冷启动留出合理重试次数 |
Docker 状态为 healthy |
服务通过健康检查 | 再进入依赖该服务的阶段 |
Docker 状态为 unhealthy |
探测持续失败 | 先看健康检查输出和容器日志 |

可验证配置
下面使用 Nginx 镜像中的 wget 探测容器本机 HTTP 端点,再由 Job 步骤读取映射端口确认服务可用。
name: verify-service-health
on:
workflow_dispatch:
jobs:
health-test:
runs-on: ubuntu-latest
services:
web:
image: nginx:1.27-alpine
ports:
- 8080:80
options: >-
--health-cmd "wget -q --spider http://127.0.0.1/ || exit 1"
--health-interval 5s
--health-timeout 3s
--health-retries 5
steps:
- name: Verify HTTP service
run: |
curl --fail --silent \
--output /dev/null \
--write-out '%{http_code}\n' \
http://127.0.0.1:8080/预期输出:
200健康命令是在服务容器内部执行的,因此它依赖镜像中已有的工具;把宿主机存在的命令直接写进 --health-cmd,如果镜像内没有该命令,健康检查会持续失败。
失败时先看什么
先检查 health check 本身,再检查应用日志。自托管 Runner 可用 docker ps、docker inspect <container> 和 docker logs <container> 查看健康状态、探测输出与启动错误;容器 ID 或名称是动态值,不应写死。
GitHub Actions 这里使用 Docker health check 语义,具体探测命令由所选镜像决定。数据库等服务应优先使用镜像提供的就绪检查命令,而不是只判断端口是否打开。
表达式与上下文
GitHub Actions 表达式通过 github、env、vars、needs、matrix、runner 等上下文读取运行时数据,适合条件、参数和动态名称计算。
使用表达式上下文
需要在 if、动态名称、参数或步骤中读取运行时数据时查这条。GitHub Actions 表达式用 ${{ <expression> }} 访问上下文;先确认目标键所在作用域允许该上下文,再读取所需属性。
常用上下文怎么判读
| 上下文 | 主要内容 | 出现条件或范围 | 建议动作 |
|---|---|---|---|
github |
仓库、事件、引用、运行等信息 | 工作流运行期间广泛可用,但具体属性取决于触发事件 | 用于分支、事件类型、仓库和运行信息判断 |
env |
工作流、Job 或 Step 定义的环境变量 | 只包含对应作用域中已定义的 env 值 |
读取配置值;不要与 Runner Shell 中的环境变量语法混淆 |
vars |
组织、仓库或环境级配置变量 | 只有已配置且当前运行可访问的变量才有值 | 放非敏感配置;敏感值改用 secrets |
needs |
依赖 Job 的结果与输出 | 当前 Job 必须通过 needs 声明依赖 |
读取前置 Job 的 result 或 outputs 决定后续动作 |
matrix |
当前矩阵组合的字段 | Job 使用 strategy.matrix 时可用 |
生成不同参数组合、名称或命令参数 |
runner |
当前 Runner 的操作系统、架构、临时目录等信息 | Job 已进入 Runner 执行阶段后常用于 Step | 根据执行环境调整脚本或读取 Runner 路径 |
快速确认
下面的工作流同时验证 github、env、matrix、runner 和 needs。保存为 .github/workflows/context-demo.yml 后,从 Actions 页面手动运行。
name: context-demo
on:
workflow_dispatch:
env:
APP_NAME: anystack
jobs:
build:
runs-on: ubuntu-latest
outputs:
sha: ${{ steps.meta.outputs.sha }}
steps:
- id: meta
shell: bash
run: echo "sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
verify:
needs: build
strategy:
matrix:
node: [20, 22]
runs-on: ubuntu-latest
steps:
- name: Show context values
shell: bash
run: |
echo "repo=${{ github.repository }}"
echo "app=${{ env.APP_NAME }}"
echo "node=${{ matrix.node }}"
echo "runner=${{ runner.os }}"
echo "sha=${{ needs.build.outputs.sha }}"预期结果:verify 会运行两次。两次日志中的仓库和提交值相同,node 分别为 20、22;在 ubuntu-latest 上 runner 为 Linux。
repo=<OWNER>/<REPO>
app=anystack
node=20
runner=Linux
sha=<SHA>第二个矩阵任务只会把 node=20 改为 node=22;<OWNER>/<REPO> 与 <SHA> 以实际运行值为准。
判读与动作
表达式拿不到预期值时,先检查上下文是否在当前位置可用,再检查触发事件是否提供对应属性。例如 matrix 只在矩阵 Job 中有意义,needs 只暴露当前 Job 声明依赖的 Job。vars 是否有值还取决于组织、仓库或环境级配置。
适用范围
本条适用于 GitHub Actions 工作流表达式。上下文能否用于某个 YAML 键由 GitHub Actions 的上下文可用性规则决定;GitHub Enterprise Server 还应按部署版本核对对应文档。
使用 success()、failure()、cancelled() 和 always() 等状态函数区分前置步骤结果,适合成功处理、失败报告、清理和收尾任务。
按结果条件分支
需要让步骤或 Job 根据前置执行结果选择成功处理、失败报告、取消处理或收尾逻辑时查这条。状态函数主要放在 if 条件中;没有显式状态检查函数时,GitHub Actions 会把 success() 作为默认状态检查。
状态函数怎么判读
| 函数 | 为 true 的典型条件 |
适合动作 |
|---|---|---|
success() |
当前范围内此前步骤都成功 | 只在正常路径继续执行 |
failure() |
当前 Job 的此前步骤失败;在依赖 Job 链中也可反映祖先 Job 失败 | 上传失败日志、生成诊断、执行失败专用处理 |
cancelled() |
工作流已被取消 | 记录取消状态或执行取消专用分支 |
always() |
即使前面失败或工作流被取消也返回 true |
适合日志与收尾;不应无条件包住可能阻塞的关键任务 |
快速确认
下面的工作流故意让第一步失败,用一次运行直接观察 success()、failure() 和 always() 的分支差异。
name: status-demo
on:
workflow_dispatch:
jobs:
demo:
runs-on: ubuntu-latest
steps:
- name: Fail intentionally
shell: bash
run: exit 1
- name: Success branch
if: ${{ success() }}
shell: bash
run: echo "success branch"
- name: Failure branch
if: ${{ failure() }}
shell: bash
run: echo "failure branch"
- name: Always branch
if: ${{ always() }}
shell: bash
run: echo "always branch"预期结果:在 Actions 运行详情中,第一步失败,成功分支跳过,失败分支和 always() 分支执行;整个 Job 最终仍为失败。
Fail intentionally: failure
Success branch: skipped
Failure branch: failure branch
Always branch: always branch
Job conclusion: failurecancelled() 需要在运行期间实际取消工作流才能变为 true,因此不能由上面的自动失败场景触发。
处理顺序
只关心正常路径时使用 success() 或直接依赖默认状态检查。失败后的诊断条件若还要叠加其它判断,应显式保留 failure(),否则默认的 success() 检查可能使该分支无法运行。
需要“成功或失败都执行,但取消时不执行”的收尾逻辑时,优先写 if: ${{ !cancelled() }}。always() 连取消状态也会执行,不适合包住拉取源码、等待外部资源等可能在取消后继续阻塞的关键步骤。
适用范围
本条适用于 GitHub Actions 工作流的 if 表达式状态检查。若运行在 GitHub Enterprise Server,应按实际部署版本核对表达式函数行为与可用性。
通过 github.event 读取触发事件提供的字段,可结合提交、分支、Pull Request 或手动输入上下文动态调整工作流行为。
读取事件上下文
当工作流需要根据触发事件携带的数据做条件判断、取提交信息或读取 Pull Request、手动触发参数时,查 github.event。它对应当前触发事件的 payload;先确认事件类型,再读取该事件实际提供的字段。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
github.event_name |
当前触发器名称 | 先用它确认 payload 应按哪类事件解释 |
github.event.<field> |
读取事件 payload 中的字段 | 只访问该事件文档明确提供的字段 |
github.event.pull_request |
Pull Request 事件常见对象 | 先确认当前事件确实包含 pull_request |
github.event.inputs |
workflow_dispatch 事件中的手动输入 |
读取前确认工作流由 workflow_dispatch 触发 |
同名字段并不保证在所有事件中都存在。对 push、pull_request、workflow_dispatch 等事件,应分别按各自 payload 判断,不能把某一种事件的结构当成通用结构。
快速确认
下面的工作流只在手动触发时运行,并读取 workflow_dispatch payload 中的 ref 与 inputs.target。
name: inspect-event
on:
workflow_dispatch:
inputs:
target:
description: Deployment target
required: true
default: staging
jobs:
inspect:
runs-on: ubuntu-latest
steps:
- name: Print event fields
env:
REF_NAME: ${{ github.event.ref }}
TARGET: ${{ github.event.inputs.target }}
run: |
printf 'ref=%s\n' "$REF_NAME"
printf 'target=%s\n' "$TARGET"预期结果:如果在分支 main 上使用默认输入触发,日志中可读到以下两行。
ref=main
target=staging实际 ref 与输入值取决于触发时选择的分支和参数。
处理顺序
先看 github.event_name,再按对应事件文档确认 github.event 的字段结构;对可选对象先做条件判断,避免直接读取不存在的字段。排查时可临时用 ${{ toJSON(github.event) }} 查看当前 payload,但事件数据可能包含不应长期写入日志的信息,确认后应删除调试输出。
适用范围:GitHub Actions 表达式上下文。事件字段由触发器决定,具体 payload 以 GitHub 对应事件文档为准。
使用 vars 读取仓库、组织或环境级配置变量,适合保存非敏感部署参数;与 secrets 的职责不同,不应用来存放私密凭据。
读取变量上下文
当工作流需要读取可复用的非敏感配置值时,查 vars。它用于引用组织、仓库或环境级配置变量;敏感令牌、密码和私钥应放在 secrets,不要写进 vars。
怎么判读
| 写法或线索 | 含义 | 建议动作 |
|---|---|---|
vars.NAME |
读取名为 NAME 的配置变量 |
用于区域、环境名、功能开关等非敏感值 |
| 组织级变量 | 可由组织集中管理 | 同时检查变量对目标仓库的可见范围 |
| 仓库级变量 | 仅供当前仓库工作流使用 | 适合仓库自己的默认配置 |
| 环境级变量 | 与指定 Environment 关联 | 确认 Job 使用了对应 environment |
| 变量不存在 | 表达式求值为空字符串 | 检查名称、作用域与可见性,不要把空值误当有效配置 |
vars 与 secrets 的边界很简单:需要保密的值不要使用 vars。配置变量的值会按字符串参与表达式或注入环境变量,布尔或数字语义应由工作流显式判断。
快速确认
假设当前仓库已经存在配置变量 DEPLOY_REGION,值为 us-west-2。下面的工作流把它注入步骤环境变量并打印。
name: inspect-vars
on:
workflow_dispatch:
jobs:
inspect:
runs-on: ubuntu-latest
steps:
- name: Print repository variable
env:
DEPLOY_REGION: ${{ vars.DEPLOY_REGION }}
run: printf 'region=%s\n' "$DEPLOY_REGION"预期输出:
region=us-west-2如果 DEPLOY_REGION 未定义或当前作用域不可见,表达式会得到空字符串,对应日志为 region=。
处理顺序
读取不到值时,依次检查变量名是否完全一致、变量定义在哪个层级、组织级变量是否授权给当前仓库,以及 Job 是否使用了预期 Environment。若该值属于凭据或其他秘密信息,应改用 secrets,不要为了让 vars 可读而降低保密要求。
适用范围:GitHub Actions configuration variables 与 vars context。组织、仓库和环境级变量的管理权限与可见范围受目标仓库和组织设置影响。
通过 runner 上下文获取当前 Runner 的操作系统、架构、临时目录和工作目录等运行信息,适合编写需要区分执行环境的脚本。
读取 Runner 上下文
当同一工作流需要根据实际执行 Runner 的操作系统、架构或临时目录调整命令时,读取 runner 上下文即可获得当前 Job 的运行环境信息。工作区路径不属于 runner,应从 github.workspace 读取。
常用值
| 表达式 | 含义 | 判读或动作 |
|---|---|---|
runner.os |
Runner 操作系统 | 按 Linux、Windows 或 macOS 选择命令和路径写法 |
runner.arch |
Runner CPU 架构 | 判断工具是否需要对应架构的二进制文件 |
runner.name |
当前 Runner 名称 | 辅助定位实际执行节点,尤其适合自托管 Runner |
runner.temp |
当前 Job 可使用的临时目录 | 存放无需长期保留的中间文件 |
runner.tool_cache |
Runner 工具缓存目录 | 查询预安装工具所在缓存位置 |
runner.debug |
调试日志状态相关值 | 在启用 Runner 调试时辅助增加诊断输出 |
runner.environment |
Runner 环境类别 | 区分 GitHub 托管与自托管执行环境 |
github.workspace |
当前工作区路径 | 需要仓库工作目录时使用,不要写成不存在的 runner.workspace |
快速确认
下面的工作流在 GitHub 托管的 Ubuntu Runner 上打印最常用的环境值,可直接通过 workflow_dispatch 手动运行。
name: inspect-runner-context
on:
workflow_dispatch:
jobs:
inspect:
runs-on: ubuntu-24.04
steps:
- name: Print runner context values
shell: bash
run: |
printf 'os=%s\n' '${{ runner.os }}'
printf 'arch=%s\n' '${{ runner.arch }}'
printf 'temp=%s\n' '${{ runner.temp }}'
printf 'workspace=%s\n' '${{ github.workspace }}'预期输出:日志中会出现操作系统、架构以及两个绝对路径。路径包含仓库名和 Runner 工作目录,实际值可能不同。
os=Linux
arch=X64
temp=<PATH>
workspace=<PATH>判读与使用
需要跨平台分支时优先判断 runner.os,需要下载架构相关工具时再判断 runner.arch。临时文件写入 runner.temp,仓库检出后的文件则以 github.workspace 为基准,避免把 Runner 安装目录或固定绝对路径写死。
适用范围
runner 是 GitHub Actions 表达式上下文,适合在已分配 Runner 的 Job 步骤中读取执行环境。可用属性以目标 GitHub Actions 环境实际提供的 Runner 上下文为准;如果需要仓库、提交、事件或工作区之外的信息,应分别查询对应的 github、env、matrix 等上下文。
制品与缓存
通过官方 Artifact Action 将构建结果保存为跨 Job 可访问的制品,适合把编译产物从独立 Runner 传递到测试、签名或部署阶段。
上传构建制品
当构建 Job 生成的文件还要交给后续测试、签名或部署 Job 使用时,通过官方 Artifact Action 上传制品。不同 Job 通常运行在彼此隔离的 Runner 上,仅设置 needs 只能建立执行顺序,不能共享本地文件系统。
数据如何跨 Job 传递

常用输入
| 输入 | 含义 | 建议动作 |
|---|---|---|
name |
制品名称 | 为构建目标设置稳定且可区分的名称 |
path |
要上传的文件、目录或匹配模式 | 上传前确认构建确实生成目标文件 |
if-no-files-found |
未匹配文件时的处理方式 | 关键构建产物建议设为 error,避免空制品悄然通过 |
retention-days |
制品保留时间 | 按仓库允许范围和审计需求设置 |
compression-level |
压缩级别 | 大型已压缩文件可按耗时与体积权衡 |
overwrite |
同名制品冲突时是否覆盖 | 需要固定名称时显式决定覆盖策略 |
include-hidden-files |
是否包含隐藏文件 | 只有确实需要时开启,并先检查其中是否包含密钥或配置秘密 |
可验证示例
下面的工作流先生成一个文件并上传为 app-dist,然后在另一个 Runner 上下载并验证内容。示例使用 actions/upload-artifact@v4 与对应的 actions/download-artifact@v4。
name: artifact-transfer
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-24.04
steps:
- name: Create build output
shell: bash
run: |
mkdir -p dist
printf 'build-ok\n' > dist/app.txt
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: app-dist
path: dist/app.txt
if-no-files-found: error
verify:
runs-on: ubuntu-24.04
needs: build
steps:
- name: Download artifact
uses: actions/download-artifact@v4
with:
name: app-dist
path: received
- name: Verify artifact
shell: bash
run: |
test "$(cat received/app.txt)" = "build-ok"
printf 'artifact=%s\n' "$(cat received/app.txt)"预期输出:build Job 成功上传名为 app-dist 的制品,verify Job 下载后通过内容断言,并在日志中输出:
artifact=build-ok判读与失败处理
如果上传步骤提示找不到文件,先检查构建输出路径以及 path 相对于当前工作区的位置;关键制品应使用 if-no-files-found: error,不要让后续 Job 在缺失输入的情况下继续运行。下游下载失败时,优先核对 Artifact 名称是否与上传步骤完全一致,以及上传 Job 是否已经成功结束。
同名制品不应被当作可持续追加的共享目录使用。矩阵构建需要分别保存不同平台产物时,给每个矩阵组合使用唯一名称,或者在单次上传中明确收集需要的全部路径。
适用范围
本示例按 actions/upload-artifact@v4 的工作方式编写。GitHub.com 与不同 GitHub Enterprise Server 版本对 Action 主版本的支持可能不同,实际使用前应以目标平台支持的官方 Artifact Action 版本和仓库保留策略为准。
通过官方 Artifact Action 下载先前作业上传的制品,使后续 Job 不依赖前一个 Runner 的本地文件系统,适合跨阶段传递构建结果。
下载构建制品
当后续 Job 需要使用前一个 Job 生成的二进制、报告或打包文件时,先用 actions/upload-artifact 上传,再用 actions/download-artifact 下载。Artifact 是跨 Job 的持久化传递介质,不依赖前一个 Runner 的工作目录仍然存在。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
| 后续 Job 找不到前一 Job 的本地文件 | Job 通常运行在独立 Runner 上,本地磁盘不共享 | 在生产 Job 上传 Artifact,在消费 Job 下载 |
| 已知 Artifact 名称 | 可以精确下载单个制品 | 给 name 传入上传时的同名值 |
| 需要放到固定目录 | 默认位置不便于后续命令引用 | 用 path 指定下载目录 |
| 需要其他工作流运行或仓库中的 Artifact | 默认作用域不足 | 按官方 Action 文档提供 github-token、repository 和 run-id 等输入,并授予最小读取权限 |
快速确认
下面的完整工作流先生成并上传 app-build,再在另一个 Job 中下载并读取文件。
name: artifact-download-demo
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Create artifact
run: |
mkdir -p dist
printf 'hello\n' > dist/result.txt
- name: Upload artifact
uses: actions/upload-artifact@v7
with:
name: app-build
path: dist/result.txt
consume:
needs: build
runs-on: ubuntu-latest
steps:
- name: Download artifact
uses: actions/download-artifact@v8
with:
name: app-build
path: downloaded
- name: Verify artifact
run: cat downloaded/result.txt预期输出:
hello如果下载步骤提示找不到 Artifact,先核对上传步骤是否成功、name 是否完全一致,以及消费 Job 是否通过 needs 等方式等待生产 Job 完成。
适用范围
Artifact 适合保存构建产物、测试报告和 Job 间必须传递的文件;依赖下载目录、编译中间缓存等可重新生成内容通常更适合 Cache。示例按 GitHub.com 当前官方主版本 actions/upload-artifact@v7 与 actions/download-artifact@v8 编写;GitHub Enterprise Server 的可用版本和后端兼容性可能不同,应以对应 GHES 版本的官方兼容表为准。
通过官方 Cache Action 保存依赖或构建缓存,减少重复下载与编译时间;缓存用于加速而非权威制品,命中后仍应允许流程正常重新生成结果。
配置依赖缓存
当依赖下载或中间构建结果可以安全重建、但重复生成耗时时,用 actions/cache 在工作流运行之间复用这些文件。缓存只能作为加速层;即使未命中或缓存被清理,流程也应能重新下载或生成所需内容。
怎么判读
| 线索 | 含义 | 建议动作 |
|---|---|---|
cache-hit 为 true |
主 key 精确命中 |
直接复用缓存,仍按项目需要执行校验或安装步骤 |
cache-hit 为 false |
主键未精确命中,可能未命中或只通过 restore-keys 恢复了旧缓存 |
运行正常的依赖安装或生成步骤,让当前内容重新达到正确状态 |
| 锁文件变化后持续命中旧内容 | key 没有包含能反映依赖变化的信息 |
将 hashFiles() 的锁文件哈希纳入主键 |
| 不同系统复用后出现不兼容文件 | 缓存键没有区分运行环境 | 将 runner.os、架构或工具链版本加入键 |
快速确认
前置条件是仓库包含 package-lock.json。下面缓存 npm 的下载缓存目录 ~/.npm,但仍执行 npm ci,因此即使缓存缺失也能正确重建依赖。
name: dependency-cache-demo
on:
workflow_dispatch:
jobs:
install:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Restore npm cache
id: npm-cache
uses: actions/cache@v6
with:
path: ~/.npm
key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-npm-
- name: Install dependencies
run: npm ci
- name: Show cache result
run: echo "cache-hit=${{ steps.npm-cache.outputs.cache-hit }}"首次使用新键时,预期结果通常为:
cache-hit=false该 Job 成功结束并保存缓存后,在锁文件和主键不变的后续运行中,预期结果为:
cache-hit=true如果只通过 restore-keys 命中前缀缓存,cache-hit 仍不是主键精确命中的 true;不要因此跳过保证依赖正确性的安装或生成步骤。
键与边界
主键应同时表达平台、工具链和依赖版本,例如操作系统加锁文件哈希。缓存内容是可淘汰、可失效的性能优化,不应保存发布包、唯一测试证据或其他无法重建的权威输出;这些内容应使用 Artifact 或外部制品仓库。
示例按 GitHub.com 当前官方 actions/cache@v6 编写。GitHub Enterprise Server、自托管 Runner、跨操作系统缓存和权限限制存在版本差异,使用前应核对目标环境对应的官方 Action 与 Runner 兼容说明。