CI/CD / 系统课时
把整段流程改成复用工作流
把整段流程改成复用工作流
当多个仓库或工作流都拥有几乎相同的构建、测试或部署 Job 时,只抽取几个步骤已经不够。GitHub Actions 的 reusable workflow 可以通过 workflow_call 暴露输入、密钥和输出,把完整 Job 流程变成具有明确调用契约的公共流水线。
学习目标
- 能使用
workflow_call定义可调用的复用工作流 - 能通过输入和输出建立调用方与复用工作流之间的契约
- 理解复用工作流与普通步骤封装的边界
从复制 Job 到调用工作流
复用工作流本身仍然是工作流文件,可以拥有一个或多个 Job,并为 Job 定义 runs-on、权限、环境和依赖关系。调用方不需要知道内部每个步骤,只需要传入约定的参数并消费输出。
一次典型调用会跨越三个层次:调用方 Job 传入输入,复用工作流执行内部 Job,内部步骤产生的值再逐级映射为 Job 输出和工作流输出。

这种边界特别适合组织级标准构建、统一安全扫描或部署流程,因为调用方无法随意遗漏内部规定的关键步骤。
定义 workflow_call 契约
片段示例:以下文件保存为 .github/workflows/reusable-build.yml。示例用输入决定制品名称,并把最终名称作为工作流输出返回。
name: Reusable build
on:
workflow_call:
inputs:
artifact-name:
description: Name of the generated artifact
required: false
type: string
default: app
outputs:
artifact-name:
description: Artifact name returned to the caller
value: ${{ jobs.build.outputs.artifact-name }}
jobs:
build:
runs-on: ubuntu-latest
outputs:
artifact-name: ${{ steps.result.outputs.name }}
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Build
run: echo "build commands run here"
- name: Publish result
id: result
shell: bash
run: echo "name=${{ inputs.artifact-name }}" >> "$GITHUB_OUTPUT"输出存在两级映射:result 步骤先写入 $GITHUB_OUTPUT,jobs.build.outputs 再暴露 Job 输出,最后由 on.workflow_call.outputs 暴露给调用方。任何一级名称写错,调用方都会拿不到预期值。
验证方法是由另一个工作流调用该文件并读取输出;该 YAML 定义本身不会单独执行。
调用复用工作流
调用 reusable workflow 时,uses 位于 Job 级,而不是普通 steps 内。下面调用同一仓库中的工作流,并让后续 Job 使用它返回的值。
片段示例:以下文件可保存为 .github/workflows/ci.yml,与前面的 reusable-build.yml 位于同一仓库。
name: CI
on:
push:
jobs:
call-build:
uses: ./.github/workflows/reusable-build.yml
with:
artifact-name: web-app
report:
needs: call-build
runs-on: ubuntu-latest
steps:
- name: Show returned value
shell: bash
run: echo "artifact=${{ needs.call-build.outputs.artifact-name }}"预期输出
artifact=web-app实际运行中,call-build 会显示复用工作流内部 Job 的执行记录;report 只有在依赖满足后才运行。动态日志时间、runner 信息等内容可能不同,不应作为输出契约的一部分。
输入、密钥与权限边界
workflow_call.inputs 适合非敏感配置,例如环境名称、构建模式或制品名称。密码、令牌等敏感值应通过 workflow_call.secrets 声明并由调用方传递,而不是伪装成普通输入。
复用工作流也不应假设自己天然拥有调用方的所有权限。设计部署类公共流程时,应显式审视 permissions、环境保护规则和所需 secrets,让调用契约能够说明“这段流程需要什么”,而不是依赖隐藏前提。
什么时候升级为复用工作流
如果重复内容只是 Job 内的几条命令,复合 Action 更轻量;如果重复的是完整 Job,或者需要统一 runner、权限、多个 Job 的依赖和部署规则,reusable workflow 更合适。
维护时应把 workflow_call 看成接口:输入名称、类型和输出名称一旦被多个调用方依赖,修改它们就可能破坏现有流水线。稳定契约、隐藏内部步骤,才是复用工作流相对于复制 YAML 的核心价值。