在工作流中使用预写构建块 - GitHub Docs

概述

您可以在工作流中使用称为操作的预先编写的构建块。操作是在工作流中执行特定任务的预定义、可重用的作业或代码集。

操作可以是

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

您在工作流中使用的操作可以在以下位置定义

与工作流文件相同的存储库
任何公共存储库
Docker Hub 上发布的 Docker 容器镜像

GitHub Marketplace 是一个中心位置，您可以在其中找到 GitHub 社区创建的操作。 GitHub Marketplace 页面允许您按类别筛选操作。

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

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

在您的存储库中，浏览到您要编辑的工作流文件。
在文件视图的右上角，单击以打开工作流编辑器。.
在编辑器的右侧，使用 GitHub Marketplace 侧边栏浏览操作。带有徽章的操作表示 GitHub 已验证操作创建者为合作伙伴组织。

将操作添加到您的工作流

您可以通过在工作流文件中引用操作来将其添加到工作流。

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

注意

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

从 GitHub Marketplace 添加操作

操作的列表页面包含操作的版本以及使用该操作所需的工作流语法。为了使您的工作流即使在对操作进行更新时也能保持稳定，您可以通过在工作流文件中指定 Git 或 Docker 标记号来引用要使用的操作版本。

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

您还可以为添加到工作流的操作启用 Dependabot 版本更新。有关详细信息，请参阅“使用 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 容器镜像用于工作流之前验证其完整性。

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 警报。有关详细信息，请参阅“GitHub Actions 的安全强化”和“关于 Dependabot 警报。”

使用标签

标签有助于让您决定何时在主要版本和次要版本之间切换，但这些标签更易变，维护人员可以移动或删除它们。此示例演示了如何定位标记为 v1.0.1 的操作。

steps:
  - uses: actions/[email protected]

使用 SHA

如果您需要更可靠的版本控制，则应使用与操作版本关联的 SHA 值。SHA 是不可变的，因此比标签或分支更可靠。但是，此方法意味着您不会自动接收操作的更新，包括重要的错误修复和安全更新。您必须使用提交的完整 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”。

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

本文内容