注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于自定义操作
您可以编写自定义代� �来创建操作,以您喜欢的方式与仓库交互,包括使用 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:
- 创建发行版� �记(例如,
v1.0.2
)之前,在发行版分支(如release/v1
)上创建发行版并进行验证。 - 对于 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 应用程序
GitHub Marketplace 提供用于改进工作流程的工具。 了解每种工具的差异和优势将使您能够选择最适合自己作业的工具。 有关构建应用程序的更多信息,请参阅"关于应用程序。
GitHub Actions 和 GitHub 应用程序的设置
尽管 GitHub Actions 和 GitHub 应用程序 都提供了构建自动化和工作流程工具的方法,但它们各有优点,使其以不同的方式发挥作用。
GitHub 应用程序:
- 持续运行并且能够对事件迅速做出反应。
- 需要持续性数据时效果非常好。
- 适合处理不费时的 API 请求。
- 在您提供的服务器或计算基础架构上运行
GitHub Actions:
- 提供可执行持续集成和持续部署的自动化。
- 可以直接在运行器计算机或 Docker 容器中运行。
- 可以包括访问仓库克隆的权限,使部署和发布工具、代� �� �式化程序和命令行工具能够访问您的代� �。
- 不需要您部署代� �或提供应用程序。
- 具有创建和使用密� �的简单界面,该界面使操作能够与第三方服务进行交互,而� 需存储使用该操作人员的凭据。