Shipfox

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 PATH directory 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 test

These 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.com

Shipfox 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:

  1. The runner environment.
  2. $SHIPFOX_ENV in 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 a wait for that step.
  3. env in the workflow, the job, or the step. This includes secrets in env.
  4. 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 linesWrite 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 repositoryWrite a relative path to $SHIPFOX_PATH. Shipfox resolves it against the working directory of the step.
Use another value in one step onlySet the variable in the env of that step. See Environment variables.
Send a value to another jobUse an output. See Pass values between jobs.
Use a credential that doesn't change between runsBind a secret in env instead of writing it to $SHIPFOX_ENV. See Add secrets and variables.
Use a credential that a step fetchesWrite 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.

Was this page helpful?
Edit this page on GitHub

On this page