注意:GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。 可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。
概述
可以在工作流中使用预编写的构建基块(称为操作)。 操作是一组预定义的可重用作业或代码,用于在工作流中执行特定任务。
操作可为:
- 可重用:操作可以在不同的工作流和存储库中使用,从而避免重写相同的代码。
- 预编写:GitHub Marketplace 中有许多操作可用,涵盖广泛的任务,如检查代码、设置环境、运行测试和部署应用程序。
- 可配置:可以使用输入、输出和环境变量配置操作,从而满足特定需求。
- 社区驱动:可以创建自己的操作并与其他人共享,或使用社区开发的操作。
在工作流程中使用的操作可以定义于:
- 与工作流文件相同的存储库
- 在同一企业帐户中被配置为允许访问工作流程的内部仓库
- 任何公共仓库
- Docker Hub 上发布的 Docker 容器图像
GitHub Marketplace 是你用来查找 GitHub 社区创建的操作的中心位置。
**注意:**GitHub Enterprise Server 上的 GitHub Actions 对 GitHub.com 或 GitHub Marketplace 上的操作具有有限的访问权限。 有关详细信息,请参阅“管理对 GitHub.com 上操作的访问”并联系 GitHub Enterprise 站点管理员。
从相同仓库添加操作
如果操作在工作流文件使用该操作的同一存储库中定义,你可以在工作流文件中通过 {owner}/{repo}@{ref}
或 ./path/to/dir
语法引用操作。
示例仓库文件结构:
|-- hello-world (repository)
| |__ .github
| └── workflows
| └── my-first-workflow.yml
| └── actions
| |__ hello-world-action
| └── action.yml
路径为相对于 (./
) 默认工作目录(github.workspace
、$GITHUB_WORKSPACE
)的路径。 如果操作将存储库签出到不同于该工作流的位置,则必须更新用于本地操作的相对路径。
示例工作流程文件:
jobs:
my_first_job:
runs-on: ubuntu-latest
steps:
# This step checks out a copy of your repository.
- name: My first step - check out repository
uses: actions/checkout@v4
# This step references the directory that contains the action.
- name: Use local hello-world-action
uses: ./.github/actions/hello-world-action
action.yml
文件用于提供操作的元数据。 若要了解此文件的内容,请参阅“GitHub Actions 的元数据语法”。
从不同仓库添加操作
如果操作在与工作流文件不同的存储库中定义,可在工作流文件中通过 {owner}/{repo}@{ref}
语法引用该操作。
该操作必须存储在公共存储库 或存储在配置为允许访问工作流的内部存储库中。 有关详细信息,请参阅“与企业共享操作和工作流”
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/setup-node@v4
引用 Docker Hub 上的容器
如果操作在 Docker Hub 上发布的 Docker 容器图像中定义,必须在工作流文件中通过 docker://{image}:{tag}
语法引用该操作。 为保护代码和数据,强烈建议先验证 Docker Hub 中 Docker 容器图像的完整性后再将其用于工作流程。
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://alpine:3.8
有关 Docker 操作的一些示例,请参阅 Docker-image.yml 工作流和“创建 Docker 容器操作”。
使用工作流中操作的安全性强化
GitHub 提供了可用于提高工作流安全性的安全功能。 可以使用 GitHub 的内置功能来确保收到有关所用操作中的漏洞的通知,或自动执行使工作流中的操作保持最新状态的过程。 有关详细信息,请参阅“使用 GitHub 的安全功能来保护 GitHub Actions 的使用”。
对自定义操作使用发行版管理
社区操作的创建者可以选择使用标记、分支或 SHA 值来管理操作的版本。 与任何依赖项类似,您应该根据自动接受操作更新的舒适程度来指示要使用的操作版本。
您将在工作流程文件中指定操作的版本。 检查操作的文档,了解其发行版管理方法的信息,并查看要使用的标记、分支或 SHA 值。
注意:建议在使用第三方操作时使用 SHA 值。 但是,请务必注意 Dependabot 只会为使用语义版本控制的易受攻击的 GitHub Actions 创建 Dependabot alerts。 有关详细信息,请参阅“GitHub Actions 的安全强化”和“关于 Dependabot 警报”。
使用标记
标记可用于让您决定何时在主要版本和次要版本之间切换,但这只是临时的,可能被维护员移动或删除。 此示例演示如何定位已标记为 v1.0.1
的操作:
steps:
- uses: actions/javascript-action@v1.0.1
使用 SHA
如果需要更可靠的版本控制,应使用与操作版本关联的 SHA 值。 SHA 是不可变的,因此比标记或分支更可靠。 但是,此方法意味着你不会自动接收操作的更新,包括重要的 Bug 修复和安全更新。 必须使用提交的完整 SHA 值,而不是缩写值。 选择 SHA 时,应验证它是否来自操作的存储库,而不是存储库分支。 此示例以操作的 SHA 为目标:
steps:
- uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f
使用分支
为操作指定目标分支意味着它将始终在该分支上运行当前的版本。 如果对分支的更新包含重大更改,此方法可能会造成问题。 此示例针对名为 @main
的分支:
steps:
- uses: actions/javascript-action@main
有关详细信息,请参阅“关于自定义操作”。
对操作使用输入和输出
操作通常接受或需要输入并生成可以使用的输出。 例如,操作可能要求您指定文件的路径、标签的名称或它将用作操作处理一部分的其他数据。
若要查看操作的输入和输出,请检查存储库根目录中的 action.yml
或 action.yaml
。
在示例 action.yml
中,inputs
关键字定义名为 file-path
的必需输入,并且包括在未指定任何输入时使用的默认值。 outputs
关键字定义名为 results-file
的输出,指示在何处查找结果。
name: "Example"
description: "Receives file and generates output"
inputs:
file-path: # id of input
description: "Path to test script"
required: true
default: "test-file.js"
outputs:
results-file: # id of output
description: "Path to results file"
后续步骤
若要继续了解 GitHub Actions,请参阅“了解 GitHub Actions”。