Skip to main content

上下文

您可以在工作流程和操作中访问上下文信息。

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

关于上下文

上下文是一种访问工作流运行、变量、运行器环境、作业及步骤相关信息的方式。 每个上下文都是一个包含属性的对象,属性可以是字符串或其他对象。

在不同的工作流运行条件下,上下文、对象和属性大不相同。 例如,matrix 上下文仅针对矩阵中的作业填充。

您可以使用表达式语法访问上下文。 有关详细信息,请参阅“表达式”。

${{ <context> }}

警告:创建工作流程和操作时,应始终考虑代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 有关详细信息,请参阅“了解脚本注入的风险”。

上下文名称类型说明
githubobject工作流程运行的相关信息。 有关更多信息,请参阅 github 上下文
envobject包含工作流、作业或步骤中设置的变量。 有关更多信息,请参阅 env 上下文

作为表达式的一部分,您可以使用以下两种语法之一访问上下文信息。

  • 索引语法:github['sha']
  • 属性取消引用语法:github.sha

若要使用属性取消引用语法,属性名称必须以字母或 _ 开头,并且只能包含字母数字字符、-_

如果尝试取消引用不存在的属性,则计算结果为空字符串。

确定何时使用上下文

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, inputs | | | 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, inputs | 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, inputs | 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, inputs | | | on.workflow_call.inputs.<inputs_id>.default | github, inputs | | | on.workflow_call.outputs.<output_id>.value | github, jobs, inputs | |

示例:将上下文信息打印到日志

您可以将上下文的内容打印到日志中进行调试。 需要使用 toJSON 函数 才能将 JSON 对象优质打印到日志。

警告: 使用整个 github 上下文时,请注意其中包含敏感信息,例如 github.token。 GitHub 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。

YAML
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 在打印到控制台时会隐藏密钥,但您在导出或打印上下文时应谨慎行事。

警告:创建工作流程和操作时,应始终考虑代码是否会执行来自可能的攻击者的不信任输入。 某些上下文应被视为不受信任的输入,因为攻击者可能会插入自己的恶意内容。 有关详细信息,请参阅“了解脚本注入的风险”。

属性名称类型说明
githubobject工作流程中任何作业或步骤期间可用的顶层上下文。 此对象包含下面列出的所有属性。
github.actionstring正在运行的操作的名称,或步骤的 id。 在当前步骤运行脚本(无 id)时,GitHub 删除特殊字符并使用名称 __run。 如果在同一作业中多次使用相同的操作,则名称将包含一个前面跟序号和下划线的后缀。 例如,运行的第一个脚本名称 __run,则第二个脚本将命名为 __run_2。 同样,actions/checkout 的第二次调用将为 actionscheckout2
github.action_pathstring操作所在的路径。 此属性仅在复合操作中受支持。 可以使用此路径访问与操作位于同一存储库中的文件,例如将目录更改为该路径: cd ${{ github.action_path }}
github.action_refstring对于执行操作的步骤,这是正在执行的操作的引用。 例如,v2
github.action_repositorystring对于执行操作的步骤,这是操作的所有者和存储库名称。 例如,actions/checkout
github.action_statusstring对于复合操作,这是复合操作的当前结果。
github.actorstring启动工作流运行的用户的用户名。

github 上下文的示例内容

以下示例上下文来自 push 事件触发的工作流运行。 此示例中的 event 对象已被截断,因为它与 push webhook 有效负载的内容相同。

注意:此上下文只是一个示例。 上下文的内容取决于正在运行的工作流。 在不同的工作流运行条件下,上下文、对象和属性大不相同。

{
  "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 上下文运行作业。

YAML
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 上下文语法支持在工作流文件中使用变量的值。 可以在非 iduses 键的步骤中,在任何键的值中使用 env 上下文。 有关 step 语法的详细信息,请参阅“GitHub Actions 的工作流语法”。

如果想要在运行器中使用变量的值,请使用运行器操作系统的正常方法来读取环境变量。

属性名称类型说明
envobject此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的属性。
env.<env_name>string特定环境变量的值。

env 上下文的示例内容

env 上下文的内容是变量名称与其值的映射。 上下文的内容可能会根据工作流运行中的使用位置而更改。

{
  "first_name": "Mona",
  "super_duper_var": "totally_awesome"
}

env 上下文的示例用法

此示例工作流演示如何在工作流、作业和步骤级别配置 env 上下文,以及如何在步骤中使用上下文。

当多个环境变量使用相同的名称定义时,GitHub 会使用最特定的变量。 例如,步骤中定义的环境变量在步骤执行时将覆盖名称相同的作业和工作流环境变量。 为作业定义的环境变量在作业执行时将覆盖名称相同的工作流变量。

YAML
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 上下文包含当前正在运行的作业相关信息。

属性名称类型说明
jobobject此上下文针对工作流程运行中的每项作业而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。
job.containerobject作业的容器相关信息。 有关容器的详细信息,请参阅“GitHub Actions 的工作流语法”。
job.container.idstring容器的 ID。
job.container.networkstring容器网络的 ID。 运行程序创建作业中所有容器使用的网络。
job.servicesobject为作业创建的服务容器。 有关服务容器的详细信息,请参阅“GitHub Actions 的工作流语法”。
job.services.<service_id>.idstring服务容器的 ID。
job.services.<service_id>.networkstring服务容器网络的 ID。 运行程序创建作业中所有容器使用的网络。
job.services.<service_id>.portsobject服务容器显露的端口。
job.statusstring作业的当前状态。 可能的值为 successfailurecancelled

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 上下文用于访问在主机上分配的端口号。

YAML
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

jobs 上下文

jobs 上下文仅在可重用工作流中可用,并且只能用于设置可重用工作流的输出。 有关详细信息,请参阅“重用工作流”。

属性名称类型说明
jobsobject这仅在可重用工作流中使用,并且只能用于设置可重用工作流的输出。 此对象包含下面列出的所有属性。
jobs.<job_id>.resultstring可重用工作流中作业的结果。 可能的值为 successfailurecancelledskipped
jobs.<job_id>.outputsobject可重用工作流中作业的输出集。
jobs.<job_id>.outputs.<output_name>string可重用工作流中作业的特定输出值。

jobs 上下文的示例内容

此示例 jobs 上下文包含可重用工作流运行中作业的结果和输出。

{
  "example_job": {
    "result": "success",
    "outputs": {
      "output1": "hello",
      "output2": "world"
    }
  }
}

jobs 上下文的示例用法

此示例可重用工作流使用 jobs 上下文设置可重用工作流的输出。 请注意输出如何从步骤流向作业,然后流向 workflow_call 触发器。 有关详细信息,请参阅“重用工作流”。

YAML
name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

steps 上下文

steps 上下文包含有关当前作业中已指定 id 且已运行的步骤的信息。

属性名称类型说明
stepsobject此上下文针对作业中的每个步骤而改变。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。
steps.<step_id>.outputsobject为步骤定义的输出集。 有关详细信息,请参阅“GitHub Actions 的元数据语法”。
steps.<step_id>.conclusionstring应用 continue-on-error 后完成的步骤的结果。 可能的值为 successfailurecancelledskipped。 当 continue-on-error 步骤失败时,outcomefailure,但最终 conclusionsuccess
steps.<step_id>.outcomestring应用 continue-on-error 前完成的步骤的结果。 可能的值为 successfailurecancelledskipped。 当 continue-on-error 步骤失败时,outcomefailure,但最终 conclusionsuccess
steps.<step_id>.outputs.<output_name>string特定输出的值。

steps 上下文的示例内容

此示例 steps 上下文显示已指定 id 的前两个步骤。 第一步的 id 名为 checkout,第二步是 generate_numbergenerate_number 步骤的输出名为 random_number

{
  "checkout": {
    "outputs": {},
    "outcome": "success",
    "conclusion": "success"
  },
  "generate_number": {
    "outputs": {
      "random_number": "1"
    },
    "outcome": "success",
    "conclusion": "success"
  }
}

steps 上下文的示例用法

此示例工作流在一个步骤中生成一个随机数作为输出,后面的步骤使用 steps 上下文来读取该输出的值。

YAML
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 上下文包含正在执行当前作业的运行器相关信息。

属性名称类型说明
runnerobject此上下文针对工作流程运行中的每项作业而改变。 此对象包含下面列出的所有属性。
runner.namestring执行作业的运行器的名称。
runner.osstring执行作业的运行器的操作系统。 可能的值为 LinuxWindowsmacOS
runner.archstring执行作业的运行器的体系结构。 可能的值为 X86X64ARMARM64
runner.tempstring运行器临时目录的路径。 此目录在每个作业的开始和结束时都是空的。 注意,如果运行者的用户帐户没有权限删除这些文件,则不会被删除。
runner.tool_cachestring包含 GitHub 托管运行器预安装工具的目录路径。 有关详细信息,请参阅“有关 GitHub 托管的运行器”。
runner.debugstring仅当启用调试日志记录并且始终具有值 1 时,才会进行此设置。 它可以用作指示器,以便在自己的作业步骤中启用更多调试或详细日志记录。

runner 上下文的示例内容

以下示例上下文来自 Linux GitHub 托管的运行器。

{
  "os": "Linux",
  "arch": "X64",
  "name": "GitHub Actions 2",
  "tool_cache": "/opt/hostedtoolcache",
  "temp": "/home/runner/work/_temp"
}

runner 上下文的示例用法

此示例工作流使用 runner 上下文来设置临时目录的路径以写入日志,如果工作流失败,它将这些日志上传为项目。

YAML
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 自动将密码编写到日志,但应避免有意将密码打印到日志。

属性名称类型说明
secretsobject对于工作流程运行中的每个作业,此上下文都是相同的。 您可以从作业中的任何步骤访问此上下文。 此对象包含下面列出的所有属性。
secrets.GITHUB_TOKENstring为每个工作流程运行自动创建的令牌。 有关详细信息,请参阅“自动令牌身份验证”。
secrets.<secret_name>string特定机密的值。

secrets 上下文的示例内容

secrets 上下文的以下示例内容显示自动 GITHUB_TOKEN,以及可用于工作流运行的两个其他机密。

{
  "github_token": "***",
  "NPM_TOKEN": "***",
  "SUPERSECRET": "***"
}

secrets 上下文的示例用法

此示例工作流程使用 labeler 操作,该操作需要 GITHUB_TOKEN 作为 repo-token 输入参数的值:

YAML
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 上下文包含有关当前作业的矩阵执行策略的信息。

属性名称类型说明
strategyobject此上下文针对工作流程运行中的每项作业而改变。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的所有属性。
strategy.fail-fastboolean如果为 true,当矩阵中的任何作业失败时,则取消所有正在进行的作业。 有关详细信息,请参阅 GitHub Actions 的工作流语法
strategy.job-indexnumber矩阵中当前作业的索引。 注意:此数字是从零开始的数字。 矩阵中的第一个作业索引为 0
strategy.job-totalnumber矩阵中的作业总数。 注意:此数字不是从零开始的数字。 例如,对于具有四个作业的矩阵,job-total 的值为 4
strategy.max-parallelnumber使用 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 属性为矩阵中的每个作业设置日志文件的唯一名称。

YAML
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 上下文包含工作流程文件中定义的适用于当前作业的矩阵属性。 例如,如果使用 osnode 键配置矩阵,则 matrix 上下文对象包含 osnode 属性,该属性具有用于当前作业的值。

matrix 上下文中没有标准属性,只有工作流文件中定义的属性。

属性名称类型说明
matrixobject此上下文仅适用于矩阵中的作业,并且对于工作流运行中的每个作业都会发生更改。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的属性。
matrix.<property_name>string矩阵属性的值。

matrix 上下文的示例内容

matrix 上下文的以下示例内容来自具有工作流中定义的 osnode 矩阵属性的矩阵中的作业。 该作业正在执行 ubuntu-latest OS 和 Node.js 版本 16 的矩阵合并。

{
  "os": "ubuntu-latest",
  "node": 16
}

matrix 上下文的示例用法

此示例工作流创建包含 osnode 键的矩阵。 它使用 matrix.os 属性为每个作业设置运行器类型,并使用 matrix.node 属性为每个作业设置 Node.js 版本。

YAML
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 的工作流语法”。

属性名称类型说明
needsobject仅为具有相关作业的工作流程运行填充此上下文,并为工作流程运行中的每个作业填充此上下文。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的所有属性。
needs.<job_id>object当前作业依赖的单个作业。
needs.<job_id>.outputsobject当前作业依赖的作业的输出集。
needs.<job_id>.outputs.<output name>string当前作业依赖的作业的特定输出值。
needs.<job_id>.resultstring当前作业依赖的作业的结果。 可能的值为 successfailurecancelledskipped

needs 上下文的示例内容

needs 上下文的以下示例内容显示了当前作业所依赖的两个作业的信息。

{
  "build": {
    "result": "success",
    "outputs": {
      "build_id": "ABC123"
    }
  },
  "deploy": {
    "result": "failure",
    "outputs": {}
  }
}

needs 上下文的示例用法

此示例工作流有三个作业:一个 build 作业(执行生成),一个 deploy 作业(需要 build 作业)以及一个 debug 作业(需要 builddeploy 作业且仅当工作流中有故障时运行)。 deploy 作业还使用 needs 上下文来访问 build 作业中的输出。

YAML
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 传递。 对于手动触发的工作流,输入是在工作流的 workflow_dispatch 事件配置中定义的。

inputs 上下文中没有标准属性,只有工作流文件中定义的属性。

属性名称类型说明
inputsobject此上下文仅在可重用工作流workflow_dispatch 事件触发的工作流中可用。 您可以从工作流程中的任何作业或步骤访问此上下文。 此对象包含下面列出的属性。
inputs.<name>stringnumberboolean从外部工作流传递的每个输入值。

inputs 上下文的示例内容

inputs 上下文的以下示例内容来自已定义 build_iddeploy_targetperform_deploy 输入的工作流。

{
  "build_id": 123456768,
  "deploy_target": "deployment_sys_1a",
  "perform_deploy": true
}

可重用工作流中 inputs 上下文的示例用法

此示例可重用工作流使用 inputs 上下文从调用方工作流获取传递到可重用工作流的 build_iddeploy_targetperform_deploy 输入的值。

YAML
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 }}
    steps:
      - name: Deploy build to target
        run: deploy --build ${{ inputs.build_id }} --target ${{ inputs.deploy_target }}

手动触发的工作流中 inputs 上下文的示例用法

这个由 workflow_dispatch 事件触发的示例工作流使用 inputs 上下文来获取传递给工作流的 build_iddeploy_targetperform_deploy 输入的值。

YAML
on:
  workflow_dispatch:
    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 }}
    steps:
      - name: Deploy build to target
        run: deploy --build ${{ inputs.build_id }} --target ${{ inputs.deploy_target }}