关于自定义操作

关于自定义操作

您可以编写自定义代码来创建操作，以您喜欢的方式与仓库交互，包括使用 GitHub 的 API 以及任何公开的第三方 API 进行交互。 例如，操作可以发布 npm 模块、在创建紧急问题时发送短信提醒，或者部署可用于生产的代码。

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

操作的类型

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

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 Actions 工作流。 有关详细信息，请参阅“与企业共享操作和工作流”。

您可以将操作的文件存储在您的仓库中的任何位置。 如果计划将操作、工作流和应用程序代码合并到一个存储库中，建议将操作存储在 .github 目录中。 例如，.github/actions/action-a 和 .github/actions/action-b。

确保与其他平台的兼容性

许多人在 GitHub.com 之外的域中访问 GitHub，例如 GHE.com 或 GitHub Enterprise Server 的自定义域。

若要确保操作与其他平台兼容，请勿使用对 API URL 的任何硬编码引用，例如 https://api.github.com。 转而，你可以：

• 使用环境变量（请参阅“在变量中存储信息”）：

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

• 使用 @actions/github 等工具包，它可自动设置正确的 URL。

针对操作使用发布管理

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

发行版管理的良好做法

如果您正在开发供其他人使用的操作，建议使用发行版管理来控制分发更新的方式。 用户期望操作的补丁版本包括必要的关键修补程序和安全补丁，同时仍与其现有工作流程保持兼容。 每当更改影响兼容性时，应考虑发布新的主要版本。

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

要使用特定的操作版本，用户可以配置其 GitHub Actions 工作流程定向标记、 提交的 SHA 或为发行版指定的分支。

使用标记进行发行版管理

建议使用标记进行操作发行版管理。 使用这种方法，您的用户可以轻松地区分主要和次要版本：

• 创建发布标记（例如 v1.0.2）之前，创建并验证发布分支上的发布（例如 release/v1）。
• 使用语义版本管理创建发行版。 有关详细信息，请参阅“管理仓库中的发行版”。
• 移动主要版本标记（例如 v1、v2），以指向当前发布的 Git 引用。 有关详细信息，请参阅“Git 基础知识 - 标记“。
• 针对破坏现有工作流的更改引入新的主要版本标记 (v2)。 例如，更改操作的输入就是破坏性的更改。
• 主要版本最初发布时可以使用 beta 标记来指示其状态，例如 v2-beta。 准备就绪后，可以删除 -beta 标记。

此示例演示用户如何引用主要发行版标记：

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

此示例演示用户如何引用特定补丁发行版标记：

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

使用分支进行发行版管理

如果希望使用分支名称进行发行版管理，此示例演示如何引用指定的分支：

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

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

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

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

为操作创建自述文件

如果计划公开分享您的操作，建议创建自述文件以帮助人们了解如何使用您的操作。 可以将此信息包含在 README.md 中：

• 操作的详细描述
• 必要的输入和输出变量
• 可选的输入和输出变量
• 操作使用的密码
• 操作使用的环境变量
• 如何在工作流程中使用操作的示例

比较 GitHub Actions与 GitHub Apps

GitHub Marketplace 提供用于改进工作流程的工具。 了解每种工具的差异和优势将使您能够选择最适合自己作业的工具。 有关构建应用的详细信息，请参阅“关于创建 GitHub 应用”。

GitHub Actions 和 GitHub 应用程序的设置

尽管 GitHub Actions 和 GitHub Apps 都提供了构建自动化和工作流程工具的方法，但它们各有优点，使其以不同的方式发挥作用。

GitHub Apps：

• 持续运行并且能够对事件迅速做出反应。
• 需要持续性数据时效果非常好。
• 适合处理不费时的 API 请求。
• 在您提供的服务器或计算基础架构上运行

GitHub Actions：

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

延伸阅读

• “GitHub Actions 的工作流命令”