在工作流中使用预编写的构建基块

概述

可以在工作流中使用预编写的构建基块（称为操作）。 操作是一组预定义的可重用作业或代码，用于在工作流中执行特定任务。

操作可为：

• 可重用：操作可以在不同的工作流和存储库中使用，从而避免重写相同的代码。
• 预编写：GitHub Marketplace 中有许多操作可用，涵盖广泛的任务，如检查代码、设置环境、运行测试和部署应用程序。
• 可配置：可以使用输入、输出和环境变量配置操作，从而满足特定需求。
• 社区驱动：可以创建自己的操作并与其他人共享，或使用社区开发的操作。

在工作流程中使用的操作可以定义于：

• 与工作流文件相同的存储库
• 在同一企业帐户中被配置为允许访问工作流程的内部仓库
• 任何公共仓库
• Docker Hub 上发布的 Docker 容器图像

GitHub Marketplace 是你用来查找 GitHub 社区创建的操作的中心位置。

从相同仓库添加操作

如果操作在工作流文件使用该操作的同一存储库中定义，你可以在工作流文件中通过 {owner}/{repo}@{ref} 或 ./path/to/dir 语法引用操作。

示例仓库文件结构：

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

路径为相对于 (./) 默认工作目录（github.workspace、$GITHUB_WORKSPACE）的路径。 如果操作将存储库签出到不同于该工作流的位置，则必须更新用于本地操作的相对路径。

示例工作流程文件：

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

action.yml 文件用于提供操作的元数据。 在“GitHub Actions 的元数据语法”中了解此文件的内容。

从不同仓库添加操作

如果操作在与工作流文件不同的存储库中定义，可在工作流文件中通过 {owner}/{repo}@{ref} 语法引用该操作。

该操作必须存储在公共存储库 或存储在配置为允许访问工作流的内部存储库中。 有关详细信息，请参阅“与企业共享操作和工作流”

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

如果企业所有者已启用对 GitHub.com 上的操作的访问，那么你可使用此语法引用你的企业或 GitHub.com 上的操作。 GitHub Actions 将首先查找企业中的操作，然后回退到 GitHub.com。

引用 Docker Hub 上的容器

如果操作在 Docker Hub 上发布的 Docker 容器图像中定义，必须在工作流文件中通过 docker://{image}:{tag} 语法引用该操作。 为保护代码和数据，强烈建议先验证 Docker Hub 中 Docker 容器图像的完整性后再将其用于工作流程。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

有关 Docker 操作的一些示例，请参阅“Docker-image.yml 工作流”和“创建 Docker 容器操作”。

使用工作流中操作的安全性强化

GitHub 提供了可用于提高工作流安全性的安全功能。 可以使用 GitHub 的内置功能来确保收到有关所用操作中的漏洞的通知，或自动执行使工作流中的操作保持最新状态的过程。 有关详细信息，请参阅“使用 GitHub 的安全功能来保护 GitHub Actions 的使用”。

对自定义操作使用发行版管理

社区操作的创建者可以选择使用标记、分支或 SHA 值来管理操作的版本。 与任何依赖项类似，您应该根据自动接受操作更新的舒适程度来指示要使用的操作版本。

您将在工作流程文件中指定操作的版本。 检查操作的文档，了解其发行版管理方法的信息，并查看要使用的标记、分支或 SHA 值。

使用标记

标记可用于让您决定何时在主要版本和次要版本之间切换，但这只是临时的，可能被维护员移动或删除。 此示例演示如何定位已标记为 v1.0.1 的操作：

steps:
  - uses: actions/javascript-action@v1.0.1

使用 SHA

如果需要更可靠的版本控制，应使用与操作版本关联的 SHA 值。 SHA 是不可变的，因此比标记或分支更可靠。 但是，此方法意味着你不会自动接收操作的更新，包括重要的 Bug 修复和安全更新。 必须使用提交的完整 SHA 值，而不是缩写值。 选择 SHA 时，应验证它是否来自操作的存储库，而不是存储库分支。 此示例以操作的 SHA 为目标：

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

使用分支

为操作指定目标分支意味着它将始终在该分支上运行当前的版本。 如果对分支的更新包含重大更改，此方法可能会造成问题。 此示例针对名为 @main 的分支：

steps:
  - uses: actions/javascript-action@main

有关详细信息，请参阅“关于自定义操作”。

对操作使用输入和输出

操作通常接受或需要输入并生成可以使用的输出。 例如，操作可能要求您指定文件的路径、标签的名称或它将用作操作处理一部分的其他数据。

若要查看操作的输入和输出，请检查存储库根目录中的 action.yml 或 action.yaml。

在示例 action.yml 中，inputs 关键字定义名为 file-path 的必需输入，并且包括在未指定任何输入时使用的默认值。 outputs 关键字定义名为 results-file 的输出，指示在何处查找结果。

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

后续步骤

若要继续了解 GitHub Actions，请参阅“了解 GitHub Actions”。