关于自定义操作

操作是您可以组合在一起以创建作业和自定义工作流的单个任务。您可以创建自己的操作，也可以使用和自定义 GitHub 社区共享的操作。

创建操作

学习路径中的第 1 步，共 8 步
下一步：创建 Docker 容器操作

本文内容

关于自定义操作

您可以通过编写自定义代码来创建操作，这些代码可以以您喜欢的任何方式与您的仓库进行交互，包括与 GitHub 的 API 和任何公开可用的第三方 API 集成。例如，操作可以发布 npm 模块，在创建紧急问题时发送短信警报，或部署生产就绪代码。

您可以编写自己的操作以在您的工作流中使用，也可以与 GitHub 社区共享您构建的操作。要与所有人共享您构建的操作，您的仓库必须是公开的。

操作可以在机器上直接运行，也可以在 Docker 容器中运行。您可以定义操作的输入、输出和环境变量。

操作类型

您可以构建 Docker 容器、JavaScript 和复合操作。操作需要一个元数据文件来定义操作的输入、输出和主入口点。元数据文件名必须是 action.yml 或 action.yaml。有关更多信息，请参阅“GitHub Actions 的元数据语法”。

类型LinuxmacOSWindows
Docker 容器
JavaScript
复合操作

Docker 容器操作

Docker 容器将环境与 GitHub Actions 代码打包在一起。这创建了一个更一致、更可靠的工作单元，因为操作的使用者无需担心工具或依赖项。

Docker 容器允许您使用特定版本的操作系统、依赖项、工具和代码。对于必须在特定环境配置中运行的操作，Docker 是一个理想的选择，因为您可以自定义操作系统和工具。由于构建和检索容器的延迟，Docker 容器操作比 JavaScript 操作速度慢。

Docker 容器操作只能在具有 Linux 操作系统的运行器上执行。自托管运行器必须使用 Linux 操作系统并安装 Docker 才能运行 Docker 容器操作。有关自托管运行器要求的更多信息，请参阅“关于自托管运行器”。

JavaScript 操作

JavaScript 操作可以直接在运行器机器上运行，并将操作代码与用于运行代码的环境分开。使用 JavaScript 操作可以简化操作代码，并且执行速度比 Docker 容器操作更快。

为了确保您的 JavaScript 操作与所有 GitHub 托管运行器（Ubuntu、Windows 和 macOS）兼容，您编写的打包 JavaScript 代码应该是纯 JavaScript，并且不依赖于其他二进制文件。JavaScript 操作直接在运行器上运行，并使用运行器镜像中已存在的二进制文件。

如果您正在开发 Node.js 项目，GitHub Actions 工具包提供了一些您可以在项目中使用的包，以加快开发速度。有关更多信息，请参阅 actions/toolkit 存储库。

组合操作

组合操作允许您将多个工作流步骤组合到一个操作中。例如，您可以使用此功能将多个运行命令捆绑到一个操作中，然后让工作流使用该操作将捆绑的命令作为单个步骤执行。要查看示例，请查看“创建组合操作”。

选择操作的位置

如果您正在开发供其他人使用的操作，我们建议将操作保存在其自己的存储库中，而不是将其与其他应用程序代码捆绑在一起。这使您可以像其他任何软件一样对操作进行版本控制、跟踪和发布。

将操作存储在其自己的存储库中，使 GitHub 社区更容易发现操作，缩小了开发人员修复问题和扩展操作的代码库范围，并将操作的版本控制与其他应用程序代码的版本控制分离。

如果您正在构建一个不打算提供给其他人的操作，您可以将操作文件存储在存储库中的任何位置。如果您计划将操作、工作流和应用程序代码组合到一个存储库中，我们建议将操作存储在 .github 目录中。例如，.github/actions/action-a 和 .github/actions/action-b。

与 GitHub Enterprise Server 的兼容性

为了确保您的操作与 GitHub Enterprise Server 兼容，您应该确保您不使用任何硬编码的 GitHub API URL 引用。相反，您应该使用环境变量来引用 GitHub API。

  • 对于 REST API，请使用 GITHUB_API_URL 环境变量。
  • 对于 GraphQL，请使用 GITHUB_GRAPHQL_URL 环境变量。

有关更多信息，请参阅“变量”。

对操作使用发布管理

本节介绍如何使用发布管理以可预测的方式分发操作更新。

发布管理的最佳实践

如果您正在开发供其他人使用的操作，我们建议使用发布管理来控制您如何分发更新。用户可以预期操作的补丁版本将包含必要的关键修复和安全补丁，同时仍与他们现有的工作流兼容。您应该考虑在更改影响兼容性时发布新的主要版本。

在这种发布管理方法下，用户不应引用操作的默认分支，因为它可能包含最新代码，因此可能不稳定。相反，您可以建议您的用户在使用您的操作时指定主要版本，并且只有在遇到问题时才将他们引导到更具体的版本。

要使用特定版本的 Action，用户可以配置其 GitHub Actions 工作流程以定位标签、提交的 SHA 或以发布命名的分支。

使用标签进行版本管理

我们建议使用标签进行 Action 版本管理。使用这种方法，您的用户可以轻松区分主要版本和次要版本。

  • 在创建发布标签（例如，v1.0.2）之前，在发布分支（例如，release/v1）上创建和验证发布。
  • 使用语义版本控制创建发布。有关更多信息，请参阅“在仓库中管理发布”。
  • 将主要版本标签（例如，v1、v2）移动到指向当前发布的 Git ref。有关更多信息，请参阅“Git 基础 - 标签”。
  • 对于会破坏现有工作流程的更改，引入新的主要版本标签（v2）。例如，更改 Action 的输入将是重大更改。
  • 主要版本可以最初使用 beta 标签发布以指示其状态，例如，v2-beta。准备好后，可以删除 -beta 标签。

此示例演示了用户如何引用主要发布标签

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

此示例演示了用户如何引用特定的补丁发布标签

steps:
    - uses: actions/[email protected]

使用分支进行版本管理

如果您更喜欢使用分支名称进行版本管理，此示例演示了如何引用命名分支

steps:
    - uses: actions/javascript-action@v1-beta

使用提交的 SHA 进行版本管理

每个 Git 提交都会收到一个计算出的 SHA 值，该值是唯一且不可变的。您的 Action 用户可能更喜欢依赖提交的 SHA 值，因为这种方法可能比指定标签更可靠，因为标签可能会被删除或移动。但是，这意味着用户将不会收到对 Action 的进一步更新。您必须使用提交的完整 SHA 值，而不是缩写值。

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

为您的操作创建 README 文件

我们建议您创建一个 README 文件，以帮助人们了解如何使用您的操作。您可以在您的 README.md 中包含以下信息：

  • 对操作功能的详细描述
  • 必需的输入和输出参数
  • 可选的输入和输出参数
  • 操作使用的密钥
  • 操作使用的环境变量
  • 在工作流程中使用您的操作的示例

比较 GitHub Actions 和 GitHub Apps

GitHub Marketplace 提供工具来改进您的工作流程。了解每种工具的差异和优势将使您能够为您的工作选择最佳工具。有关构建应用程序的更多信息，请参阅“关于创建 GitHub Apps”。

GitHub Actions 和 GitHub Apps 的优势

虽然 GitHub Actions 和 GitHub Apps 都提供了构建自动化和工作流程工具的方法，但它们各自都有优势，使它们在不同的情况下都很有用。

GitHub Apps

  • 持续运行，可以快速响应事件。
  • 当需要持久数据时，它们非常有效。
  • 最适合不耗时的 API 请求。
  • 在您提供的服务器或计算基础设施上运行。

GitHub Actions

  • 提供可以执行持续集成和持续部署的自动化。
  • 可以在运行器机器上或 Docker 容器中直接运行。
  • 可以包括对您的存储库克隆的访问权限，使部署和发布工具、代码格式化程序和命令行工具能够访问您的代码。
  • 不需要您部署代码或提供应用程序。
  • 有一个简单的界面来创建和使用密钥，这使操作能够与第三方服务交互，而无需存储使用该操作的人员的凭据。

进一步阅读

下一步创建 Docker 容器操作