发布自定义 GitHub 操作

  • 6 分钟

你将在本单元了解为操作选择适当的可见性、记录操作和对其进行版本控制的最佳做法，以及如何将操作发布到 GitHub Marketplace 的相关信息。

选择操作的位置

图示显示了操作的两个可见性选项：公共或专用。

创建操作时，必须首先确定操作位置以及操作的可见性，即是 public 还是 private。 操作的可见性决定了发布该操作所需的建议和要求。 让我们进一步了解一下这两个可见性选项。

公共

任何存储库中的工作流都可以使用公共操作。 如需让正在开发的操作成为开放源代码源或通过 GitHub Marketplace 公开提供，我们建议并在大多数情况要求：该操作拥有自己的存储库，而不是与其他应用代码捆绑在一起。 如此一来，你便可跟踪和发布操作并对其进行版本控制，就像任何其他软件一样。 这样，GitHub 社区便可更轻松地发现操作、缩小开发人员解决问题和扩展操作的基本代码范围，并将操作的版本控制与其他应用代码的版本控制分离。

专用

当某项操作位于专用存储库中时，只有同一存储库中的工作流才能使用该操作。 你可以通过专用操作将操作的文件存储在存储库中的任何位置。 如果计划在单个存储库中合并操作、工作流和应用代码，则建议将操作存储在 .github 目录中。 例如，.github/actions/action-a 和 .github/actions/action-b。

记录操作

如果文档太过含糊或甚至缺失，则新工具或应用使用起来可能会非常麻烦。 请务必在操作中包含清晰文档，以便他人可以了解该操作的原理（无论计划设为公共还是专用）。 首先，请为作创建良好的 README.md 文件。

通常情况下，开发人员首先会查看 README.md 文件，以了解操作原理。 该文件是包含所有重要操作信息的不二之选。 下面是要包含内容的非详尽列表：

  • 操作用途的详细说明。
  • 必需的输入和输出参数。
  • 可选输入和输出参数。
  • 操作使用的密钥。
  • 操作使用的环境变量。
  • 如何在工作流中使用操作的示例。

通常情况下，README.md 文件应包含用户使用该操作时应该知道的一切内容。 如果你认为这些信息可能是有用信息，请将其纳入 README.md 中。

发布操作和对其进行版本控制

如果你正在开发一项操作，以供他人使用，而不考虑其为公共还是专用，则应制定发布管理策略，以便控制更新的分发方式。 主要版本更新包括会影响兼容性的必要关键修补程序和安全修补程序，需予以清晰记录。

发布管理和对其进行版本控制的优良做法

完善的发布管理策略应包括版本控制建议。 用户不应使用作引用作的默认分支。 这是因为可能包含最新代码（可能或可能不稳定）的默认分支可能会导致工作流中断。 相反，我们建议用户在使用操作时指定主要版本，并仅在遇到问题时将其定向到更具体的版本。 为此，可将其 GitHub Actions 工作流配置为面向某个标记、提交的 SHA 或为发布指定的特定分支。 下面将更详细地介绍这些发布选项。

标记

标记可能是管理操作发布的好方法。 通过使用标记，用户可以轻松区分主要版本和次要版本。 以下是创建发布时可以考虑的有用做法列表：

  • 创建发布标记（例如 release/v1）之前，创建并验证发布分支上的发布（例如 v1.0.2）。
  • 使用语义化版本控制。
  • 移动主要版本标记（例如 v1、v2），以指向当前发布的 Git 引用。
  • 针对破坏现有工作流的更改引入新的主要版本标记 (v2)。
  • 发布带有 beta 标记的主要版本来指示其状态，例如 v2-beta。 可以在发布就绪时删除 -beta 标记。

下面是每个选项的一些示例。

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

使用提交的 SHA

标记不仅有用，而且被广泛使用，但使用标记的一个缺点是标记可被删除或移动。 使用 Git 时，每个提交都会收到一个计算的 SHA 值，该值是唯一且无法修改的。 使用提交 SHA 进行版本控制将为你提供最可靠、最安全的方法来使用操作和对其进行版本控制。 但在 Git 中，通常可以将 SHA 哈希代码缩写为前几个字符，并且 Git 将可以识别引用。 如果使用提交的 SHA 进行发布管理，则需要使用完整的 SHA 值，而非缩写值。

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

将操作发布到 GitHub Marketplace

图片显示了用于构建和改进工作流的 GitHub Marketplace 工具。

在准备好与 GitHub 社区共享你的操作时，可以将其发布到 GitHub Marketplace，并与数百万个 GitHub 用户联系。 如果符合所有要求，发布到 GitHub Marketplace 的操作会立即发布。 不符合要求的操作将需要在发布之前接受 GitHub 评审。 你需要确保存储库仅包含操作所需的元数据文件、代码和文件。 为操作创建单个仓库允许您在单一单元中标记、发布和打包代码。 GitHub 还使用 GitHub Marketplace 页面上的操作元数据。

下面是将操作发布到 GitHub Marketplace 的要求。 这些要求适用于基于 Docker 容器的操作和基于 JavaScript 的操作：

  • 操作必须位于公共存储库中。
  • 每个存储库必须仅包含一项操作。
  • 操作的元数据文件（action.yml 或 action.yaml）必须位于存储库的根目录中。
  • 在 GitHub Marketplace 上，操作的元数据文件中的 name 必须是唯一的。
    • 名称无法与 GitHub 上的用户或组织匹配，除非该用户或组织所有者正在发布操作。 例如，只有 GitHub 组织可以发布名为 github 的操作。
    • name 无法与现有 GitHub Marketplace 类别匹配。
    • name 无法与现有 GitHub 功能匹配。

你可以将已创建的操作添加到 GitHub Marketplace，方法是将其标记为新版本，然后再行发布。 GitHub 中提供了几个指导步骤，你可以按照这些步骤来发布操作版本。 有关这些步骤的详细信息，请参阅本模块末尾的总结部分。