在工作流中使用预编写的构建模块 - GitHub 文档

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

您可以直接在仓库的工作流编辑器中搜索和浏览操作。通过侧边栏，您可以搜索特定操作、查看精选操作以及浏览精选分类。您还可以看到该操作在 GitHub 社区中获得的星标数量。

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

向工作流添加操作

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

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

您可以在包含工作流的仓库的依赖关系图中，将工作流中引用的 GitHub Actions 操作视为依赖项。欲了解更多信息，请参阅“关于依赖关系图”。

注意

为提升安全性，GitHub Actions 不支持对操作或可重用工作流的重定向。这意味着当操作的所有者、仓库名称或操作名称发生变更时，任何使用旧名称的工作流将会失败。

从 GitHub Marketplace 添加操作

操作的列表页面包含该操作的版本以及使用该操作所需的工作流语法。为了在操作更新后仍保持工作流的稳定性，您可以在工作流文件中指定 Git 或 Docker 标签号来引用要使用的操作版本。

导航至您想在工作流中使用的操作。
点击以查看该操作的完整 Marketplace 列表。
在“Installation”下，点击以复制工作流语法。
将该语法粘贴为工作流中的新步骤。欲了解更多信息，请参阅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@v5
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

action.yml 文件用于提供该操作的元数据。了解此文件的内容，请参阅元数据语法参考。

从不同仓库添加操作

如果操作在与工作流文件不同的仓库中定义，您可以在工作流文件中使用 {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} 语法来引用该操作。为保护您的代码和数据，我们强烈建议您在工作流中使用该容器镜像之前，先验证其完整性。

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

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

在工作流中使用操作的安全加固

GitHub 提供了可用于提升工作流安全性的安全功能。您可以使用 GitHub 的内置功能，以便在所使用的操作出现漏洞时获得通知，或自动保持工作流中操作的最新状态。欲了解更多信息，请参阅安全使用参考。

为自定义操作使用发布管理

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

您将在工作流文件中指定操作的版本。请查阅该操作的文档，了解其发布管理方式，以及使用哪个标签、分支或 SHA 值。

注意

我们建议在使用第三方操作时使用 SHA 值。不过，需要注意的是，Dependabot 仅会对使用语义化版本的有漏洞 GitHub Actions 创建 Dependabot 警报。欲了解更多信息，请参阅安全使用参考和关于 Dependabot 警报。

使用标签

标签可帮助您决定何时在主要和次要版本之间切换，但它们相对短暂，维护者可能会移动或删除。以下示例演示了如何定位已标记为 v1.0.1 的操作。

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

使用 SHA

如果您需要更可靠的版本控制，应使用与该操作版本关联的 SHA 值。SHA 是不可变的，因此比标签或分支更可靠。不过，这种方式意味着您不会自动收到该操作的更新，包括重要的错误修复和安全更新。您必须使用完整的提交 SHA 值，而不是缩写形式。选择 SHA 时，应确认它来自该操作的仓库，而非仓库的分叉。以下示例定位了某操作的 SHA。

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

使用分支

为操作指定目标分支意味着它始终运行该分支当前的版本。如果分支的更新包含破坏性更改，这种方式可能会导致问题。以下示例定位了名为 @main 的分支。

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

欲了解更多信息，请参阅关于自定义操作。

在操作中使用输入和输出

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

要查看操作的输入和输出，请检查仓库根目录中的 action.yml。

在本示例的 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"

在工作流中使用预构建块

本文内容