Atrahasis CI

Run Atrahasis API tests, flows, and load tests inside any GitHub Actions workflow.

This action is a thin wrapper around the atra CLI. It runs your command through npx --yes @atrahasis/cli, so nothing is installed on the runner and there is no license key to configure. The CLI, its flow runner, and its load testing are free.

Whatever atra returns, the action returns. Exit code 0 passes, 1 fails, so your assertions gate the pipeline.

atra does three things, and this action exposes all three through a single args input:

1. A terminal API client. Send requests from the shell with request tracing, assertions, and random data generation built in.
2. A flow runner. Run the multi step flows you designed in the Atrahasis desktop app, unchanged.
3. A load tester. Run the load specs you built in the app, with real traffic shapes and thresholds.

Quick start

- name: API health check
  uses: atrahasisdev/action@v1
  with:
    args: GET https://api.example.com -a "status eq 200" -a "response_time lt 2000"

The args input is passed to atra verbatim. Anything you can type after atra on your machine works here.

Inputs

Input	Required	Default	Description
args	yes		Arguments passed verbatim to atra.
working-directory	no	.	Directory to run atra in. Point it at the checked-out folder that holds your flow or spec groups.

The three ways to use atra

1. Single request

Send one request and assert on the result. No files needed.

- uses: atrahasisdev/action@v1
  with:
    args: GET https://api.example.com/health -a "status eq 200"

2. Flow runner

Run flows you designed in the Atrahasis desktop app. Flow groups are stored as .flow.json files and are version controlled on their own. Check that repository out first, then run from inside it. atra runs in the current directory by default, so you do not name the group.

- uses: actions/checkout@v4
- uses: atrahasisdev/action@v1
  with:
    args: run

run with no flow name runs every flow in the group. To run a single flow, name it with -f:

- uses: atrahasisdev/action@v1
  with:
    args: run -f logout-flow -p 2 -c

3. Load testing

Run load specs you built in the desktop app. Spec groups are stored as .spec.json files. Same idea: check them out, then run from inside the group. run with no spec name runs every spec in the group.

- uses: actions/checkout@v4
- uses: atrahasisdev/action@v1
  with:
    args: run -t stress

Assertions gate the build

Assertions are what turn a request into a test. When one fails, atra exits 1 and the job fails. Chain as many -a flags as you need.

- uses: atrahasisdev/action@v1
  with:
    args: >-
      GET https://api.example.com/users/1
      -a "status eq 200"
      -a "response_time lt 800"
      -a "$.user.id exists"
      -a "header Content-Type contains json"

Target	Example
Status code	-a "status eq 200"
Response time (ms)	-a "response_time lt 800"
JSON path	-a "$.user.id eq 42"
Body content	-a "body contains success"
Header	-a "header Content-Type contains json"

Operators come in short and long forms: eq/equals, lt/less_than, plus contains, exists, matches_regex, and more. See the full reference in the assertions guide.

Secrets and variables

Flows and specs reference values with {{variable}}. When a value is sensitive, or changes per environment, keep it out of the checked-out files and pass it through the environment instead.

In the Atrahasis desktop app, mark the variable as Secret (source os). atra then reads it from the process environment at run time rather than from environments.json, so no value is committed to Git.

In the workflow, put the value in the env: block of the step. It works the same whether the value comes from a GitHub secret or a GitHub variable:

- uses: actions/checkout@v4
- uses: atrahasisdev/action@v1
  env:
    api_key: ${{ secrets.API_KEY }}    # from a secret, masked in the logs
    base_url: ${{ vars.BASE_URL }}     # from a variable, shown in plain text
  with:
    args: run -e dev

A few rules that save time:

• Match the names exactly. The name on the left of env: becomes the OS environment variable atra reads, and it must equal the variable key in environments.json, letter for letter. GitHub shows stored secret names in uppercase, but you choose the env: name, so set it to match your key (for example base_url, not BASE_URL, if that is how you named it in the app).
• Secret or variable, atra does not care. Both land in the environment the same way. The only difference is that secrets are masked in the logs and variables are printed in full.
• GitHub Environments work too. If the value lives in a GitHub Environment rather than a repository secret, add environment: <name> to the job so the secret is available to the step.
• Nothing is written to disk. Secret values stay in the environment for the length of the run and never land in a file.

Full workflow example

name: API tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Health check
        uses: atrahasisdev/action@v1
        with:
          args: GET https://api.example.com/health -a "status eq 200"

      - name: Run flow
        uses: atrahasisdev/action@v1
        env:
          base_url: ${{ secrets.BASE_URL }}
        with:
          args: run -f logout-flow -e dev -p 2 -c

      - name: Load test
        uses: atrahasisdev/action@v1
        with:
          args: run -t spike

Where do the flow and spec files come from?

You design and run flows and load tests in the Atrahasis desktop app. Each flow group and each spec group is version controlled independently through the app's built in Git, so they live in their own repository, separate from your application code.

To run them in CI, check that repository out with actions/checkout and point working-directory at the folder if it is not the repository root.

Notes

• Runs on the GitHub hosted Linux, macOS, and Windows runners. Node.js ships with all of them, which is all npx needs.
• Secrets never touch disk. Pass sensitive values through the env: block and reference them with {{variable}} in your flows and specs. See Secrets and variables above.

Learn more

• atra CLI guide
• Flow runner
• Load testing
• Assertions
• @atrahasis/cli on npm
• Atrahasis