通过使用可重用工作流/组合动作来重用 GitHub Actions 的处理

有两种大致的方法可以重新利用自己编写的 GitHub Actions 处理：

1. 方法一：把自己编写的 GitHub Actions 处理存储到一个可重复使用的模块中，以便其他项目可以轻松引用和调用该模块。

2. 方法二：将自己编写的 GitHub Actions 处理转化为一个独立的工具或插件，让其他项目可以通过安装和配置该工具或插件来实现相同的功能。

• Reusable workflows

 

Composite action

由于 GitHub Actions 的 yaml 文件会变得庞大且难以阅读和维护，所以为了保持一个和平的环境，必须努力保持适度的大小，并进行适当的模块分解和重用。我今年遇到了类似的情况，因此我把它整理成了一篇文章。

“重新使用的工作流是什么？”

 

根据语言的常规，这是可重复使用的工作流。为了防止在每个存储库中填写 GitHub Actions 的定义，并且因此产生了冗长的和散落在各处的代码，导致了复制粘贴的混乱，我们希望将共同的定义拆分出来并外部调用。为此，我们有了可重复使用的工作流机制。

经历了一些规范和环境的变迁之后，从现在开始（2022年12月之后），可以调用存放在另一个私有仓库中的操作。本文档基于这个情况进行描述。

可重复使用的工作流设置

代码库

需要对用于设置 GitHub Actions 文件的可重用工作流程存储库进行以下配置。
如果没有进行这些配置，则无法调用 Actions。

将 GitHub Actions 的访问设置更改为可以在~中的存储库访问。

https://github.com/(组织名)/(仓库名)/设置/操作

您可以从通过上述URL访问的设置界面中进行设置。

默认情况下，”Access”的设置为”Not accessible”，所以我们将其更改为在”xxxxxx”组织的存储库中可访问。

Github Actions 文件

必须根据可重复使用工作流的规范来描述Actions文件。

• .github/workflows 配下に設置する必要がある

サブディレクトリの作成も基本的に不可

呼び出しの定義として on: workflow_call: の定義を必ずつける必要がある

on:
  workflow_call:

• その他、Reusable workflows の詳細な仕様については公式ドキュメントを参照ください

https://docs.github.com/ja/actions/using-workflows/reusing-workflows

记述的示例

以下是一个示例，展示了如何在 GitHub Actions 的 Lint 工具 actionlint 中执行可重复使用的工作流程。

on:
  workflow_call:
    inputs:
      os:
        default: ubuntu-latest
        required: false
        type: string

jobs:
  actionlint:
    runs-on: ${{ inputs.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Run actionlint
        shell: bash
        run: |
          bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
          ./actionlint -color

为了使用可重复的工作流程，您需要提供 on: workflow_call指令，这样就可以在通过输入指定的操作系统环境（默认为 ubuntu-latest）上运行 rhysd/actionlint。

调用可复用的工作流

描述示例

假设上述适用于 actionslint 的可重复工作流文件被放置在 (机构)/github-actions/.github/workflows/actionlint.yml 中，您可以通过以下方式进行调用。

name: Actionlint
on:
  pull_request:

jobs:
  actionlint:
    uses: (organization)/github-actions/.github/workflows/actionlint.yml@main

使用“には”，以以下的格式指定要调用的 Actions 文件。

（组织/仓库）/ .github / workflows / （可重用工作流文件）@（分支名称）

如果要向可重复使用的工作流程传递值，可以使用`with`或`secrets`等指定传递。

可以以这种方式将在各个地方实施的共同处理作为可以重用的工作流剥离出来。
Reusable workflows 是早就存在的功能，但从2023年（2022年12月至今）的主题来看，我认为其重要之处在于可以调用其他放置在私有仓库中的工作流，从而提高了其便利性。

什么是复合动作？

 

可以这样来解释，它是指将由多个步骤组成的过程进行分割，并将其转换为可重复使用的 Action。

与可重复使用的工作流程类似，您现在可以调用存放在另一个私有存储库中的操作。本文档是在此情况下撰写的。

另外，我认为可以将 可重复利用的工作流与复合操作的区别归纳如下。

• Reusable workflows: workflow の処理を切り出して再利用化できる。

 

Composite action: 複数の step の処理を切り出して再利用化できる。

设置综合动作

Github Actions 文件

需要根据 Composite Action 的规范来描述 Actions 文件。

呼び出しの定義として runs: using:composite の定義を必ずつける必要がある

runs:
  using: composite

• Reusable workflow と異なり、Composite action は所定のディレクトリを作成し、その中に単一もしくは複数の Action 定義 yaml を設置する形になる。

 

Composite action へ値を渡す時は Composite action 側で inputs を定義する。

inputs:
  some_value:
    required: true

• Reusable workflow と異なり、Composite action では secrets を指定することはできない

その他、Composite actions の仕様については公式ドキュメントを参照ください

https://docs.github.com/ja/actions/creating-actions/creating-a-composite-action

规范（组织特定的）

这是我们组织的特定情况，但相关的 Composite action 文件将放置在 .github/composite 目录下。

这个原因是因为目前 actionlint 不支持 Composite action 格式，如果让 actionlint 加载这些文件，就会出错。

 

由于想要将.github/workflows作为actionlint的目标，因此我们采取了上述操作作为解决方案。

描述示例

举例来说，我们可以初始化Terraform环境并执行计划的复合操作。

name: terraform-plan
description: terraform-plan
inputs:
  terraform_version:
    required: true
runs:
  using: composite
  steps:
    - name: setup terraform
      uses: hashicorp/setup-terraform@v2
      with:
        terraform_version: ${{ inputs.terraform_version }}

    - name: terraform fmt
      id: fmt
      shell: bash
      run: terraform fmt -check

    - name: terraform init
      id: init
      shell: bash
      run: terraform init

    - name: terraform validate
      id: validate
      shell: bash
      run: terraform validate -no-color

    - name: terraform plan
      id: plan
      shell: bash
      run: terraform plan -no-color

我已安装terraform，并执行了以下命令。

• terraform fmt

 

• terraform init

 

• terraform validate

 

terraform plan

调用复合动作

描述实例

如果以 Terraform 相关的 Composite Action 举例，那么在调用者方面，可以使用以下描述进行调用。

      - name: terraform plan
        uses: (organization)/github-actions/.github/composite/terraform-plan@main
        with:
          terraform_version: 1.6.5

请以以下的格式指定要调用的 Actions 文件。

（组织）/（仓库）/ .github/composite/（组合操作目录）@(分支名)

在传递值给Composite action时，一个重要的注意事项是要使用with进行传递。原因是因为在当前情况下，secrets在Composite action中尚不受支持，所以只能通过with实现值传递。

 

目前为止，在公司内部还没有遇到需要进行如此安全的值交换的要求，但我觉得拒绝采用上述规范并选择不使用复合动作的选择也是可能的。