Set Environment Variables for Later Steps
Set an environment variable or add a PATH directory in one step, and use it in the later steps of the same job.
A step can set an environment variable for the steps that run after it in the
same job. A step can also add a directory to PATH for these steps. Use this
when one step installs a program or calculates a value that later steps need.
Each step runs in a new shell. When the step ends, the shell closes. The
variables that the step set with export are lost. The changes that the step
made to PATH are also lost.
To keep a value for the later steps, write the value to a file:
- Write an environment variable to the file
$SHIPFOX_ENV. - Write a
PATHdirectory to the file$SHIPFOX_PATH.
When the step ends, Shipfox reads the two files. Shipfox then gives the values to each later step of the job.
The example below installs Nix in one step and runs it in the next step. For
your own case, keep the two echo lines. Change the variable, the directory,
and the commands.
Set a variable and add a PATH directory
This is a complete workflow:
# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Set environment variables for later steps
runner: shipfox
triggers:
manual:
source: manual
jobs:
test:
steps:
- name: Install Nix
run: |
curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
# Sets the variable NIX_PATH for the later steps.
# Write one NAME=value on each line.
echo "NIX_PATH=nixpkgs=channel:nixos-24.05" >> "$SHIPFOX_ENV"
# Adds the directory of the nix program to PATH for the later steps.
# Write one directory on each line.
echo "$HOME/.nix-profile/bin" >> "$SHIPFOX_PATH"
# This step finds the nix program and reads $NIX_PATH.
- run: nix develop --command make testThese steps get the values:
- The run steps and the action steps that run later in the same job.
- The shell commands of the agent steps that run later in the same job.
The step that writes the files doesn't get the values. Other jobs don't get them.
Shipfox reads the files when the step ends, even if the step fails. Two names
are not permitted in $SHIPFOX_ENV: PATH, and a name that starts with
SHIPFOX_. A step that writes one of these names fails.
When one of the two files is invalid, Shipfox gives no values from that step to the later steps. If the step also failed for another reason, the step keeps that failure, and the end of the step log names the invalid file.
Mask a value that a step fetches
Shipfox masks the secrets it stores. It doesn't know a value that a command fetches during the run, such as a short-lived cloud token. A later step that prints this value shows it in the logs.
To mask the value, write it to the file $SHIPFOX_MASK before you write it to
$SHIPFOX_ENV:
steps:
- name: Get a registry token
run: |
TOKEN="$(aws ecr get-login-password)"
# Masks the token in the later steps. Write one value on each line.
echo "$TOKEN" >> "$SHIPFOX_MASK"
# Sets the variable REGISTRY_TOKEN for the later steps.
echo "REGISTRY_TOKEN=$TOKEN" >> "$SHIPFOX_ENV"
# If this step prints the token, its log shows *** in place of it.
- run: printf '%s' "$REGISTRY_TOKEN" | docker login --username AWS --password-stdin registry.example.comShipfox reads $SHIPFOX_MASK when the step ends, even if the step fails. It
then replaces each value with *** in the logs, outputs, and annotations of
every later step of the job. The values stay masked after a gate restart.
These limits apply:
- The step that writes the file isn't masked while it runs. Don't print the value in this step. Shipfox does mask the outputs of this step.
- Each value needs at least 8 characters. A shorter value fails the step, because it would also hide ordinary text in the logs.
- Each line is one value. For a value that has several lines, write each line of at least 8 characters as its own value.
- Other jobs don't get the masks.
Values in $SHIPFOX_ENV are not masked by default
A value that a step writes only to $SHIPFOX_ENV appears in the logs of any
later step that prints it. If the value doesn't change between runs, store
it as a secret instead.
Check which value a step gets
A variable can come from more than one place. The step gets the value from the last place in this list:
- The runner environment.
$SHIPFOX_ENVin earlier steps. If two steps set the same variable, the step that is lower in the workflow file sets the value. A background step sets values only after awaitfor that step.envin the workflow, the job, or the step. This includes secrets inenv.- Variables that Shipfox sets, for example
SHIPFOX_RUN_ID.
Directories from $SHIPFOX_PATH come before the directories in PATH. The
directory that a step wrote last comes first.
Know what a gate restart changes
A gate can make earlier steps run again. Later steps then get the values from the last time each step ran:
- A step that runs again replaces all the values it wrote before.
- A step that is skipped the second time gives no values. Shipfox removes the values and the directories that the step wrote before.
- A step before the restart point keeps its values.
Adapt it to your workflow
| To... | Change this |
|---|---|
| Set a value that has several lines | Write a NAME<<DELIMITER line, the value, then a line with only the delimiter. The format is the same as for $SHIPFOX_OUTPUT. |
| Add a directory inside the repository | Write a relative path to $SHIPFOX_PATH. Shipfox resolves it against the working directory of the step. |
| Use another value in one step only | Set the variable in the env of that step. See Environment variables. |
| Send a value to another job | Use an output. See Pass values between jobs. |
| Use a credential that doesn't change between runs | Bind a secret in env instead of writing it to $SHIPFOX_ENV. See Add secrets and variables. |
| Use a credential that a step fetches | Write it to $SHIPFOX_MASK, then to $SHIPFOX_ENV. See Mask a value that a step fetches. |
Verify the values
Start the workflow
Select Run, then open the new run.
Inspect the later step
Open a step that runs after the step that writes the files. Confirm that it read the variable and found the program.
In the example, the second step runs nix. The log doesn't contain a
"command not found" error.
See Step environment for every variable that Shipfox sets on a step.