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。示例用输入决定制品名称,并把最终名称作为工作流输出返回。

yaml
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 位于同一仓库。

yaml
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 }}"

预期输出

text
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 的核心价值。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把整段流程改成复用工作流

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通