关于自定义操作

Actions 是您可以组合以创建作业并自定义工作流的单个任务。您可以创建自己的 Actions，或使用和自定义 GitHub 社区共享的 Actions。

创建 Action

学习路径中的第 1 部分（共 8 部分）
下一步:创建 Docker 容器 Action

本文内容

关于自定义 Actions

您可以通过编写与您的存储库以任何您想要的方式交互的自定义代码来创建 Actions，包括与 GitHub 的 API 和任何公开可用的第三方 API 集成。例如，Action 可以发布 npm 模块，在创建紧急问题时发送短信警报，或部署可用于生产的环境代码。

您可以编写自己的 Actions 用于工作流中，或者与 GitHub 社区共享您构建的 Actions。要与所有人共享您构建的 Actions，您的存储库必须是公开的。

Actions 可以直接在机器上或 Docker 容器中运行。您可以定义 Action 的输入、输出和环境变量。

Actions 类型

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

类型LinuxmacOSWindows
Docker 容器
JavaScript
复合 Actions

Docker 容器 Actions

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

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.com 之外的域（例如 GHE.com 或 GitHub Enterprise Server 的自定义域）访问 GitHub。

为了确保你的操作与其他平台兼容，请不要使用任何硬编码的 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 ref。有关更多信息，请参阅“Git 基础 - 标记”。
  • 为会破坏现有工作流程的更改引入新的主要版本标签 (v2)。例如，更改操作的输入将是破坏性更改。
  • 主要版本可以最初使用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 值，该值是唯一且不可变的。你的操作用户可能更喜欢依赖提交的 SHA 值，因为这种方法可能比指定标签更可靠，因为标签可以被删除或移动。但是，这意味着用户将不会收到对操作的进一步更新。你必须使用提交的完整 SHA 值，而不是缩写值。

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

为你的操作创建自述文件

我们建议创建一个自述文件来帮助人们了解如何使用你的操作。你可以在你的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 容器操作