Nota: Los ejecutores hospedados en GitHub no son compatibles con GitHub Enterprise Server actualmente. Puedes encontrar más información sobre el soporte que se tiene planeado en el futuro en el Itinerario público de GitHub.
About contexts
Contexts are a way to access information about workflow runs, runner environments, jobs, and steps. Each context is an object that contains properties, which can be strings or other objects.
Contexts, objects, and properties will vary significantly under different workflow run conditions. For example, the matrix
context is only populated for jobs in a build matrix.
You can access contexts using the expression syntax. For more information, see "Expressions."
${{ <context> }}
Advertencia: Cuando crees flujos de trabajo y acciones siempre debes considerar si tu código podría ejecutar entradas no confiables de atacantes potenciales. Se tratará a algunos contextos como una entrada no confiable, ya que un atacante podrían insertar su propio contenido malintencionado. Para obtener más información, consulta la sección "Entenderel riesgo de las inyecciones de scripts".
Context name | Type | Description |
---|---|---|
github | object | Information about the workflow run. For more information, see github context. |
env | object | Contains environment variables set in a workflow, job, or step. For more information, see env context. |
job | object | Information about the currently running job. For more information, see job context. |
steps | object | Information about the steps that have been run in the current job. For more information, see steps context. |
runner | object | Information about the runner that is running the current job. For more information, see runner context. |
secrets | object | Contains the names and values of secrets that are available to a workflow run. For more information, see secrets context. |
strategy | object | Information about the matrix execution strategy for the current job. For more information, see strategy context. |
matrix | object | Contains the matrix properties defined in the workflow that apply to the current job. For more information, see matrix context. |
needs | object | Contains the outputs of all jobs that are defined as a dependency of the current job. For more information, see needs context. |
As part of an expression, you can access context information using one of two syntaxes.
- Index syntax:
github['sha']
- Property dereference syntax:
github.sha
In order to use property dereference syntax, the property name must:
- start with
a-Z
or_
. - be followed by
a-Z
0-9
-
or_
.
Determining when to use contexts
GitHub Actions incluye una colección de variables que se llama contextos y una recopilación de variables similar que se llaman variables de ambiente predeterminadas. Estas variables se pretenden utilizar en puntos diferentes del flujo de trabajo:
- Variables de ambiente predeterminadas: Estas variables existen únicamente en el ejecutor que está ejecutando tu job. Para obtener más información, consulta la sección "Variables de ambiente predeterminadas."
- Contextos: Puedes utilizar la mayoría de los contextos en cualquier punto de tu flujo de trabajo, incluyendo cuando no estén disponibles las variables de ambiente predeterminadas. Por ejemplo, puedes utilizar contextos con expresiones para llevar a cabo un procesamiento inicial antes de que el job se enrute a un ejecutor para su exclusión; esto te permite utilizar un contexto con la palabra clave condicional
if
para determinar si se debería ejecutar un paso. Una vez que el job se esté ejecutando, también debes recuperar las variables de contexto para el ejecutor que está ejecutando el trabajo, tal comorunner.os
. Para encontrar más detalles de dónde puedes utilizar contextos diversos dentro de un flujo de trabajo, consulta "Disponibilidad de contexto".
El siguiente ejemplo ilustra cómo estos tipos de variables de ambiente diferentes pueden utilizarse juntas en el job:
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"
En este ejemplo, el contexto de la declaración if
verifica el contexto de github.ref
para determinar el nombre de rama actual; si el nombre es refs/heads/main
, entonces los siguientes pasos subsecuentes se ejecutarán. El if
verifica que se encuentre procesado por GitHub Actions, y que el job solo se envíe al ejecutor si el resultado es Verdadero
. Una vez que se envía el job al ejecutor, se ejecuta el paso y se refiere al ambiente de variables $GITHUB_REF
para el ejecutor.
Context availability
Different contexts are available throughout a workflow run. For example, the secrets
context may only be used at certain places within a job.
In addition, some functions may only be used in certain places. For example, the hashFiles
function is not available everywhere.
The following table indicates where each context and special function can be used within a workflow. Unless listed below, a function can be used anywhere.
Path | Context | Special functions |
---|---|---|
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 |
Example: printing context information to the log
You can print the contents of contexts to the log for debugging. The toJSON
function is required to pretty-print JSON objects to the log.
Advertencia: Cuando utilizas todo el contexto de GitHub
, cuida que incluya la información sensible tal como un github.token
. GitHub enmascara secretos cuando se imprimen en la consola, pero debes tener cuidado cuando exportes o imprimas el contexto.
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
context
The github
context contains information about the workflow run and the event that triggered the run. You can also read most of the github
context data in environment variables. For more information about environment variables, see "Using environment variables."
Advertencia: Cuando utilizas todo el contexto de GitHub
, cuida que incluya la información sensible tal como un github.token
. GitHub enmascara secretos cuando se imprimen en la consola, pero debes tener cuidado cuando exportes o imprimas el contexto.
Advertencia: Cuando crees flujos de trabajo y acciones siempre debes considerar si tu código podría ejecutar entradas no confiables de atacantes potenciales. Se tratará a algunos contextos como una entrada no confiable, ya que un atacante podrían insertar su propio contenido malintencionado. Para obtener más información, consulta la sección "Entenderel riesgo de las inyecciones de scripts".
Property name | Type | Description |
---|---|---|
github | object | The top-level context available during any job or step in a workflow. This object contains all the properties listed below. |
github.action | string | The name of the action currently running, or the id of a step. GitHub removes special characters, and uses the name __run when the current step runs a script without an id . 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 . Similarly, the second invocation of actions/checkout will be actionscheckout2 . |
github.action_path | string | The path where an action is located. This property is only supported in composite actions. You can use this path to access files located in the same repository as the action. |
github.action_ref | string | For a step executing an action, this is the ref of the action being executed. For example, v2 . |
github.action_repository | string | For a step executing an action, this is the owner and repository name of the action. For example, actions/checkout . |
github.actor | string | The username of the user that initiated the workflow run. |
github.api_url | string | The URL of the GitHub REST API. |
github.base_ref | string | The base_ref or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target . |
github.env | string | Path on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "Workflow commands for GitHub Actions." |
github.event | object | The full event webhook payload. You can access individual properties of the event using this context. This object is identical to the webhook payload of the event that triggered the workflow run, and is different for each event. The webhooks for each GitHub Actions event is linked in "Events that trigger workflows." For example, for a workflow run triggered by the push event, this object contains the contents of the push webhook payload. |
github.event_name | string | The name of the event that triggered the workflow run. |
github.event_path | string | The path to the file on the runner that contains the full event webhook payload. |
github.graphql_url | string | The URL of the GitHub GraphQL API. |
github.head_ref | string | The head_ref or source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either pull_request or pull_request_target . |
github.job | string | The job_id of the current job. |
github.ref | string | The branch or tag ref that triggered the workflow run. For branches this is the format refs/heads/<branch_name> , and for tags it is refs/tags/<tag_name> . |
github.path | string | Path on the runner to the file that sets system PATH variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see "Workflow commands for GitHub Actions." |
github.repository | string | The owner and repository name. For example, Codertocat/Hello-World . |
github.repository_owner | string | The repository owner's name. For example, Codertocat . |
github.repositoryUrl | string | The Git URL to the repository. For example, git://github.com/codertocat/hello-world.git . |
github.retention_days | string | The number of days that workflow run logs and artifacts are kept. |
github.run_id | string | Un número único para cada ejecución de flujo de trabajo dentro de un repositorio. Este número no cambia si vuelves a ejecutar el flujo de trabajo. |
github.run_number | string | Un número único para cada ejecución de un flujo de trabajo particular en un repositorio. Este número comienza en 1 para los flujos de trabajo que se ejecutan primero, e incrementa con cada ejecución nueva. Este número no cambia si vuelves a ejecutar el flujo de trabajo. |
github.run_attempt | string | 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 | string | The URL of the GitHub server. For example: https://github.com . |
github.sha | string | The commit SHA that triggered the workflow run. |
github.token | string | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the GITHUB_TOKEN secret. For more information, see "Automatic token authentication." |
github.workflow | string | The name of the workflow. If the workflow file doesn't specify a name , the value of this property is the full path of the workflow file in the repository. |
github.workspace | string | The default working directory on the runner for steps, and the default location of your repository when using the checkout action. |
Example contents of the github
context
The following example context is from a workflow run triggered by the push
event. The event
object in this example has been truncated because it is identical to the contents of the push
webhook payload.
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"
}
Example usage of the github
context
This example workflow uses the github.event_name
context to run a job only if the workflow run was triggered by the pull_request
event.
name: Run CI
on: [push, pull_request]
jobs:
normal_ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run normal CI
run: ./run-tests
pull_request_ci:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'pull_request' }}
steps:
- uses: actions/checkout@v2
- name: Run PR CI
run: ./run-additional-pr-ci
env
context
The env
context contains environment variables that have been set in a workflow, job, or step. For more information about setting environment variables in your workflow, see "Workflow syntax for GitHub Actions."
The env
context syntax allows you to use the value of an environment variable in your workflow file. You can use the env
context in the value of any key in a step except for the id
and uses
keys. For more information on the step syntax, see "Workflow syntax for GitHub Actions."
If you want to use the value of an environment variable inside a runner, use the runner operating system's normal method for reading environment variables.
Property name | Type | Description |
---|---|---|
env | object | This context changes for each step in a job. You can access this context from any step in a job. This object contains the properties listed below. |
env.<env_name> | string | The value of a specific environment variable. |
Example contents of the env
context
The contents of the env
context is a mapping of environment variable names to their values. The context's contents can change depending on where it is used in the workflow run.
{
"first_name": "Mona",
"super_duper_var": "totally_awesome"
}
Example usage of the env
context
This example workflow shows how the env
context can be configured at the workflow, job, and step levels, as well as using the context in steps.
Cuando se define más de una variable de ambiente con el mismo nombre, GitHub utiliza la más específica. Por ejemplo, una variable de ambiente definida en un paso anulará aquellas de los jobs y flujos de trabajo con el mismo nombre, mientras ejecuta el paso. Una variable definida para un trabajo anulará aquella de un flujo de trabajo si tienen el mismo nombre, mientras ejecuta el job.
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
context
The job
context contains information about the currently running job.
Property name | Type | Description |
---|---|---|
job | object | This context changes for each job in a workflow run. You can access this context from any step in a job. This object contains all the properties listed below. |
job.container | object | Information about the job's container. For more information about containers, see "Workflow syntax for GitHub Actions." |
job.container.id | string | The ID of the container. |
job.container.network | string | The ID of the container network. The runner creates the network used by all containers in a job. |
job.services | object | The service containers created for a job. For more information about service containers, see "Workflow syntax for GitHub Actions." |
job.services.<service_id>.id | string | The ID of the service container. |
job.services.<service_id>.network | string | The ID of the service container network. The runner creates the network used by all containers in a job. |
job.services.<service_id>.ports | object | The exposed ports of the service container. |
job.status | string | The current status of the job. Possible values are success , failure , or cancelled . |
Example contents of the job
context
This example job
context uses a PostgreSQL service container with mapped ports. If there are no containers or service containers used in a job, the job
context only contains the status
property.
{
"status": "success",
"container": {
"network": "github_network_53269bd575974817b43f4733536b200c"
},
"services": {
"postgres": {
"id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105",
"ports": {
"5432": "49153"
},
"network": "github_network_53269bd575974817b43f4733536b200c"
}
}
}
Example usage of the job
context
This example workflow configures a PostgreSQL service container, and automatically maps port 5432 in the service container to a randomly chosen available port on the host. The job
context is used to access the number of the port that was assigned on the host.
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@v2
- run: pg_isready -h localhost -p ${{ job.services.postgres.ports[5432] }}
- run: ./run-tests
steps
context
The steps
context contains information about the steps in the current job that have an id
specified and have already run.
Property name | Type | Description |
---|---|---|
steps | object | This context changes for each step in a job. You can access this context from any step in a job. This object contains all the properties listed below. |
steps.<step_id>.outputs | object | The set of outputs defined for the step. For more information, see "Metadata syntax for GitHub Actions." |
steps.<step_id>.conclusion | string | The result of a completed step after continue-on-error is applied. Possible values are success , failure , cancelled , or skipped . When a continue-on-error step fails, the outcome is failure , but the final conclusion is success . |
steps.<step_id>.outcome | string | The result of a completed step before continue-on-error is applied. Possible values are success , failure , cancelled , or skipped . When a continue-on-error step fails, the outcome is failure , but the final conclusion is success . |
steps.<step_id>.outputs.<output_name> | string | The value of a specific output. |
Example contents of the steps
context
This example steps
context shows two previous steps that had an id
specified. The first step had the id
named checkout
, the second generate_number
. The generate_number
step had an output named random_number
.
{
"checkout": {
"outputs": {},
"outcome": "success",
"conclusion": "success"
},
"generate_number": {
"outputs": {
"random_number": "1"
},
"outcome": "success",
"conclusion": "success"
}
}
Example usage of the steps
context
This example workflow generates a random number as an output in one step, and a later step uses the steps
context to read the value of that output.
name: Generate random failure
on: push
jobs:
randomly-failing-job:
runs-on: ubuntu-latest
steps:
- id: checkout
uses: actions/checkout@v2
- 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
context
The runner
context contains information about the runner that is executing the current job.
Property name | Type | Description |
---|---|---|
runner | object | This context changes for each job in a workflow run. This object contains all the properties listed below. |
runner.name | string | El nombre del ejecutor que ejecuta el job. |
runner.os | string | El sistema operativo del ejecutor que ejecuta el trabajo. Los valores posibles son Linux , Windows o macOS . |
runner.temp | string | La ruta a un directorio temporal en el ejecutor. Este directorio se vacía al inicio y al final de cada job. Nota que los archivos no se eliminarán si la cuenta de usuario del ejecutor no tiene permisos para borrarlos. |
runner.tool_cache | string | La ruta al directorio que contiene las herramientas preinstaladas para los ejecutores hospedados en GitHub. Para obtener más información, consulta la sección "Acerca de los ejecutores hospedados en GitHub". |
Example contents of the runner
context
The following example context is from a Linux GitHub-hosted runner.
{
"os": "Linux",
"arch": "X64",
"name": "GitHub Actions 2",
"tool_cache": "/opt/hostedtoolcache",
"temp": "/home/runner/work/_temp"
}
Example usage of the runner
context
This example workflow uses the runner
context to set the path to the temporary directory to write logs, and if the workflow fails, it uploads those logs as artifact.
name: Build
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- 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@v2
with:
name: Build failure logs
path: ${{ runner.temp }}/build_logs
secrets
context
The secrets
context contains the names and values of secrets that are available to a workflow run. The secrets
context is not available for composite actions. For more information about secrets, see "Encrypted secrets."
GITHUB_TOKEN
is a secret that is automatically created for every workflow run, and is always included in the secrets
context. For more information, see "Automatic token authentication."
Advertencia: GitHub redacta automáticamente secretos impresos en el registro, pero debes evitar imprimir secretos en el registro intencionalmente.
Property name | Type | Description |
---|---|---|
secrets | object | This context is the same for each job in a workflow run. You can access this context from any step in a job. This object contains all the properties listed below. |
secrets.GITHUB_TOKEN | string | Automatically created token for each workflow run. For more information, see "Automatic token authentication." |
secrets.<secret_name> | string | The value of a specific secret. |
Example contents of the secrets
context
The following example contents of the secrets
context shows the automatic GITHUB_TOKEN
, as well as two other secrets available to the workflow run.
{
"github_token": "***",
"NPM_TOKEN": "***",
"SUPERSECRET": "***"
}
Example usage of the secrets
context
Este flujo de trabajo de ejemplo usa la acción de etiquetadora , que requiere el GITHUB_TOKEN
como el valor para el parámetro de entrada repo-token
:
name: Pull request labeler
on: [ pull_request_target ]
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: actions/labeler@v2
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
strategy
context
For workflows with a build matrix, the strategy
context contains information about the matrix execution strategy for the current job.
Property name | Type | Description |
---|---|---|
strategy | object | This context changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. |
strategy.fail-fast | string | When true , all in-progress jobs are canceled if any job in a build matrix fails. For more information, see "Workflow syntax for GitHub Actions." |
strategy.job-index | string | The index of the current job in the build matrix. Note: This number is a zero-based number. The first job's index in the build matrix is 0 . |
strategy.job-total | string | The total number of jobs in the build matrix. Note: This number is not a zero-based number. For example, for a build matrix with four jobs, the value of job-total is 4 . |
strategy.max-parallel | string | The maximum number of jobs that can run simultaneously when using a matrix job strategy. For more information, see "Workflow syntax for GitHub Actions." |
Example contents of the strategy
context
The following example contents of the strategy
context is from a build matrix with four jobs, and is taken from the final job. Note the difference between the zero-based job-index
number, and job-total
which is not zero-based.
{
"fail-fast": true,
"job-index": 3,
"job-total": 4,
"max-parallel": 4
}
Example usage of the strategy
context
This example workflow uses the strategy.job-index
property to set a unique name for a log file for each job in a build matrix.
name: Test matrix
on: push
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
test-group: [1, 2]
node: [14, 16]
steps:
- uses: actions/checkout@v2
- run: npm test > test-job-${{ strategy.job-index }}.txt
- name: Upload logs
uses: actions/upload-artifact@v2
with:
name: Build log for job ${{ strategy.job-index }}
path: test-job-${{ strategy.job-index }}.txt
matrix
context
For workflows with a build matrix, the matrix
context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a build matrix with the os
and node
keys, the matrix
context object includes the os
and node
properties with the values that are being used for the current job.
There are no standard properties in the matrix
context, only those which are defined in the workflow file.
Property name | Type | Description |
---|---|---|
matrix | object | This context is only available for jobs in a build matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. |
matrix.<property_name> | string | The value of a matrix property. |
Example contents of the matrix
context
The following example contents of the matrix
context is from a job in a build matrix that has the os
and node
matrix properties defined in the workflow. The job is executing the matrix combination of an ubuntu-latest
OS and Node.js version 16
.
{
"os": "ubuntu-latest",
"node": 16
}
Example usage of the matrix
context
This example workflow creates a build matrix with os
and node
keys. It uses the matrix.os
property to set the runner type for each job, and uses the matrix.node
property to set the Node.js version for each job.
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@v2
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
needs
context
The needs
context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."
Property name | Type | Description |
---|---|---|
needs | object | This context is only populated for workflow runs that have dependent jobs, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. |
needs.<job_id> | object | A single job that the current job depends on. |
needs.<job_id>.outputs | object | The set of outputs of a job that the current job depends on. |
needs.<job_id>.outputs.<output name> | string | The value of a specific output for a job that the current job depends on. |
needs.<job_id>.result | string | The result of a job that the current job depends on. Possible values are success , failure , cancelled , or skipped . |
Example contents of the needs
context
The following example contents of the needs
context shows information for two jobs that the current job depends on.
{
"build": {
"result": "success",
"outputs": {
"build_id": "ABC123"
}
},
"deploy": {
"result": "failure",
"outputs": {}
}
}
Example usage of the needs
context
This example workflow has three jobs: a build
job that does a build, a deploy
job that requires the build
job, and a debug
job that requires both the build
and deploy
jobs and runs only if there is a failure in the workflow. The deploy
job also uses the needs
context to access an output from the build
job.
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@v2
- 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@v2
- run: ./deploy --build ${{ needs.build.outputs.build_id }}
debug:
needs: [build, deploy]
runs-on: ubuntu-latest
if: ${{ failure() }}
steps:
- uses: actions/checkout@v2
- run: ./debug