Workflow commands for OpenTestFactory Orchestrator Plugins¶
You can use workflow commands when running shell commands in a workflow or in a plugin’s code.
About workflow commands¶
Providers plugins can communicate with the execution environment to set environment variables, output values used by other plugins, add debug messages to the output logs, and other tasks.
Most workflow commands use the echo
command in a specific format, while
others are invoked by writing to a file. For more information, see
“Environment Files”.
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
Note
Workflow command and parameter names are case-insensitive.
Warning
If you are using Command Prompt, omit double quote characters
("
) when using workflow commands.
You can use the set-output
command in your workflow to set the same value:
- name: Set selected color
run: echo '::set-output name=SELECTED_COLOR::green'
id: random-color-generator
- name: Get color
run: echo 'The selected color is' ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}
Attaching an artifact¶
::attach type={type}::{path}
Sets a function’s attachment. You can optionally provide a type further describing the attachment.
Example¶
echo "::attach::foobar.yaml"
Sending an artifact to an execution environment¶
::put file={name}::{path}
Copies an artifact to the execution environment. name
must be a file described
in the workflow’s resources.files
section.
Example¶
echo "::put file=foo.json::where/to/put/bar.json"
Setting an output parameter¶
::set-output name={name}::{value}
Sets a function’s output parameter.
Optionally, you can also declare output parameters in a plugin’s metadata file. For more information, see “Metadata syntax for OpenTestFactory Orchestrator Plugins.”
Example¶
echo "::set-output name=action_fruit::strawberry"
Setting a debug message¶
::debug::{message}
Prints a debug message to the log. You must create a secret named
ACTIONS_STEP_DEBUG
with the value true
to see the debug messages set by
this command in the log. For more information, see “Managing a workflow run.”
Example¶
echo "::debug::Set the Octocat variable"
Setting a warning message¶
::warning file={name},line={line},col={col}::{message}
Creates a warning message and prints the message to the log. You can
optionally provide a filename (file
), line number (line
), and column
(col
) number where the warning occurred.
Example¶
echo "::warning file=app.js,line=1,col=5::Missing semicolon"
Setting an error message¶
::error file={name},line={line},col={col}::{message}
Creates an error message and prints the message to the log. You can optionally
provide a filename (file
), line number (line
), and column (col
) number
where the error occurred.
Example¶
echo "::error file=app.js,line=10,col=15::Something went wrong"
Masking a value in log¶
::add-mask::{value}
Masking a value prevents a string or variable from being printed in the log.
Each masked word separated by whitespace is replaced with the *
character.
You can use an environment variable or string for the mask’s value
.
The masking starts right after the masking command and lasts until the job ends.
Example masking a string¶
When you print "I'm Mona The Octocat"
in the log, you’ll see "I'm ***"
.
echo "::add-mask::Mona The Octocat"
echo "I'm Mona The Octocat"
Example masking an environment variable¶
When you print the variable MY_NAME
or the value "Mona The Octocat"
in the
log, you’ll see "***"
instead of "Mona The Octocat"
.
MY_NAME="Mona The Octocat"
echo "::add-mask::$MY_NAME"
echo "$MY_NAME"
Example masking a string in the middle of a script¶
When you print something after a masking command, the values are masked.
jobs:
masking-demo:
- runs-on: windows
- steps:
- run: echo mona the octocat
- run: echo ::add-mask::mona
- run: echo mona the octocat
- run: |
echo mona the octocat
echo ::add-mask::octocat
echo mona the octocat
In your execution log you will see:
mona the octocat # no mask in effect
*** the octocat # first mask applies
*** the octocat # first mask still applies, the second is not in effect
*** the *** # both masks are in effect
Stopping and starting workflow commands¶
::stop-commands::{endtoken}
Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command. For example, you could stop logging to output an entire script that has comments.
To stop the processing of workflow commands, pass a unique token to stop-commands
.
To resume processing workflow commands, pass the same token that you used to stop
workflow commands.
Warnings
Make sure the token you are using is randomly generated and unique for each run.
::{endtoken}::
Example stopping workflow commands¶
echo "::stop-commands::pause-logging"
To start workflow commands, pass the token that you used to stop workflow commands.
echo "::pause-logging::"
Example stopping and starting workflow commands¶
jobs:
workflow-command-job:
runs-on: linux
steps:
- name: disable workflow commands
- run: |
echo "::warning::this is a warning"
hash=$RANDOM
echo "::stop-commands::${hash}"
echo "::warning::this will NOT be a warning"
echo "::${hash}::"
echo "::warning::this is a warning again"
Environment Files¶
During the execution of a workflow, the execution environment generates temporary files that can be used to perform certain tasks. The path to these files are exposed via environment variables. You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines.
Setting an environment variable¶
echo "{name}={value}" >> $OPENTF_VARIABLES
echo set {name}={value}>>%OPENTF_VARIABLES%
You can make an environment variable available to any subsequent steps in a workflow
job by defining or updating the environment variable and writing this to the
OPENTF_VARIABLES
environment file. The step that creates or updates the environment
variables does not have access to the new value, but all subsequent steps in a job will
have access. The names of environment variables are case-sensitive, and you can include
punctuation.
Example¶
jobs:
set_var:
runs-on: linux
steps:
- name: Set the value
run: |
echo "action_state=yellow" >> $OPENTF_VARIABLES
- name: Use the value
run: |
echo "$action_state" # This will output 'yellow'