CI/CD / 系统课时
把重复步骤封装成复合 Action
把重复步骤封装成复合 Action
当多个工作流都重复执行安装依赖、构建或检查等步骤时,复制 YAML 会让修改逐渐失控。复合 Action 可以把一组 steps 封装成仓库内可复用的动作,让调用方只保留输入参数和一次 uses 调用。
学习目标
- 理解 composite action 适合抽取什么层级的重复逻辑
- 能定义带输入参数的复合 Action 并在工作流中调用
- 能区分复合 Action 与复用工作流的职责边界
复合 Action 抽取的是什么
复合 Action 复用的是一组步骤,而不是完整 Job。典型场景是多个 Job 都要执行相同的环境准备、依赖安装或构建命令。如果继续复制这些步骤,一旦 Node.js 版本或安装命令变化,就必须同步修改多个工作流。
调用关系可以理解为:工作流中的 Job 执行一个 uses 步骤,该步骤进入复合 Action,再按声明顺序执行其中的多个内部步骤。

复合 Action 自己不会创建独立 Job,也不能像工作流那样直接定义 runs-on、Job 级权限或服务容器。因此它最适合封装 Job 内部的局部操作。
定义一个复合 Action
仓库内的自定义 Action 通常放在 .github/actions/<NAME>/action.yml。下面把 Node.js 项目的环境准备和构建封装起来,并允许调用方指定 Node.js 版本。
片段示例:以下内容保存为 .github/actions/build-node/action.yml,依赖调用它的 Job 已经通过 checkout 将仓库内容检出到 runner。
name: Build Node project
description: Set up Node.js, install dependencies, and build
inputs:
node-version:
description: Node.js version used for the build
required: false
default: "22"
runs:
using: composite
steps:
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: npm
- name: Install dependencies
shell: bash
run: npm ci
- name: Build
shell: bash
run: npm run build这里的 runs.using: composite 声明这是复合 Action。inputs 是调用边界,内部通过 ${{ inputs.node-version }} 读取值。复合 Action 中的 run 步骤需要明确提供 shell,避免依赖调用方环境的隐式行为。
验证方法是在工作流中调用该 Action,并观察内部三个步骤是否依次执行;配置文件本身不会产生独立控制台输出。
在工作流中调用
片段示例:以下工作流假设仓库根目录存在可执行的 Node.js 项目,并且 package.json 已定义 build 脚本。
name: CI
on:
push:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Build project
uses: ./.github/actions/build-node
with:
node-version: "22"uses: ./.github/actions/build-node 是仓库内的相对路径。由于本地 Action 文件也属于仓库内容,所以必须先执行 checkout,否则 runner 上没有这个目录可供加载。
预期结果
Set up Node.js
Install dependencies
Build实际日志还会包含各 Action 和命令产生的详细内容;这里列出的是应出现的三个核心步骤名称。如果任一步骤失败,Job 会在对应位置显示失败状态。
设计可复用边界
不要因为能封装就把整个流水线塞进一个复合 Action。好的复合 Action 通常有明确职责,例如“准备 Node.js 并构建”或“执行统一代码检查”,输入数量也保持有限。
需要让调用方变化的值放进 inputs;真正固定的组织规范留在内部。这样既消除了重复,又不会让调用方通过大量参数重新拼装内部实现。
如果需要复用的已经不是几个步骤,而是包含 runs-on、权限、多个 Job、Job 依赖或部署环境的一整段流水线,应改用 reusable workflow。复合 Action 的边界应停留在“可复用步骤集合”,这样调用关系和故障位置都更容易维护。