创建 GitHub Actions 组合操作-未完纪

本教程介绍如何构建组合操作，将多个步骤封装起来，在工作流中复用。

简介

本指南说明创建和使用组合操作所需的基本组件，重点在于打包操作，示例功能只是验证这些组件：先输出“Hello World”和“Goodbye”；传入自定义名称时，输出“Hello [who-to-greet]”和“Goodbye”。操作还会把随机数映射到 random-number 输出，并运行 goodbye.sh 脚本。完成后，你将了解如何构建自己的组合操作，以及如何在工作流中测试它。

创建工作流和操作时，需要考虑代码是否会执行来自潜在攻击者的不可信输入。攻击者可能把恶意内容插入某些上下文，因此应将这些上下文视为不可信输入。详见安全使用指南。

组合操作与可重用工作流

组合操作把一组作业步骤收集成单个操作，可在多个工作流中作为一个作业步骤执行。可重用工作流则允许从另一个工作流调用完整工作流。这是两种不同的复用方式，参见重用工作流配置。

先决条件

这里先把组合操作放在独立仓库中；也可以放在同一仓库，后文会介绍这种组织方式。

在 GitHub 上创建新的公共仓库。可以自行命名，下面使用 hello-world-composite-action。相关说明见创建新仓库。
将仓库克隆到本机，参见克隆仓库。
在终端进入新仓库：
```
cd hello-world-composite-action
```
在仓库中新建 goodbye.sh，写入示例脚本：
```
echo "echo Goodbye" > goodbye.sh
```
让 goodbye.sh 具有可执行权限。macOS：
```
chmod +x goodbye.sh
```
Linux：
```
chmod +x goodbye.sh
```
Windows 可通过 Git 标记可执行位：
```
git add --chmod=+x -- goodbye.sh
```

提交并推送脚本。macOS：

git add goodbye.sh
git commit -m "Add goodbye script"
git push

Linux：

git add goodbye.sh
git commit -m "Add goodbye script"
git push

Windows 的上一条命令已经暂存文件，这里提交并推送：

git commit -m "Add goodbye script"
git push

创建操作元数据文件

在 hello-world-composite-action 仓库中创建 action.yml，加入下面的内容。语法说明见元数据语法参考。

name: 'Hello World'
description: 'Greet someone'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-number }}
runs:
  using: "composite"
  steps:
    - name: Set Greeting
      run: echo "Hello $INPUT_WHO_TO_GREET."
      shell: bash
      env:
        INPUT_WHO_TO_GREET: ${{ inputs.who-to-greet }}

    - name: Random Number Generator
      id: random-number-generator
      run: echo "random-number=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

    - name: Set GitHub Path
      run: echo "$GITHUB_ACTION_PATH" >> $GITHUB_PATH
      shell: bash
      env:
        GITHUB_ACTION_PATH: ${{ github.action_path }}

    - name: Run goodbye.sh
      run: goodbye.sh
      shell: bash

文件定义了 who-to-greet 输入，把生成的随机数映射到 random-number 输出，将操作所在路径加入运行器的系统路径，以便找到 goodbye.sh，然后运行这个脚本。输出映射详见组合操作的输出；github.action_path 的含义详见上下文参考。

提交并推送 action.yml：

git add action.yml
git commit -m "Add action"
git push

添加版本标记。本例使用 v1，关于自定义操作的版本管理见管理自定义操作。
```
git tag -a -m "Description of this release" v1
git push --follow-tags
```

在工作流中测试操作

下面的工作流使用刚才完成的操作。将它放到另一个仓库的 .github/workflows/main.yml 中，把 OWNER 替换为仓库所有者，把 SHA 替换为准备使用的提交 SHA。who-to-greet 也可以改成自己的名称。

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - uses: actions/checkout@v6
      - id: foo
        uses: OWNER/hello-world-composite-action@SHA
        with:
          who-to-greet: 'Mona the Octocat'
      - run: echo random-number "$RANDOM_NUMBER"
        shell: bash
        env:
          RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}

在仓库中打开“Actions（操作）”选项卡，选择最新一次工作流运行。按原文示例，输出应包括问候 Mona the Octocat 的文字、Goodbye 脚本的结果和随机数。这些是教程描述的预期结果。

在同一仓库中创建组合操作

新建 hello-world-composite-action 子目录。可放在任意子目录中；建议放到 .github/actions，方便组织和维护。

在该目录中按前面的步骤创建 goodbye.sh：

echo "echo Goodbye" > goodbye.sh

macOS 的执行权限设置：

chmod +x goodbye.sh

Linux 的执行权限设置：

chmod +x goodbye.sh

Windows 的执行位标记：

git add --chmod=+x -- goodbye.sh

macOS 提交与推送：

git add goodbye.sh
git commit -m "Add goodbye script"
git push

Linux 提交与推送：

git add goodbye.sh
git commit -m "Add goodbye script"
git push

Windows 提交与推送：

git commit -m "Add goodbye script"
git push

在同一目录内，依照“创建操作元数据文件”的步骤创建 action.yml。

调用操作时，将 uses 写成包含 action.yml 的目录的相对路径。下面假设该目录是 .github/actions/hello-world-composite-action：

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - uses: actions/checkout@v6
      - id: foo
        uses: ./.github/actions/hello-world-composite-action
        with:
          who-to-greet: 'Mona the Octocat'
      - run: echo random-number "$RANDOM_NUMBER"
        shell: bash
        env:
          RANDOM_NUMBER: ${{ steps.foo.outputs.random-number }}