CI/CD / 系统课时

把重复步骤封装成复合 Action

把重复步骤封装成复合 Action

当多个工作流都重复执行安装依赖、构建或检查等步骤时,复制 YAML 会让修改逐渐失控。复合 Action 可以把一组 steps 封装成仓库内可复用的动作,让调用方只保留输入参数和一次 uses 调用。

学习目标

  • 理解 composite action 适合抽取什么层级的重复逻辑
  • 能定义带输入参数的复合 Action 并在工作流中调用
  • 能区分复合 Action 与复用工作流的职责边界

复合 Action 抽取的是什么

复合 Action 复用的是一组步骤,而不是完整 Job。典型场景是多个 Job 都要执行相同的环境准备、依赖安装或构建命令。如果继续复制这些步骤,一旦 Node.js 版本或安装命令变化,就必须同步修改多个工作流。

调用关系可以理解为:工作流中的 Job 执行一个 uses 步骤,该步骤进入复合 Action,再按声明顺序执行其中的多个内部步骤。

工作流调用复合 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。

yaml
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 脚本。

yaml
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 上没有这个目录可供加载。

预期结果

text
Set up Node.js
Install dependencies
Build

实际日志还会包含各 Action 和命令产生的详细内容;这里列出的是应出现的三个核心步骤名称。如果任一步骤失败,Job 会在对应位置显示失败状态。

设计可复用边界

不要因为能封装就把整个流水线塞进一个复合 Action。好的复合 Action 通常有明确职责,例如“准备 Node.js 并构建”或“执行统一代码检查”,输入数量也保持有限。

需要让调用方变化的值放进 inputs;真正固定的组织规范留在内部。这样既消除了重复,又不会让调用方通过大量参数重新拼装内部实现。

如果需要复用的已经不是几个步骤,而是包含 runs-on、权限、多个 Job、Job 依赖或部署环境的一整段流水线,应改用 reusable workflow。复合 Action 的边界应停留在“可复用步骤集合”,这样调用关系和故障位置都更容易维护。

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

目录与阅读设置

阅读设置

17

记录一个想法

把重复步骤封装成复合 Action

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

登录哪都通