Environments

This word is overloaded, and mixing the two up is the single most common source of confusion when wiring atra into a pipeline. They are separate systems and neither knows about the other.

You build environments in Atrahasis, not in a text editor. The app saves them into the group folder as environments.json, you commit that folder, and atra reads it back on the runner. There is nothing to hand-write and nothing to keep in sync.

Environments are scoped to their group. Each flow group and each spec group carries its own set, so a flow group's dev is unrelated to a spec group's dev.

What you set on a variable

Four settings decide where a value comes from at run time. Only the last two matter for CI, and they are the ones people miss.

One rule, and it is the whole thing

When a variable is marked as a secret with its source set to OS, atra reads it from an operating system environment variable whose name is exactly the key. A key of base_url looks for an environment variable called base_url. Nothing is uppercased, prefixed or otherwise transformed.

The same bridge on each platform

The secret store differs, the requirement does not: an environment variable named base_url has to exist when atra runs.

env:
  base_url: ${{ secrets.BASE_URL }}

environment {
    base_url = credentials('atrahasis-base-url')
}

export base_url="https://api.example.com"

atra checks for every secret it will need before it sends a single request, and lists all of them at once. You get one clear failure instead of a confusing 401 halfway through a flow, and you can fix every missing variable in one go rather than re-running after each one.

Environment 'dev' has secret variables that are not set in your shell:
  export base_url=<value>
  export api_key=<value>

Set them before running the command.

The hint is printed in the syntax of the machine it ran on, so a Windows agent shows $env:base_url = "<value>" instead. Seeing this in a build log almost always means step 3 above was skipped, or the name does not match the key.

And when you forget -e entirely

Without -e no environment is loaded, so nothing fills the placeholders. Rather than firing requests at a URL containing a literal {{base_url}}, atra stops and names what it could not resolve.

Unresolved variable(s) '{{base_url}}' in flow 'logout'
 Hint:  Use --env (-e) to select an environment from environments.json

Pass the environment name with -e or --env. Matching is case-insensitive, so -e Dev finds dev.

In a pipeline the environment name is usually the one thing worth making a parameter, so the same job can be pointed at staging or production without editing the file.

A variable whose source is Vault is fetched from HashiCorp Vault at run time. Instead of the value itself, the pipeline supplies credentials for the connection, in an environment variable named after it: VAULT_AUTH_<CONNECTION>.

# Token auth
export VAULT_AUTH_MYCONNECTION="<token>@https://vault.example.com"

# Username and password
export VAULT_AUTH_MYCONNECTION="<username>:<password>@https://vault.example.com"

These are checked up front too. If a connection has no credentials, atra names the connection and prints the exact variable to set before any traffic is sent. One CI secret then covers every variable that connection serves.