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

概述

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

操作可为：

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

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

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

GitHub Marketplace 是你用来查找 GitHub 社区创建的操作的中心位置。利用GitHub Marketplace 页面页面可按类别筛选操作。

在工作流程编辑器中浏览 Marketplace 操作

您可以直接在仓库的工作流程编辑器中搜索和浏览操作。从边栏可以搜索特定的操作、查看特色操作和浏览特色类别。您也可以查看操作从 GitHub 社区获得的星标数。

在仓库中，浏览至要编辑的工作流程文件。
若要打开工作流编辑器，请在文件视图右上角单击。
在编辑器右侧，使用 GitHub Marketplace 边栏浏览操作。带有徽章的操作指示 GitHub 已验证操作的创建者为合作伙伴组织。

添加操作到工作流程

您可以通过在工作流程文件中引用操作来向工作流程添加操作。

您可以将 GitHub Actions 工作流程中引用的操作视为包含工作流程的仓库依赖图中的依赖项。有关详细信息，请参阅“关于依赖项关系图”。

注意：为了增强安全性，GitHub Actions 不支持对操作或可重用工作流进行重定向。这意味着，当所有者、操作存储库的名称或操作名称发生更改时，使用该操作并具有先前名称的任何工作流都将失败。

从 GitHub Marketplace 添加操作

操作的列表页包括操作的版本以及使用操作所需的工作流程语法。为使工作流程在操作有更新时也保持稳定，您可以在工作流程文件中指定 Git 或 Docker 标记号以引用所用操作的版本。

导航到要在工作流程中使用的操作。
单击以查看操作的完整市场列表。
在“安装”下，单击“”，复制工作流语法。
将语法粘贴为工作流程中的新步骤。有关详细信息，请参阅“GitHub Actions 的工作流语法”。
如果操作要求您提供输入，请将其设置在工作流程中。有关操作可能需要的输入的信息，请参阅“在工作流中使用预编写的构建基块”。

您也可以为添加到工作流程的操作启用 Dependabot version updates。有关详细信息，请参阅“使用 Dependabot 保持操作的最新状态”。

从相同仓库添加操作

如果操作在工作流文件使用该操作的同一存储库中定义，你可以在工作流文件中通过 {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

引用 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 值。

注意：建议在使用第三方操作时使用 SHA 值。但是，请务必注意 Dependabot 只会为使用语义版本控制的易受攻击的 GitHub Actions 创建 Dependabot alerts。有关详细信息，请参阅“GitHub Actions 的安全强化”和“关于 Dependabot 警报”。

使用标记

标记可用于让您决定何时在主要版本和次要版本之间切换，但这只是临时的，可能被维护员移动或删除。此示例演示如何定位已标记为 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”。

本文内容