注:GitHub Enterprise Server 2.22 上的 GitHub Actions 支持是有限的公测版。 测试已结束。 GitHub Actions 现在一般可用于 GitHub Enterprise Server 3.0 或更新版本。 更多信息请参阅 GitHub Enterprise Server 3.0 发行说明。
- 有关升级到 GitHub Enterprise Server 3.0 或更新版本的更多信息,请参阅“升级 GitHub Enterprise Server”。
- 有关在升级后配置 GitHub Actions 的更多信息,请参阅 GitHub Enterprise Server 3.0 的文档。
注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
About contexts
警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
上下文是一种访问工作流程运行、运行器环境、作业及步骤相关信息的方式。 上下文使用表达式语法。 For more information, see "Expressions."
${{ <context> }}
上下文名称 | 类型 | 描述 |
---|---|---|
github | 对象 | 工作流程运行的相关信息。 更多信息请参阅 github 上下文。 |
env | 对象 | 包含工作流程、作业或步骤中设置的环境变量。 更多信息请参阅 env 上下文。 |
job | 对象 | 当前执行的作业相关信息。 更多信息请参阅 job 上下文。 |
steps | 对象 | 此作业中已经运行的步骤的相关信息。 更多信息请参阅 steps 上下文。 |
runner | 对象 | 运行当前作业的运行程序相关信息。 更多信息请参阅 runner 上下文。 |
secrets | 对象 | 启用对密码的访问权限。 有关密码的更多信息,请参阅“创建和使用加密密码”。 |
strategy | 对象 | 用于访问配置的策略参数及当前作业的相关信息。 策略参数包括 fail-fast 、job-index 、job-total 和 max-parallel 。 |
matrix | 对象 | 用于访问为当前作业配置的矩阵参数。 例如,如果使用 os 和 node 版本配置矩阵构建,matrix 上下文对象将包含当前作业的 os 和 node 版本。 |
needs | 对象 | 允许访问定义为当前作业依赖项的所有作业的输出。 更多信息请参阅 needs 上下文。 |
作为表达式的一部分,您可以使用以下两种语法之一访问上下文信息。
- 索引语法:
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
环境变量。
github
上下文
github
上下文包含有关工作流程运行以及触发运行的事件相关信息。 您可以读取环境变量中的大多数 github
上下文数据。 有关环境变量的更多信息,请参阅“使用环境变量”。
警告:在使用整个 github
上下文时,请注意其中包括诸如 github.token
等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。
警告:创建工作流程和操作时,您应始终考虑您的代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 更多信息请参阅“了解脚本注入的风险”。
属性名称 | 类型 | 描述 |
---|---|---|
github | 对象 | 工作流程中任何作业或步骤期间可用的顶层上下文。 |
github.action | 字符串 | 正在运行的操作的名称。 GitHub removes special characters or uses the name __run when the current step runs a script. If you use the same action more than once in the same job, the name will include a suffix with the sequence number with underscore before it. For example, the first script you run will have the name __run , and the second script will be named __run_2 . 同样,actions/checkout 第二次调用时将变成 actionscheckout2 。 |
github.action_path | 字符串 | 您的操作所在的路径。 您可以使用此路径轻松访问与操作位于同一仓库中的文件。 此属性仅在复合操作中才受支持。 |
github.actor | 字符串 | 发起工作流程运行的用户的登录名。 |
github.base_ref | 字符串 | 工作流程运行中拉取请求的 base_ref 或目标分支。 此属性仅在触发工作流程运行的事件为 pull_request 或 pull_request_target 时才可用。 |
github.event | 对象 | 完整事件 web 挂钩有效负载。 更多信息请参阅“触发工作流程的事件”。 您可以使用上下文访问事件的个别属性。 |
github.event_name | 字符串 | 触发工作流程运行的事件的名称。 |
github.event_path | 字符串 | 运行器上完整事件 web 挂钩有效负载的路径。 |
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.repository | 字符串 | 所有者和仓库名称。 例如 Codertocat/Hello-World 。 |
github.repository_owner | 字符串 | 仓库所有者的名称。 例如 Codertocat 。 |
github.run_id | 字符串 | 仓库中每个运行的唯一编号。 如果您重新执行工作流程运行,此编号不变。 |
github.run_number | 字符串 | 仓库中特定工作流程每个运行的唯一编号。 此编号从 1(对应于工作流程的第一个运行)开始,然后随着每个新的运行而递增。 如果您重新执行工作流程运行,此编号不变。 |
github.run_attempt | 字符串 | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. |
github.server_url | 字符串 | Returns the URL of the GitHub server. 例如:https://github.com 。 |
github.sha | 字符串 | 触发工作流程的提交 SHA。 |
github.token | 字符串 | 代表仓库上安装的 GitHub 应用程序进行身份验证的令牌。 这在功能上等同于 GITHUB_TOKEN 密码。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。 |
github.workflow | 字符串 | 工作流程的名称。 如果工作流程文件未指定 name ,此属性的值将是仓库中工作流程文件的完整路径。 |
github.workspace | 字符串 | 使用 checkout 操作时步骤的默认工作目录和仓库的默认位置。 |
env
上下文
env
上下文包含已在工作流程、作业或步骤中设置的环境变量。 有关在工作流程中设置环境变量的更多信息,请参阅“GitHub Actions 的工作流程语法”。
env
上下文语法允许您在工作流程文件中使用环境变量的值。 您可以在步骤的任何键值中使用 env
上下文,但 id
和 uses
键除外。 有关步骤语法的更多信息,请参阅“GitHub Actions 的工作流程语法”。
如果您想要在运行器中使用环境变量的值,请使用运行器操作系统的正常方法来读取环境变量。
属性名称 | 类型 | 描述 |
---|---|---|
env | 对象 | 此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。 |
env.<env_name> | 字符串 | 特定环境变量的值。 |
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 。 |
steps
上下文
steps
上下文包含当前作业中已经运行的步骤相关信息。
属性名称 | 类型 | 描述 |
---|---|---|
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> | 字符串 | 特定输出的值。 |
runner
上下文
runner
上下文包含正在执行当前作业的运行器相关信息。
属性名称 | 类型 | 描述 |
---|---|---|
runner.name | 字符串 | The name of the runner executing the job. |
runner.os | 字符串 | 执行作业的运行器的操作系统。 可能的值为 Linux 、Windows 或 macOS 。 |
runner.temp | 字符串 | 运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。 |
runner.tool_cache | 字符串 | 包含 GitHub 托管运行器预安装工具的目录路径。 更多信息请参阅“GitHub 托管运行器的规范”。 |
needs
上下文
needs
上下文包含定义为当前作业依赖项的所有作业的输出。 有关定义作业依赖项的更多信息,请参阅“GitHub Actions 的工作流程语法”。
属性名称 | 类型 | 描述 |
---|---|---|
needs.<job id> | 对象 | 当前作业依赖的单个作业。 |
needs.<job id>.outputs | 对象 | 当前作业依赖的作业的输出集。 |
needs.<job id>.outputs.<output name> | 字符串 | 当前作业依赖的作业的特定输出值。 |
needs.<job id>.result | 字符串 | 当前作业依赖的作业的结果。 可能的值包括 success 、failure 、cancelled 或 skipped 。 |
打印上下文信息到日志文件的示例
要检查每个上下文中可访问的信息,您可以使用此工作流程文件示例。
警告:在使用整个 github
上下文时,请注意其中包括诸如 github.token
等敏感信息。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。
.github/workflows/main.yml
on: push
jobs:
one:
runs-on: ubuntu-latest
steps:
- name: Dump GitHub context
env:
GITHUB_CONTEXT: ${{ toJSON(github) }}
run: echo "$GITHUB_CONTEXT"
- name: Dump job context
env:
JOB_CONTEXT: ${{ toJSON(job) }}
run: echo "$JOB_CONTEXT"
- name: Dump steps context
env:
STEPS_CONTEXT: ${{ toJSON(steps) }}
run: echo "$STEPS_CONTEXT"
- name: Dump runner context
env:
RUNNER_CONTEXT: ${{ toJSON(runner) }}
run: echo "$RUNNER_CONTEXT"
- name: Dump strategy context
env:
STRATEGY_CONTEXT: ${{ toJSON(strategy) }}
run: echo "$STRATEGY_CONTEXT"
- name: Dump matrix context
env:
MATRIX_CONTEXT: ${{ toJSON(matrix) }}
run: echo "$MATRIX_CONTEXT"
上下文可用性
在整个工作流程运行过程中,提供不同的上下文。 例如,secrets
上下文只能用于作业中的某些地方。
此外,某些功能只能在某些地方使用。 例如, hashFiles
函数无法随处可用。
下表列出了工作流程中每一个上下文和特殊函数可以使用的地方。 除非下面列出,否则可以在任何地方使用函数。
路径 | 上下文 | 特殊函数 |
---|---|---|
concurrency | github | |
env | github, secrets | |
jobs.<job_id>.concurrency | github, needs, strategy, matrix | |
jobs.<job_id>.container | github, needs, strategy, matrix | |
jobs.<job_id>.container.credentials | github, needs, strategy, matrix, env, secrets | |
jobs.<job_id>.container.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | |
jobs.<job_id>.continue-on-error | github, needs, strategy, matrix | |
jobs.<job_id>.defaults.run | github, needs, strategy, matrix, env | |
jobs.<job_id>.env | github, needs, strategy, matrix, secrets | |
jobs.<job_id>.environment | github, needs, strategy, matrix | |
jobs.<job_id>.environment.url | github, needs, strategy, matrix, job, runner, env, steps | |
jobs.<job_id>.if | github, needs | always, cancelled, success, failure |
jobs.<job_id>.name | github, needs, strategy, matrix | |
jobs.<job_id>.outputs.<output_id> | github, needs, strategy, matrix, job, runner, env, secrets, steps | |
jobs.<job_id>.runs-on | github, needs, strategy, matrix | |
jobs.<job_id>.services | github, needs, strategy, matrix | |
jobs.<job_id>.services.<service_id>.credentials | github, needs, strategy, matrix, env, secrets | |
jobs.<job_id>.services.<service_id>.env.<env_id> | github, needs, strategy, matrix, job, runner, env, secrets | |
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 | hashFiles |
jobs.<job_id>.steps.if | github, needs, strategy, matrix, job, runner, env, steps | always, cancelled, success, failure, hashFiles |
jobs.<job_id>.steps.name | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.steps.run | github, needs, strategy, matrix, job, runner, env, secrets, steps | 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 | hashFiles |
jobs.<job_id>.steps.working-directory | github, needs, strategy, matrix, job, runner, env, secrets, steps | hashFiles |
jobs.<job_id>.strategy | github, needs | |
jobs.<job_id>.timeout-minutes | github, needs, strategy, matrix |