Context and expression syntax for workflows¶
You can access context information and evaluate expressions in workflows.
About contexts and expressions¶
You can use expressions to programmatically set variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators.
Expressions are commonly used with the conditional if
keyword in a workflow file to
determine whether a step should run. When an if
conditional is true
, the step will run.
You need to use specific syntax to tell the OpenTestFactory orchestrator to evaluate an expression rather than treat it as a string.
${{ <expression> }}
When you use expressions in an if
conditional, you may omit the expression syntax
(${{ }}
) because the orchestrator automatically evaluates the if
conditional as an
expression. For more information about if
conditionals, see
“Workflow syntax for OpenTestFactory orchestrator.”
Warning
When creating workflows and provider tasks, you should always consider whether your code might execute untrusted input from possible attackers. Certain contexts should be treated as untrusted input, as an attacker could insert their own malicious content. For more information, see “Understanding the risk of script injections.”
Example expression in an if
conditional¶
steps:
- run: dir /s
if: runner.os == 'windows' # or: ${{ runner.os == 'windows' }}
Example setting an environment variable¶
variables:
my_env_var: ${{ <expression> }}
Contexts¶
Contexts are a way to access information about workflow runs, execution environments, jobs, and steps. Contexts use the expression syntax.
${{ <context> }}
Context name | Type | Description |
---|---|---|
opentf |
object |
Information about the workflow run. For more information, see opentf context. |
variables |
object |
Contains environment variables set in a workflow, job, or step. For more information, see variables context. |
resources |
object |
Information about the resources set in a workflow. For more information, see resources context. |
job |
object |
Information about the currently executing job. For more information, see job context. |
steps |
object |
Information about the steps that have been run in this job. For more information, see steps context. |
runner |
object |
Information about the execution environment that is running the current job. For more information, see runner context. |
needs |
object |
Enables access to the outputs of all jobs that are defined as a dependency of the current job. For more information, see needs context. |
inputs |
object |
Contains the inputs of a reusable or manually triggered workflow. For more information, see inputs context. |
As part of an expression, you may access context information using one of two syntaxes.
- Index syntax:
opentf['job']
- Property dereference syntax:
opentf.job
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¶
The OpenTestFactory orchestrator includes a collection of variables called contexts and a similar collection of variables called default environment variables. These variables are intended for use at different points in the workflow:
-
Default environment variables: These variables exist only on the runner that is executing your job. For more information, see “Default environment variables.”
-
Contexts: You can use most contexts at any point in your workflow, including when default environment variables would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to an execution environment for execution; this allows you to use a context with the conditional
if
keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the execution environment that is executing the job, such asrunner.os
. For details of where you can use various contexts within a workflow, see “Context availability.”
The following example demonstrates how these different types of environment variables can be used together in a job:
metdata:
name: CI
jobs:
prod-check:
if: ${{ opentf.actor == 'octocat' }}
runs-on: linux
steps:
- run: echo "Deploying to production server on behalf of $OPENTF_ACTOR"
In this example, the if
statement checks the opentf.actor
context to determine the
caller’s name; if the name is octocat
, then the subsequent steps are executed. The
if
check is processed by the OpenTestFactory orchestrator, and the job is only sent to the
execution environment if the result is true. Once the job is sent to the execution
environment, the step is executed and refers to the $OPENTF_ACTOR
environment variable
from the execution environment.
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 success()
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.
Workflow key | Context | Special functions |
---|---|---|
variables |
opentf , secrets , inputs |
|
jobs.<job_id>.continue-on-error |
opentf , needs , inputs |
|
jobs.<job_id>.defaults.run |
opentf , needs , variables , inputs |
|
jobs.<job_id>.variables |
opentf , needs , secrets , inputs |
|
jobs.<job_id>.if |
opentf , needs , inputs |
always , cancelled , success , failure |
jobs.<job_id>.name |
opentf , needs , inputs |
|
jobs.<job_id>.outputs.<output_id> |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.runs-on |
opentf , needs , inputs |
|
jobs.<job_id>.secrets.<secrets_id> |
opentf , needs , secrets , inputs |
|
jobs.<job_id>.steps.continue-on-error |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.steps.variables |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.steps.if |
opentf , needs , job , runner , variables , steps, inputs |
always , cancelled , success , failure |
jobs.<job_id>.steps.name |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.steps.run |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.steps.timeout-minutes |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.steps.with |
opentf , needs , job , runner , variables , secrets , steps , inputs , resources |
|
jobs.<job_id>.steps.working-directory |
opentf , needs , job , runner , variables , secrets , steps , inputs |
|
jobs.<job_id>.timeout-minutes |
opentf , needs , inputs |
|
jobs.<job_id>.with.<with_id> |
opentf , needs , inputs , resources |
opentf
context¶
The opentf
context contains information about the workflow run and the event that
triggered the run. You can read most of the opentf
context data in environment variables.
For more information about environment variables, see
“Using environment variables.”
Warning
When using the whole opentf
context, be mindful that it includes sensitive information
such as opentf.token
. The orchestrator masks secrets when they are printed to the
console, but you should be cautious when exporting or printing the context
.
Property name | Type | Description |
---|---|---|
opentf |
object |
The top-level context available during any job or step in a workflow. |
opentf.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. |
opentf.namespace |
string |
The name of the namespace the workflow belongs to. |
opentf.job |
string |
The job_id of the current job. |
opentf.actor |
string |
The login of the user that initiated the workflow run. |
opentf.token |
string |
A token to authenticate on behalf of the orchestrator plugin. |
opentf.step |
string |
The name of the step currently running. The orchestrator removes special characters or uses the name run when the current step runs a script. If you use the same function more than once in the same job, the name will include a suffix with the sequence number. For example, the first script you run will have the name run1 , and the second script will be named run2 . Similarly, the second invocation of actions/checkout will be actionscheckout2 . |
Example contents of the opentf
context¶
The following example context is from a workflow run triggered by the push event.
Note
This context is an example only. The content 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",
"actor": "octocat",
"workflow": "Context testing",
"namespace": "default",
"step": "run12"
}
Example usage of the opentf
context¶
This example workflow uses the opentf.name
context to run a job only if the workflow was
triggered by the expected actor.
metadata:
name: Run CI
jobs:
normal_ci:
runs-on: linux
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- name: Run normal CI
run: ./run-tests
post_ci:
needs: normal_ci
runs-on: linux
if: ${{ opentf.actor == 'octocat' }}
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- name: Run PR CI
run: ./run-additional-post-ci
variables
context¶
The variables
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 OpenTestFactory orchestrator.”
The variables
context syntax allows you to use the value of an environment variable in
your workflow file. You can use the variables
context in any key in a step except for
the generator
, id
, and uses
keys. For more information on the step syntax, see
“Workflow syntax for OpenTestFactory orchestrator.”
If you want to use the value of an environment variable inside an execution environment, use the execution environment operating system’s normal method for reading environment variables.
Property name | Type | Description |
---|---|---|
variables |
object |
This context changes for each step in a job. You can access this context from any step in a job. |
variables.<var name> |
string |
The value of a specific environment variable. |
Example contents of the variables
context¶
The content of the variables
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 variables
context¶
This example workflow shows how the variables
context can be configured at the workflow,
job, and step levels, as well as using the context in steps.
When more than one environment variable is defined with the same name, the OpenTestFactory orchestrator uses the most specific environment variable. For example, an environment variable defined in a step will override job and workflow variables with the same name, while the step executes. A variable defined for a job will override a workflow variable with the same name, while the job executes.
metadata:
name: Hi Mascot
variables:
mascot: Mona
super_duper_var: totally_awesome
jobs:
windows_job:
runs-on: windows
steps:
- run: echo Hi ${{ variables.mascot }} # Hi Mona
- run: echo Hi ${{ variables.mascot }} # Hi Octocat
variables:
mascot: Octocat
linux_job:
runs-on: linux
variables:
mascot: Tux
steps:
- run: echo 'Hi ${{ variables.mascot }}' # Hi Tux
resources
context¶
The resources
context contains resources that have been set in a workflow. For more
information about setting resources in your workflow, see “Workflow syntax for OpenTestFactory orchestrator.”
The resources
context syntax allows you to use the resources in your workflow file.
You can only use the resources
context in the value of the with
and name
keys. For
more information on the step syntax, see “Workflow syntax for OpenTestFactory orchestrator.”
Property name | Type | Description |
---|---|---|
resources.<resource type> |
object |
The resource type objects. Possible values are testmanagers , repositories , or files . |
resources.<resource type>.<name> |
object |
The set of properties for the resource. There is at least a name property, the other are resource type dependent. |
Example contents of the resources
context¶
This example resources
context shows two linked files and one defined repository.
{
"files": {
"config1": {
"name": "config1",
"url": "https://cdn.example.com/abcfoo"
},
"config2": {
"name": "config2",
"url": "https://cdn.example.com/defbar"
}
},
"repositories": {
"myrepo": {
"name": "myrepo",
"type": "bitbucket",
"repository": "example/my-example-repo.git",
"endpoint": "https://bitbucket.org"
}
}
}
Example usage of the resources
context¶
This example workflow takes two configuration files and builds the project twice. The configuration files are provided when triggering the workflow, using for example:
opentf-ctl \
run workflow bibuild.yaml \
-f config1=local/conf1.properties \
-f config2=local/conf2.properties
metadata:
name: Build twice
resources:
files:
- config1
- config2
repositories:
- name: myrepo
type: bitbucket
repository: example/my-example-repo.git
endpoint: https://bitbucket.org
jobs:
build:
- uses: actions/checkout@v2
with:
repository: ${{ resources.repositories.myrepo }}
- uses: actions/put-file@v1
with:
file: config1
path: conf/config.properties
- name: Build using first configuration
run: ./build.sh --target target/build-using-first-config
- uses: actions/put-file@v1
with:
file: config2
path: conf/config.properties
- name: Build using second configuration
run: ./build.sh --target target/build-using-second-config
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. |
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 only contains the status property.
{
"status": "success"
}
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. |
steps.<step id>.outputs |
object |
The set of outputs defined for the step. For more information, see “Metadata syntax for OpenTestFactory orchestrator plugins.” |
steps.<step id>.outputs.<output name> |
string |
The value of a specific output. |
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>.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 . |
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
, and 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.
metadata:
name: Generate random failure
jobs:
randomly-failing-job:
runs-on: linux
steps:
- id: checkout
uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- 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 execution environment 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.os |
string |
The operating system of the runner executing the job. Possible values are linux , windows , or macos . |
runner.temp |
string |
The path of the temporary directory for the execution environment. This directory is guaranteed to be empty at the start of each job, even on self-hosted execution environments. |
Example contents of the runner
context¶
The following example context is from a Linux-based execution environment.
{
"os": "linux",
"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 artifacts.
metadata:
name: Build
jobs:
build:
runs-on: linux
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- 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
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 OpenTestFactory orchestrator.”
Property name | Type | Description |
---|---|---|
needs.<job id> |
object |
A single 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>.outputs |
object |
The set of outputs of 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 , or cancelled . |
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.
metadata:
name: Build and deploy
jobs:
build:
runs-on: linux
outputs:
build_id: ${{ steps.build_step.outputs.build_id }}
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- name: Build
id: build_step
run: |
./build
echo "::set-output name=build_id::$BUILD_ID"
deploy:
needs: build
runs-on: linux
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- run: ./deploy --build ${{ needs.build.outputs.build_id }}
debug:
needs: [build, deploy]
runs-on: linux
if: ${{ failure() }}
steps:
- uses: actions/checkout@v2
with:
repository: https://git.example.com/my_repo.git
- run: ./debug
inputs
context¶
The inputs
context contains input properties passed to a function. For reusable workflows,
the input names and types are defined in the workflow_call event configuration of a reusable
workflow, and the input values are passed from jobs.<job_id>.with
in an external workflow
that calls the reusable workflow. For manually triggered workflows, the inputs are defined
in the workflow_dispatch event configuration of a workflow.
There are no standard properties in the inputs
context, only those which are defined in the
workflow file.
Property name | Type | Description |
---|---|---|
inputs |
object |
This context is only available in a function. You can access this context from any step in a function. This object contains the properties listed below. |
inputs.<name> |
string or number or boolean |
Each input value passed from an external workflow. |
Literals¶
As part of an expression, you can use boolean
, null
, number
, or string
data types.
Boolean literals are not case-sensitive, so you can use true or True.
Data type | Literal value |
---|---|
boolean |
true or false |
null |
null |
number |
Any number format supported by JSON. |
string |
You must use single quotes. Escape literal single-quotes with a single quote. |
Example¶
variables:
myNull: ${{ null }}
myBoolean: ${{ false }}
myIntegerNumber: ${{ 711 }}
myFloatNumber: ${{ -9.2 }}
myHexNumber: ${{ 0xff }}
myExponentialNumber: ${{ -2.99-e2 }}
myString: ${{ 'Mona the Octocat' }}
myEscapedString: ${{ 'It''s open source!' }}
Operators¶
Operator | Description | Usage |
---|---|---|
( ) |
Logical grouping | ((foo == 4) || (bar == 5)) && (baz == 6) |
[ ] |
Index | variables['VAR'] |
. |
Property dereference | variables.VAR |
< |
Less than | 12 < 4 |
<= |
Less than or equal | 12 <= 4 |
> |
Greater than | 12 > 4 |
>= |
Greater than or equal | 12 >= 4 |
== |
Equal | variables.VAR == 'foo' |
!= |
Not equal | 12 != 4 |
~= |
Match regular expression | variables.VAR ~= '^abc.*' |
&& |
And | true && false |
|| |
Or | true || false |
The orchestrator performs loose equality comparisons.
- If the types do not match, the orchestrator coerces the type to a number. The orchestrator casts data types to a number using these conversions:
Type | Result |
---|---|
Null | 0 |
Boolean | true returns 1 false returns 0 |
String | Parsed from any legal JSON number format, otherwise NaN .Note: empty string returns 0 . |
Array | NaN |
Object | NaN |
-
A comparison of one
NaN
to anotherNaN
does not result intrue
. For more information, see the “NaN Mozilla docs.” -
The orchestrator ignores the case when comparing strings.
-
For more information on the regular expression syntax, see “Python
re
module.” -
Objects and arrays are only considered equal when they are the same instance.
Job-status check functions¶
You can use the following status check functions as expressions in if
conditionals. If
your if
expression does not contain any of the status functions it will automatically
result in success()
. For more information about if
conditionals, see
“Workflow syntax for OpenTestFactory orchestrator.”
success¶
Returns true
when none of the previous steps have failed or been canceled.
Example¶
steps:
...
- name: The job has succeeded
if: ${{ success() }}
always¶
Always returns true
, even when canceled. A job or step will not run when a critical
failure prevents the task from running. For example, if getting sources failed.
Example¶
if: ${{ always() }}
cancelled¶
Returns true
if the workflow was canceled.
Example¶
if: ${{ cancelled() }}
failure¶
Returns true
when any previous step of a job fails.
Example¶
steps:
...
- name: The job has failed
if: ${{ failure() }}