查找和自定义操作

概述

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

与你的工作流文件位于同一存储库中
任何公共存储库
Docker Hub 上发布的 Docker 容器映像

GitHub Marketplace 是一个中心位置，你可以在这里找到 GitHub 社区创建的操作。GitHub Marketplace 页面让你能够按类别筛选操作。

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

你可以在存储库的工作流编辑器中直接搜索和浏览操作。从侧边栏，你可以搜索特定操作、查看特色操作并浏览特色类别。你还可以查看操作从 GitHub 社区收到的星级数。

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

将操作添加到工作流

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

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

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

从 GitHub Marketplace 添加操作

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

导航到要在工作流中使用的操作。
单击以查看操作的完整市场列表。
在“安装”下，单击以复制工作流语法。
将语法粘贴为工作流中的新步骤。有关更多信息，请参阅“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 容器映像之前验证 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 操作创建 Dependabot 提醒。有关详细信息，请参阅“GitHub 操作的安全强化”和“关于 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 的基本功能”。