Note: GitHub Actions was available for GitHub Enterprise Server 2.22 as a limited beta. The beta has ended. GitHub Actions is now generally available in GitHub Enterprise Server 3.0 or later. For more information, see the GitHub Enterprise Server 3.0 release notes.
- For more information about upgrading to GitHub Enterprise Server 3.0 or later, see "Upgrading GitHub Enterprise Server."
- For more information about configuring GitHub Actions after you upgrade, see the documentation for GitHub Enterprise Server 3.0.
Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.
About workflow commands
Actions can communicate with the runner machine to set environment variables, output values used by other actions, add debug messages to the output logs, and other tasks.
Workflow commands use the echo
command in a specific format.
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
Note: Workflow command and parameter names are not case-sensitive.
Warning: If you are using Command Prompt, omit double quote characters ("
) when using workflow commands.
Using workflow commands to access toolkit functions
The actions/toolkit includes a number of functions that can be executed as workflow commands. Use the ::
syntax to run the workflow commands within your YAML file; these commands are then sent to the runner over stdout
. For example, instead of using code to set an output, as below:
core.setOutput('SELECTED_COLOR', 'green');
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 }}"
The following table shows which toolkit functions are available within a workflow:
Toolkit function | Equivalent workflow command |
---|---|
core.addPath | add-path |
core.debug | debug |
core.error | error |
core.endGroup | endgroup |
core.exportVariable | set-env |
core.getInput | Accessible using environment variable INPUT_{NAME} |
core.getState | Accessible using environment variable STATE_{NAME} |
core.isDebug | Accessible using environment variable RUNNER_DEBUG |
core.saveState | save-state |
core.setFailed | Used as a shortcut for ::error and exit 1 |
core.setOutput | set-output |
core.setSecret | add-mask |
core.startGroup | group |
core.warning | warning |
Setting an environment variable
::set-env name={name}::{value}
Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. Environment variables are case-sensitive and you can include punctuation.
Example
echo "::set-env name=action_state::yellow"
Setting an output parameter
::set-output name={name}::{value}
Sets an action's output parameter.
Optionally, you can also declare output parameters in an action's metadata file. For more information, see "Metadata syntax for GitHub Actions."
Example
echo "::set-output name=action_fruit::strawberry"
Adding a system path
::add-path::{path}
Prepends a directory to the system PATH
variable for all subsequent actions in the current job. The currently running action cannot access the new path variable.
Example
echo "::add-path::/path/to/dir"
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 "Enabling debug logging."
Example
echo "::debug::Set the Octocat variable"
Setting a warning message
::warning file={name},line={line},endLine={endLine},title={title}::{message}
Creates a warning message and prints the message to the log. This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.
Parameter | Value |
---|---|
file | Filename |
col | Column number, starting at 1 |
line | Line number, starting at 1 |
Example
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Setting an error message
::error file={name},line={line},endLine={endLine},title={title}::{message}
Creates an error message and prints the message to the log. This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.
Parameter | Value |
---|---|
file | Filename |
col | Column number, starting at 1 |
line | Line number, starting at 1 |
Example
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Grouping log lines
::group::{title}
::endgroup::
Creates an expandable group in the log. To create a group, use the group
command and specify a title
. Anything you print to the log between the group
and endgroup
commands is nested inside an expandable entry in the log.
Example
echo "::group::My title"
echo "Inside group"
echo "::endgroup::"
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
.
Example masking a string
When you print "Mona The Octocat"
in the log, you'll see "***"
.
echo "::add-mask::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"
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.
Warning: Make sure the token you're using is randomly generated and unique for each run. As demonstrated in the example below, you can generate a unique hash of your github.token
for each run.
::{endtoken}::
Example stopping and starting workflow commands
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: disable workflow commands
run: |
echo '::warning:: this is a warning'
echo "::stop-commands::`echo -n ${{ github.token }} | sha256sum | head -c 64`"
echo '::warning:: this will NOT be a warning'
echo "::`echo -n ${{ github.token }} | sha256sum | head -c 64`::"
echo '::warning:: this is a warning again'
Sending values to the pre and post actions
You can use the save-state
command to create environment variables for sharing with your workflow's pre:
or post:
actions. For example, you can create a file with the pre:
action, pass the file location to the main:
action, and then use the post:
action to delete the file. Alternatively, you could create a file with the main:
action, pass the file location to the post:
action, and also use the post:
action to delete the file.
If you have multiple pre:
or post:
actions, you can only access the saved value in the action where save-state
was used. For more information on the post:
action, see "Metadata syntax for GitHub Actions."
The save-state
command can only be run within an action, and is not available to YAML files. The saved value is stored as an environment value with the STATE_
prefix.
This example uses JavaScript to run the save-state
command. The resulting environment variable is named STATE_processID
with the value of 12345
:
console.log('::save-state name=processID::12345')
The STATE_processID
variable is then exclusively available to the cleanup script running under the main
action. This example runs in main
and uses JavaScript to display the value assigned to the STATE_processID
environment variable:
console.log("The running PID from the main action is: " + process.env.STATE_processID);