关于上下文
上下文是一种访问工作流程运行、运行器环境、作业及步骤相关信息的方式。 每个上下文都是一个包含属性的对象,属性可以是字符串或其他对象。
Contexts, objects, and properties will vary significantly under different workflow run conditions. 例如,matrix
上下文中仅填充 matrix 中的作业。
您可以使用表达式语法访问上下文。 更多信息请参阅“表达式”。
${{ <context> }}
警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
上下文名称 | 类型 | 描述 |
---|---|---|
github | 对象 | 工作流程运行的相关信息。 更多信息请参阅 github 上下文。 |
env | 对象 | 包含工作流程、作业或步骤中设置的环境变量。 更多信息请参阅 env 上下文。 |
job | 对象 | 有关当前运行的作业的信息。 更多信息请参阅 job 上下文。 |
steps | 对象 | 有关当前作业中已运行的步骤的信息。 更多信息请参阅 steps 上下文。 |
runner | 对象 | 运行当前作业的运行程序相关信息。 更多信息请参阅 runner 上下文。 |
secrets | 对象 | 包含可用于工作流程运行的机密的名称和值。 更多信息请参阅 secrets 上下文。 |
strategy | 对象 | 有关当前作业的矩阵执行策略的信息。 更多信息请参阅 strategy 上下文。 |
matrix | 对象 | 包含在工作流程中定义的应用于当前作业的矩阵属性。 更多信息请参阅 matrix 上下文。 |
needs | 对象 | 包含定义为当前作业依赖项的所有作业的输出。 更多信息请参阅 needs 上下文。 |
inputs | object | 包含可重用工作流的输入。 更多信息请参阅 inputs 上下文。 |
作为表达式的一部分,您可以使用以下两种语法之一访问上下文信息。
- 索引语法:
github['sha']
- 属性解除参考语法:
github.sha
要使用属性解除参考语法,属性名称必须:
- 以
a-Z
或_
开头。 - 后跟
a-Z
0-9
-
或_
。
如果尝试取消引用不存在的属性,则该属性的计算结果将为空字符串。
确定何时使用上下文
GitHub Actions 包含一个称为上下文的变量集和一个称为默认环境变量的类似变量集。 这些变量预期用于工作流程中的不同点:
- 默认环境变量:这些变量仅存在于执行作业的运行器上。 更多信息请参阅“默认环境变量”。
- 上下文:您可以在工作流程的任何时候使用大多数上下文,包括当默认环境变量不可用时。 例如,您可以使用带表达式的上下文执行初始处理,然后将作业路由到运行器以供执行;这允许您使用带有条件
if
关键字的上下文来确定步骤是否应运行。 作业运行后,您还可以从执行作业的运行器(如runner.os
)检索上下文变量。 有关您可以在工作流程中使用各种上下文的详细信息,请参阅“上下文可用性”。
下面的示例演示了这些不同类型的环境变量如何在一个作业中一起使用:
name: CI
on: push
jobs:
prod-check:
if: ${{ github.ref == 'refs/heads/main' }}
runs-on: ubuntu-latest
steps:
- run: echo "Deploying to production server on branch $GITHUB_REF"
在此示例中,if
语句检查 github.ref
上下文以确定当前分支名称;如果名称是 refs/heads/main
,则执行后续步骤。 if
检查由 GitHub Actions 处理,作业仅在结果为 true
时才发送到运行器。 作业发送到运行器后, 该步骤将执行并引用运行器的 $GITHUB_REF
环境变量。
上下文可用性
在整个工作流程运行过程中,提供不同的上下文。 例如,secrets
上下文只能用于作业中的某些地方。
此外,某些功能只能在某些地方使用。 例如, hashFiles
函数无法随处可用。
下表列出了工作流程中每一个上下文和特殊函数可以使用的地方。 除非下面列出,否则可以在任何地方使用函数。 |
| 工作流程键 | 上下文 | 特殊函数 |
| -------------------------- | -------------------------- | -------------------------- |
| concurrency
| github, inputs
| |
| env
| github, secrets, inputs
| |
| jobs.<job_id>.concurrency
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.container
| github, needs, strategy, matrix, env, secrets, inputs
| |
| jobs.<job_id>.container.credentials
| github, needs, strategy, matrix, env, secrets, inputs
| |
| jobs.<job_id>.container.env.<env_id>
| github, needs, strategy, matrix, job, runner, env, secrets, inputs
| |
| jobs.<job_id>.continue-on-error
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.defaults.run
| github, needs, strategy, matrix, env, inputs
| |
| jobs.<job_id>.env
| github, needs, strategy, matrix, secrets, inputs
| |
| jobs.<job_id>.environment
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.environment.url
| github, needs, strategy, matrix, job, runner, env, steps, inputs
| |
| jobs.<job_id>.if
| github, needs, inputs
| always, cancelled, success, failure
|
| jobs.<job_id>.name
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.outputs.<output_id>
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| |
| jobs.<job_id>.runs-on
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.secrets.<secrets_id>
| github, needs, secrets
| |
| jobs.<job_id>.services
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.services.<service_id>.credentials
| github, needs, strategy, matrix, env, secrets, inputs
| |
| jobs.<job_id>.services.<service_id>.env.<env_id>
| github, needs, strategy, matrix, job, runner, env, secrets, inputs
| |
| jobs.<job_id>.steps.continue-on-error
| github, needs, strategy, matrix, job, runner, env, secrets, steps
| hashFiles
|
| jobs.<job_id>.steps.env
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| hashFiles
|
| jobs.<job_id>.steps.if
| github, needs, strategy, matrix, job, runner, env, steps, inputs
| always, cancelled, success, failure, hashFiles
|
| jobs.<job_id>.steps.name
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| hashFiles
|
| jobs.<job_id>.steps.run
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| hashFiles
|
| jobs.<job_id>.steps.timeout-minutes
| github, needs, strategy, matrix, job, runner, env, secrets, steps
| hashFiles
|
| jobs.<job_id>.steps.with
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| hashFiles
|
| jobs.<job_id>.steps.working-directory
| github, needs, strategy, matrix, job, runner, env, secrets, steps, inputs
| hashFiles
|
| jobs.<job_id>.strategy
| github, needs, inputs
| |
| jobs.<job_id>.timeout-minutes
| github, needs, strategy, matrix, inputs
| |
| jobs.<job_id>.with.<with_id>
| github, needs
| |
| on.workflow_call.inputs.<inputs_id>.default
| github
| |
| on.workflow_call.outputs.<output_id>.value
| github, jobs, inputs
| |
示例:将上下文信息打印到日志
您可以将上下文的内容打印到日志中进行调试。 需要 toJSON
函数才能将 JSON 对象打印到日志中。
警告:在使用整个 github
上下文时,请注意其中包括诸如 github.token
等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。
name: Context testing
on: push
jobs:
dump_contexts_to_log:
runs-on: ubuntu-latest
steps:
- name: Dump GitHub context
id: github_context_step
run: echo '${{ toJSON(github) }}'
- name: Dump job context
run: echo '${{ toJSON(job) }}'
- name: Dump steps context
run: echo '${{ toJSON(steps) }}'
- name: Dump runner context
run: echo '${{ toJSON(runner) }}'
- name: Dump strategy context
run: echo '${{ toJSON(strategy) }}'
- name: Dump matrix context
run: echo '${{ toJSON(matrix) }}'
github
上下文
github
上下文包含有关工作流程运行以及触发运行的事件相关信息。 您还可以读取环境变量中的大多数 github
上下文数据。 有关环境变量的更多信息,请参阅“使用环境变量”。
警告:在使用整个 github
上下文时,请注意其中包括诸如 github.token
等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。
警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
属性名称 | 类型 | 描述 |
---|---|---|
github | 对象 | 工作流程中任何作业或步骤期间可用的顶层上下文。 此对象包含下面列出的所有属性。 |
github.action | 字符串 | 当前运行的操作的名称,或步骤的 id 。 GitHub 将删除特殊字符,并在当前步骤运行没有 id 的脚本时使用名称 __run 。 如果在同一作业中多次使用相同的操作,则名称将包含一个前面跟序号和下划线的后缀。 例如,运行的第一个脚本名称 __run ,则第二个脚本将命名为 __run_2 。 同样,actions/checkout 第二次调用时将变成 actionscheckout2 。 |
github.action_path | 字符串 | 操作所在的路径。 此属性仅在复合操作中受支持。 您可以使用此路径访问与操作位于同一存储库中的文件。 |
github.action_ref | 字符串 | 对于执行操作的步骤,这是正在执行的操作的引用。 例如 v2 。 |
github.action_repository | 字符串 | 对于执行操作的步骤,这是操作的所有者和存储库名称。 例如 actions/checkout 。 |
github.action_status | 字符串 | 对于复合操作,这是复合操作的当前结果。 |
github.actor | 字符串 | 发起工作流程运行的用户的用户名。 |
github.api_url | 字符串 | GitHub REST API 的 URL。 |
github.base_ref | 字符串 | 工作流程运行中拉取请求的 base_ref 或目标分支。 此属性仅在触发工作流程运行的事件为 pull_request 或 pull_request_target 时才可用。 |
github.env | 字符串 | 运行器上从工作流程命令到设置环境变量的文件路径。 此文件对于当前步骤是唯一的,并且是作业中每个步骤的不同文件。 更多信息请参阅“GitHub Actions 的工作流程命令”。 |
github.event | 对象 | 完整事件 web 挂钩有效负载。 您可以使用上下文访问事件的个别属性。 此对象与触发工作流运行的事件的 web 挂钩有效负载相同,并且对于每个事件都是不同的。 每个 GitHub Actions 事件的 web 挂钩都链接在“触发工作流程”的事件中。 例如,对于由 push 事件触发的工作流程运行,此对象包含push webhook payload 的内容。 |
github.event_name | 字符串 | 触发工作流程运行的事件的名称。 |
github.event_path | 字符串 | 运行器上包含完整事件 web 挂钩负载的文件的路径。 |
github.graphql_url | 字符串 | GitHub GraphQL API 的 URL。 |
github.head_ref | 字符串 | 工作流程运行中拉取请求的 head_ref 或来源分支。 此属性仅在触发工作流程运行的事件为 pull_request 或 pull_request_target 时才可用。 |
github.job | 字符串 | 当前作业的 job_id 。 |
github.ref | 字符串 | 触发工作流程的分支或标记参考。 对于分支,格式为 refs/heads/<branch_name> ,对于标记是 refs/tags/<tag_name> 。 |
github.ref_name | string | 触发工作流程的分支或标记名称。 |
github.path | string | 运行器上从工作流程命令到设置系统 PATH 变量的文件的路径。 此文件对于当前步骤是唯一的,并且是作业中每个步骤的不同文件。 更多信息请参阅“GitHub Actions 的工作流程命令”。 |
github.run_attempt | string | 在存储库中运行的特定工作流程的每次尝试的唯一编号。 对于工作流程运行的第一次尝试,此数字从 1 开始,并随着每次重新运行而递增。 |
github.server_url | string | GitHub 服务器的 URL。 例如:https://github.com 。 |
github
上下文的示例内容
以下示例上下文来自由 push
事件触发的工作流程运行。 此示例中的 event
对象已被截断,因为它与 push
web 挂钩有效负载的内容相同。
Note: This context is an example only. The contents of a context depends on the workflow that you are running. Contexts, objects, and properties will vary significantly under different workflow run conditions.
{
"token": "***",
"job": "dump_contexts_to_log",
"ref": "refs/heads/my_branch",
"sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369",
"repository": "octocat/hello-world",
"repository_owner": "octocat",
"repositoryUrl": "git://github.com/octocat/hello-world.git",
"run_id": "1536140711",
"run_number": "314",
"retention_days": "90",
"run_attempt": "1",
"actor": "octocat",
"workflow": "Context testing",
"head_ref": "",
"base_ref": "",
"event_name": "push",
"event": {
...
},
"server_url": "https://github.com",
"api_url": "https://api.github.com",
"graphql_url": "https://api.github.com/graphql",
"ref_name": "my_branch",
"ref_protected": false,
"ref_type": "branch",
"secret_source": "Actions",
"workspace": "/home/runner/work/hello-world/hello-world",
"action": "github_step",
"event_path": "/home/runner/work/_temp/_github_workflow/event.json",
"action_repository": "",
"action_ref": "",
"path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602",
"env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602"
}
github
上下文的示例用法
仅当工作流运行是由 pull_request
事件触发时,此示例工作流才使用 github.event_name
上下文来运行作业。
name: Run CI
on: [push, pull_request]
jobs:
normal_ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run normal CI
run: ./run-tests
pull_request_ci:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'pull_request' }}
steps:
- uses: actions/checkout@v3
- name: Run PR CI
run: ./run-additional-pr-ci
env
上下文
env
上下文包含已在工作流程、作业或步骤中设置的环境变量。 有关在工作流程中设置环境变量的更多信息,请参阅“GitHub Actions 的工作流程语法”。
env
上下文语法允许您在工作流程文件中使用环境变量的值。 您可以在步骤中除 id
和 uses
之外的任何键的值中使用 env
上下文。 有关步骤语法的更多信息,请参阅“GitHub Actions 的工作流程语法”。
如果您想要在运行器中使用环境变量的值,请使用运行器操作系统的正常方法来读取环境变量。
属性名称 | 类型 | 描述 |
---|---|---|
env | 对象 | 此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的属性。 |
env.<env_name> | 字符串 | 特定环境变量的值。 |
env
上下文的示例内容
env
上下文的内容是环境变量名称与其值的映射。 上下文的内容可能会根据工作流运行中的使用位置而更改。
{
"first_name": "Mona",
"super_duper_var": "totally_awesome"
}
env
上下文的示例用法
此示例工作流演示如何在工作流、作业和步骤级别配置 env
上下文,以及如何在步骤中使用上下文。
当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的环境变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流程变量。 为作业定义的变量在作业执行时将覆盖名称相同的工作流程变量。
name: Hi Mascot
on: push
env:
mascot: Mona
super_duper_var: totally_awesome
jobs:
windows_job:
runs-on: windows-latest
steps:
- run: echo 'Hi ${{ env.mascot }}' # Hi Mona
- run: echo 'Hi ${{ env.mascot }}' # Hi Octocat
env:
mascot: Octocat
linux_job:
runs-on: ubuntu-latest
env:
mascot: Tux
steps:
- run: echo 'Hi ${{ env.mascot }}' # Hi Tux
job
上下文
job
上下文包含当前正在运行的作业相关信息。
属性名称 | 类型 | 描述 |
---|---|---|
job | 对象 | 此上下文针对工作流程运行中的每项作业而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。 |
job.container | 对象 | 作业的容器相关信息。 有关容器的更多信息,请参阅“GitHub Actions 的工作流程语法”。 |
job.container.id | 字符串 | 容器的 ID。 |
job.container.network | 字符串 | 容器网络的 ID。 运行程序创建作业中所有容器使用的网络。 |
job.services | 对象 | 为作业创建的服务容器。 有关服务容器的更多信息,请参阅“GitHub Actions 的工作流程语法”。 |
job.services.<service_id>.id | 字符串 | 服务容器的 ID。 |
job.services.<service_id>.network | 字符串 | 服务容器网络的 ID。 运行程序创建作业中所有容器使用的网络。 |
job.services.<service_id>.ports | 对象 | 服务容器显露的端口。 |
job.status | 字符串 | 作业的当前状态。 可能的值包括 success 、failure 或 cancelled 。 |
job
上下文的示例内容
此示例 job
上下文使用具有映射端口的 PostgreSQL 服务容器。 如果作业中没有使用容器或服务容器,则 job
上下文仅包含 status
属性。
{
"status": "success",
"container": {
"network": "github_network_53269bd575974817b43f4733536b200c"
},
"services": {
"postgres": {
"id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
"ports": {
"5432": "49153"
},
"network": "github_network_53269bd575974817b43f4733536b200c"
}
}
}
job
上下文的示例用法
此示例工作流程配置 PostgreSQL 服务容器,并自动将服务容器中的端口 5432 映射到主机上随机选择的可用端口。 job
上下文用于访问在主机上分配的端口号。
name: PostgreSQL Service Example
on: push
jobs:
postgres-job:
runs-on: ubuntu-latest
services:
postgres:
image: postgres
env:
POSTGRES_PASSWORD: postgres
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
ports:
# Maps TCP port 5432 in the service container to a randomly chosen available port on the host.
- 5432
steps:
- uses: actions/checkout@v3
- run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
- run: ./run-tests
steps
上下文
steps
上下文包含有关当前作业中指定了 id
且已运行的步骤的信息。
属性名称 | 类型 | 描述 |
---|---|---|
steps | 对象 | 此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。 |
steps.<step_id>.outputs | 对象 | 为步骤定义的输出集。 更多信息请参阅“GitHub Actions 的元数据语法”。 |
steps.<step_id>.conclusion | 字符串 | 在 continue-on-error 应用之后完成的步骤的结果。 可能的值包括 success 、failure 、cancelled 或 skipped 。 当 continue-on-error 步骤失败时,outcome 为 failure ,但最终的 conclusion 为 success 。 |
steps.<step_id>.outcome | 字符串 | 在 continue-on-error 应用之前完成的步骤的结果。 可能的值包括 success 、failure 、cancelled 或 skipped 。 当 continue-on-error 步骤失败时,outcome 为 failure ,但最终的 conclusion 为 success 。 |
steps.<step_id>.outputs.<output_name> | 字符串 | 特定输出的值。 |
steps
上下文的示例内容
此示例 steps
上下文显示前面两个指定了 id
的步骤。 第一步将 id
命名为 checkout
,第二步 generate_number
。 generate_number
步骤有一个名为 random_number
的输出。
{
"checkout": {
"outputs": {},
"outcome": "success",
"conclusion": "success"
},
"generate_number": {
"outputs": {
"random_number": "1"
},
"outcome": "success",
"conclusion": "success"
}
}
steps
上下文的示例用法
此示例工作流程在一个步骤中生成一个随机数作为输出,后面的步骤使用 steps
上下文来读取该输出的值。
name: Generate random failure
on: push
jobs:
randomly-failing-job:
runs-on: ubuntu-latest
steps:
- id: checkout
uses: actions/checkout@v3
- name: Generate 0 or 1
id: generate_number
run: echo "::set-output name=random_number::$(($RANDOM % 2))"
- name: Pass or fail
run: |
if [[ ${{ steps.generate_number.outputs.random_number }} == 0 ]]; then exit 0; else exit 1; fi
runner
上下文
runner
上下文包含正在执行当前作业的运行器相关信息。
属性名称 | 类型 | 描述 |
---|---|---|
runner | 对象 | 此上下文针对工作流程运行中的每项作业而改变。 此对象包含下面列出的所有属性。 |
runner.name | 字符串 | 执行作业的运行器的名称。 |
runner.os | 字符串 | 执行作业的运行器的操作系统。 可能的值为 Linux 、Windows 或 macOS 。 |
runner.arch | 字符串 | 执行作业的运行器的架构。 可能的值包括 X86 、X64 、ARM 或 ARM64 。 |
| runner.temp
| 字符串
| 运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。
| runner.tool_cache
| 字符串
| 包含 GitHub 托管运行器预安装工具的目录路径。 更多信息请参阅“关于 GitHub 托管的运行器”。
runner
上下文的示例内容
以下示例上下文来自 Linux GitHub 托管的运行器。
{
"os": "Linux",
"arch": "X64",
"name": "GitHub Actions 2",
"tool_cache": "/opt/hostedtoolcache",
"temp": "/home/runner/work/_temp"
}
runner
上下文的示例用法
此示例工作流程使用 runner
上下文来设置临时目录的路径以写入日志,如果工作流程失败,它将这些日志上传为构件。
name: Build
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build with logs
run: |
mkdir ${{ runner.temp }}/build_logs
./build.sh --log-path ${{ runner.temp }}/build_logs
- name: Upload logs on fail
if: ${{ failure() }}
uses: actions/upload-artifact@v3
with:
name: Build failure logs
path: ${{ runner.temp }}/build_logs
secrets
上下文
secrets
上下文包含可用于工作流程运行的机密的名称和值。 secrets
上下文不可用于复合操作。 有关机密的更多信息,请参阅“加密密码”。
GITHUB_TOKEN
是为每个工作流程运行自动创建的机密,并且始终包含在 secrets
上下文中。 更多信息请参阅“自动令牌身份验证”。
警告:GitHub 自动将密码编写到日志,但您应避免有意将密码打印到日志。
属性名称 | 类型 | 描述 |
---|---|---|
secrets | 对象 | 对于工作流程运行中的每个作业,此上下文都是相同的。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。 |
secrets.GITHUB_TOKEN | 字符串 | 为每个工作流程运行自动创建的令牌。 更多信息请参阅“自动令牌身份验证”。 |
secrets.<secret_name> | 字符串 | 特定机密的值。 |
secrets
上下文的示例内容
以下 secrets
上下文的示例内容显示了自动 GITHUB_TOKEN
,以及可用于工作流程运行的另外两个机密。
{
"github_token": "***",
"NPM_TOKEN": "***",
"SUPERSECRET": "***"
}
secrets
上下文的示例用法
此示例工作流程使用贴标器操作,需要 GITHUB_TOKEN
作为 repo-token
输入参数的值:
name: Pull request labeler
on: [ pull_request_target ]
permissions:
contents: read
pull-requests: write
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: actions/labeler@v4
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
strategy
上下文
对于具有矩阵的工作流程,strategy
上下文包含有关当前作业的矩阵执行策略的信息。
属性名称 | 类型 | 描述 |
---|---|---|
strategy | 对象 | 此上下文针对工作流程运行中的每项作业而改变。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的所有属性。 |
strategy.fail-fast | 字符串 | 为 true 时,如果矩阵中的任何作业失败,所有正在进行的作业都将被取消。 更多信息请参阅“GitHub Actions 的工作流程语法”。 |
strategy.job-index | 字符串 | 矩阵中当前作业的索引。 注意: 此数字是零基数字。 矩阵中第一个作业的索引是 0 。 |
strategy.job-total | 字符串 | 矩阵中的作业总数。 注意: 此数字 不是从零基数字。 例如,对于具有四个作业的矩阵,job-total 的值为 4 。 |
strategy.max-parallel | 字符串 | 使用 matrix 作业策略时可同时运行的最大作业数。 更多信息请参阅“GitHub Actions 的工作流程语法”。 |
strategy
上下文的示例内容
strategy
上下文的以下示例内容来自具有四个作业的矩阵,取自最终作业。 请注意零基 job-index
数字与 job-total
(非零基)之间的差异。
{
"fail-fast": true,
"job-index": 3,
"job-total": 4,
"max-parallel": 4
}
strategy
上下文的示例用法
此示例工作流程使用 strategy.job-index
属性为矩阵中每个作业的日志文件设置唯一名称。
name: Test matrix
on: push
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
test-group: [1, 2]
node: [14, 16]
steps:
- uses: actions/checkout@v3
- run: npm test > test-job-${{ strategy.job-index }}.txt
- name: Upload logs
uses: actions/upload-artifact@v3
with:
name: Build log for job ${{ strategy.job-index }}
path: test-job-${{ strategy.job-index }}.txt
matrix
上下文
对于具有矩阵的工作流程,matrix
上下文包含工作流程文件中定义的适用于当前作业的矩阵属性。 例如,如果使用 os
和 node
键配置矩阵,则 matrix
上下文对象将包括 os
和 node
属性,具有用于当前作业的值。
matrix
上下文中没有标准属性,只有工作流程文件中定义的属性。
属性名称 | 类型 | 描述 |
---|---|---|
matrix | 对象 | 此上下文仅适用于矩阵中的作业,并且对于工作流程运行中的每个作业都会发生更改。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的属性。 |
matrix.<property_name> | 字符串 | 矩阵属性的值。 |
matrix
上下文的示例内容
matrix
上下文的以下示例内容来自矩阵中的作业,该矩阵具有工作流中定义的 os
和 node
矩阵属性。 该作业执行 ubuntu-latest
OS 和 Node.js 版本 16
的矩阵组合。
{
"os": "ubuntu-latest",
"node": 16
}
matrix
上下文的示例用法
此示例工作流程创建一个包含 os
和 node
键的矩阵。 它使用 matrix.os
属性为每个作业设置运行器类型,并使用 matrix.node
属性为每个作业设置 Node.js 版本。
name: Test matrix
on: push
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest]
node: [14, 16]
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node }}
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
needs
上下文
needs
上下文包含定义为当前作业依赖项的所有作业的输出。 有关定义作业依赖项的更多信息,请参阅“GitHub Actions 的工作流程语法”。
属性名称 | 类型 | 描述 |
---|---|---|
needs | 对象 | 仅为具有相关作业的工作流程运行填充此上下文,并为工作流程运行中的每个作业填充此上下文。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的所有属性。 |
needs.<job_id> | 对象 | 当前作业依赖的单个作业。 |
needs.<job_id>.outputs | 对象 | 当前作业依赖的作业的输出集。 |
needs.<job_id>.outputs.<output name> | 字符串 | 当前作业依赖的作业的特定输出值。 |
needs.<job_id>.result | 字符串 | 当前作业依赖的作业的结果。 可能的值包括 success 、failure 、cancelled 或 skipped 。 |
needs
上下文的示例内容
needs
上下文的以下示例内容显示了当前作业所依赖的两个作业的信息。
{
"build": {
"result": "success",
"outputs": {
"build_id": "ABC123"
}
},
"deploy": {
"result": "failure",
"outputs": {}
}
}
needs
上下文的示例用法
此示例工作流程有三个作业:执行生成的 build
作业,执行生成;需要 build
作业的 deploy
作业,以及需要 build
和 deploy
作业并且仅工作流程中出现失败时运行的 debug
作业。 deploy
作业还使用 needs
上下文来访问 build
作业的输出。
name: Build and deploy
on: push
jobs:
build:
runs-on: ubuntu-latest
outputs:
build_id: ${{ steps.build_step.outputs.build_id }}
steps:
- uses: actions/checkout@v3
- name: Build
id: build_step
run: |
./build
echo "::set-output name=build_id::$BUILD_ID"
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: ./deploy --build ${{ needs.build.outputs.build_id }}
debug:
needs: [build, deploy]
runs-on: ubuntu-latest
if: ${{ failure() }}
steps:
- uses: actions/checkout@v3
- run: ./debug
inputs
上下文
inputs
上下文包含传递给可重用工作流程的输入属性。 输入名称和类型在可重用工作流程的 workflow_call
事件配置中定义,输入值从调用可重用工作流程的外部工作流中的 jobs.<job_id>.with
传递。
inputs
上下文中没有标准属性,只有那些在可重用工作流程文件中定义的属性。
更多信息请参阅“重用工作流程”。
属性名称 | 类型 | 描述 |
---|---|---|
inputs | 对象 | 此上下文仅在可重用的工作流程中可用。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的属性。 |
inputs.<name> | string 或 number 或 boolean | 从外部工作流传递的每个输入值。 |
inputs
上下文的示例内容
inputs
上下文的以下示例内容来自已定义 build_id
和 deploy_target
输入的可重用工作流程中的作业。
{
"build_id": 123456768,
"deploy_target": "deployment_sys_1a"
}
inputs
上下文的示例用法
此可重用工作流程示例使用 inputs
上下文来获取从调用方工作流传递到可重用工作流的 build_id
的值和 deploy_target
输入。
name: Reusable deploy workflow
on:
workflow_call:
inputs:
build_id:
required: true
type: number
deploy_target:
required: true
type: string
perform_deploy:
required: true
type: boolean
jobs:
deploy:
runs-on: ubuntu-latest
if: ${{ inputs.perform_deploy == 'true' }}
steps:
- name: Deploy build to target
run: deploy --build ${{ inputs.build_id }} --target ${{ inputs.deploy_target }}