关于自定义操作

注意：GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

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

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

操作的类型

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

类型	操作系统
Docker 容器	Linux
JavaScript	Linux、macOS、Windows
复合操作	Linux、macOS、Windows

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/actions/action-a 和 .github/actions/action-b。

与 GitHub Enterprise Server 的兼容性

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

对于 REST API，请使用 GITHUB_API_URL 环境变量。
对于 GraphQL，请使用 GITHUB_GRAPHQL_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@172239021f7ba04fe7327647b213799853a9eb89

为操作创建自述文件

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

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

比较 GitHub Actions与 GitHub Apps

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

GitHub Actions 和 GitHub 应用程序的设置

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

GitHub Apps：

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

GitHub Actions：

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

关于自定义操作

本文内容