我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

关于操作

操作是可以组合来创建作业和自定义工作流程的单个任务。 您可以创建自己的操作,以及使用和自定义 GitHub 社区分享的操作。

GitHub 操作 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub 操作 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 更多信息请参阅“GitHub 的产品”。

本文内容

关于操作

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

您可以编写自己的操作以用于工作流程,或者与 GitHub 社区共享您创建的操作。 要共享您创建的操作,您的仓库必须是公共的。

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

操作类型

您可以创建 Docker 容器和 JavaScript 操作。 操作需要元数据文件来定义操作的输入、输出和主要进入点。 元数据文件名必须是 action.ymlaction.yaml。 更多信息请参阅“GitHub 操作 的元数据语法”。

类型操作系统
Docker 容器Linux
JavaScriptLinux、MacOS、Windows

Docker 容器操作

Docker 容器使用 GitHub 操作 代码封装环境。 这会创建更加一致、可靠的工作单位,因为操作的使用者不需要担心工具或依赖项。

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

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

JavaScript 操作

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

要确保您的 JavaScript 操作与所有 GitHub 托管的运行器(Ubuntu、Windows 和 macOS)兼容,您编写的封装 JavaScript 代码应该是纯粹的 JavaScript,不能依赖于其他二进制文件。 JavaScript 操作直接在运行器上运行,并使用虚拟环境中已存在的二进制文件。

自托管运行器必须安装 Node.js 才能运行 JavaScript 操作。 有关自托管运行器要求的更多信息,请参阅“关于自托管运行器”。

如果您正在开发 Node.js 项目,GitHub 操作 工具包提供可用于项目中加速开发的软件包。 更多信息请参阅 actions/toolkit 仓库。

选择操作的位置

如果是开发供其他人使用的操作,我们建议将该操作保持在其自己的仓库中,而不是与其他应用程序代码一起捆绑。 这可让您管理操作版本以及跟踪和发行操作,就像任何其他软件一样。

将操作存储在其自己的仓库中更便于 GitHub 社区发现操作,缩小代码库范围以便开发者修复问题和扩展操作,以及从其他应用程序代码的版本解耦操作的版本。

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

为操作使用发行版管理

This section explains how you can use release management to distribute updates to your actions in a predictable way.

Good practices for release management

If you're developing an action for other people to use, we recommend using release management to control how you distribute updates. Users can expect an action's major version to include necessary critical fixes and security patches, while still remaining compatible with their existing workflows. You should consider releasing a new major version whenever your changes affect compatibility.

Under this release management approach, users should not be referencing an action's master branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues.

To use a specific action version, users can configure their GitHub 操作 workflow to target a tag, a commit's SHA, or a branch named for a release.

Using tags for release management

We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions:

  • Create and validate a release on a release branch (such as release/v1) before creating the release tag (for example, v1.0.2).
  • Create a release using semantic versioning. 更多信息请参阅“创建发行版”。
  • Move the major version tag (such as v1, v2) to point to the Git ref of the current release. 更多信息请参阅“Git 基本信息 - 标记”。
  • Introduce a new major version tag (v2) for changes that will break existing workflows. 例如,更改操作的输入就是破坏性的更改。
  • Major versions can be initially released with a beta tag to indicate their status, for example, v2-beta. The -beta tag can then be removed when ready.

This example demonstrates how a user can reference a major release tag:

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

This example demonstrates how a user can reference a specific patch release tag:

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

Using branches for release management

If you prefer to use branch names for release management, this example demonstrates how to reference a named branch:

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

Using a commit's SHA for release management

Each Git commit receives a calculated SHA value, which is unique and immutable. Your action's users might prefer to rely on a commit's SHA value, as this approach can be more reliable than specifying a tag, which could be deleted or moved. However, this means that users will not receive further updates made to the action. Using a commit's full SHA value instead of the abbreviated value can help prevent people from using a malicious commit that uses the same abbreviation.

steps:
    - uses: actions/javascript-action@172239021f7ba04fe7327647b213799853a9eb89

为操作创建自述文件

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

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

比较 GitHub 操作与 GitHub 应用程序

GitHub Marketplace 提供用于改进工作流程的工具。 了解每种工具的差异和优势将使您能够选择最适合自己作业的工具。 有关构建操作和应用的更多信息,请参阅 GitHub 开发者文档中的“关于 GitHub 操作”和“关于应用程序”。

GitHub 操作和 GitHub 应用程序的设置

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

GitHub 应用程序:

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

GitHub 操作:

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

延伸阅读

问问别人

找不到要找的内容?

联系我们