Any CI System

GitLab CI, CircleCI, Azure Pipelines, Bitbucket, TeamCity, Bamboo, Woodpecker, Drone, a cron job on a server. atra is a single binary with no daemon and no licence check, so anywhere you can run a shell command you can run it. This page is the pattern behind every platform page.

It comes down to four decisions

Every platform page on this site is these four questions answered in that platform's syntax. Answer them for yours and you are done.

1How does atra get onto the machine? Through npx if Node is there, or the shell installer if not.

2How do the flows get there? A git checkout of the repository your Atrahasis folder lives in.

3How does the secret get in? As an environment variable named exactly like the key in the app.

4How does a failure fail the build? It already does. atra exits non-zero and every CI system reads exit codes.

1. Getting atra onto the machine

If the image has Node

Most CI images do. Nothing to install and nothing to keep at the right version.

npx --yes @atrahasis/cli GET https://api.example.com/health -a "status eq 200"

If it does not

The installer picks the right build for the platform and the C library, then puts atra on the path.

curl -fsSL https://cli.atrahasis.dev | sh
atra GET https://api.example.com/health -a "status eq 200"

On Windows agents the equivalent is irm https://cli.atrahasis.dev/install.ps1 | iex.

Alpine and old enterprise Linux both work. The installer detects musl and fetches a statically linked build, so slim images need no compatibility layer. The glibc builds go back to 2.17, which covers RHEL 7 and 8, Amazon Linux 2, Debian 10 and Ubuntu 18.04.

2. Getting your flows and specs there

You do not author flows or load specs for CI by hand. You build them in Atrahasis, which writes plain files into a group folder alongside an environments.json. Commit that folder, then have the pipeline clone it.

git clone --depth 1 https://github.com/my-org/api-flows.git flows
cd flows
npx --yes @atrahasis/cli run -f logout -e dev

Whatever your platform's checkout step is called, this is all it needs to achieve. Keeping tests in their own repository is the usual arrangement, since several pipelines tend to want the same flow.

Where you run it decides what you name

atra reads the group from the current directory. Run from inside the group and leave its name out. Run from the parent and name the group as the first argument: run checkout-flows -f signup -e dev. Dropping -f runs every flow in the group, and dropping -s runs every spec, which means adding a test in the app needs no pipeline change.

3. Getting the secret in

A variable marked as a secret with its source set to OS in the app is read from an operating system environment variable whose name is exactly the key. Nothing is uppercased or prefixed. So the whole bridge, on any platform, is this:

export base_url="https://api.example.com"
npx --yes @atrahasis/cli run -f logout -e dev

Your platform has a way to put a stored secret into the environment of a job. That is the step you are looking for. The name it is stored under does not matter; the name it arrives as does.

Environments in full, including Vault →

Your platform's own "environment" feature is unrelated to an Atrahasis environment, and nothing maps between them. Deploying to an environment called staging does not select the Atrahasis environment called staging. You always pass -e yourself.

4. Making a failure fail the build

Nothing to configure. atra exits 0 when every check passed and non-zero when any did not, covering a failed assertion in a request, a failed step in a flow and a breached threshold in a load test. Every CI system in existence fails a step on a non-zero exit code, so no wrapper script, output parsing or grep over stdout is involved.

The only thing to watch for is a shell that hides the exit code. If you pipe atra into something else, the pipeline's exit status is the last command's, not atra's. Use set -o pipefail if you do that.

A worked example: GitLab CI

GitLab does not have its own page here yet, because a platform only gets one once atra has actually been run on it. It makes a good illustration of applying the four decisions to a platform we have not written up, which is exactly what this page is for.

api-tests:
  image: node:22-alpine
  variables:
    # 3. the secret arrives under the key name from the app
    base_url: $BASE_URL
  script:
    # 1. Node is in the image, so npx is enough
    - npx --yes @atrahasis/cli GET "$base_url/health" -a "status eq 200"

    # 2. the flows come from their own repository
    - git clone --depth 1 https://gitlab.com/my-org/api-flows.git flows
    - cd flows
    - npx --yes @atrahasis/cli run -e dev

    # 4. nothing here: a failure already exits non-zero

Translate those four moves into your platform's vocabulary and you have your integration. If you get one working on a platform not listed here, tell us and it can become a page.

If something does not work

Symptom	Cause
`npx: not found`	No Node in the image. Use the shell installer, or pick an image that has it.
Secret variables are not set in your shell	The secret never reached the job as an environment variable, or its name does not match the key. It is case-sensitive.
Unresolved variable(s)	`-e` is missing, or the variable is not in the environment you selected.
The step is green but nothing ran	atra was piped into another command, so the shell reported that command's exit code. Add `set -o pipefail`.

Jenkins