Share flows with Git

Bandura has no sync service, no workspace invites, no export step. Because flows are plain text in your repository, Git already is the collaboration layer. This guide is the handful of conventions that make that work smoothly; the case for the arrangement itself (readable diffs in pull requests, clone-and-run, and what it costs a team that wanted a hosted workspace) is on Git-native API testing.

What to commit, what to ignore

my-api-tests/
├── *.aether          ✔ commit        the flows themselves
├── bandura.json      ✔ commit        environments + which secrets the project needs
├── openapi.yaml      ✔ commit        the spec, if you use self-healing
├── .env.example      ✔ commit        a template of the keys, with values blanked
└── .env              ✘ .gitignore    the actual secrets

Two rules do most of the work:

1. .env never enters Git. Bandura’s variable system is built so it never has to: flows reference ${{ env.API_KEY }}, and the value stays local. Runtime overrides you type into the app are also stored outside the workspace, so they can’t leak into a commit either.

2. bandura.json declares what .env must contain via requiredEnv, which lists names only, never values:

   {
     "name": "My API Tests",
     "environments": {
       "staging": { "BASE_URL": "https://staging.api.example.com" }
     },
     "requiredEnv": [{ "name": "API_KEY", "secret": true }]
   }

   The Environments view lists these required keys (with a secret badge where marked), so what a new machine is missing is visible in the app, not tribal knowledge.

The clone → run story

What onboarding a teammate looks like:

git clone [email protected]:your-org/my-api-tests.git

Or skip the terminal: Clone from GitHub… on the welcome screen (and in the command palette) takes a repo URL (https://…, git@host:owner/repo.git, or just owner/repo), asks where to put it, clones, and opens it. There is no “import” step because there is nothing to import: a Bandura project is a Git repo of plain .aether files.

1. Open the folder in Bandura (Open Folder → browse to the clone).
2. Check the Environments view. The required .env keys are listed there; create .env and fill them (copy .env.example if you commit one).
3. Pick an environment in the status bar and Run.

No import, no account, no “who has the latest collection”. git pull is the latest collection. And if a key is forgotten, the pre-run guard catches the unset reference before the run, naming the exact variable.

Reviewing flow changes

An .aether diff reads like a code diff. A changed assertion is one changed line:

   config:
-    check: "response.status === 200"
+    check: "response.status === 200 && response.body.items.length > 0"

Branch, PR, and review API tests exactly like the code they test. Even graph layout (ui.position) is in the file, so the arrangement you made travels to your teammate’s canvas.

You don’t have to leave the app to do this. The Source Control view (branch icon in the activity bar) shows your staged and unstaged changes, lets you stage and commit, and:

• Click any changed file to review it in a side-by-side diff: your working copy against the last commit, with full .aether syntax highlighting.
• See who changed what: the diff’s history rail lists every commit that touched the file (author, date, message, with renames followed), and the Commits list below your changes expands each recent commit into the files it touched. Selecting a commit shows exactly what it changed.
• Take a change back, the whole file or one line: Discard reverts a file’s uncommitted edits (always behind a confirmation, because it can’t be undone), and discarding an untracked file moves it to your system Trash rather than deleting it outright. For surgical reverts, hover the diff’s gutter and click the revert arrow on any single change. Just that block flips back to the committed version; Save (⌘S) applies it.

Push, pull, branching, and merges stay with your normal Git tooling; the built-in terminal works, too.

What stays personal

Run history, variable overrides, your selected environment, and your AI key all live outside the workspace on each machine, never committed, never shared. Your repo carries the tests; your machine carries your state.

The same repo in CI

Because the suite is just files, CI needs one line (bandura run "flows/**/*.aether") with secrets injected as environment variables. Working pipeline files for GitHub Actions and GitLab are on Run flows in CI; the command’s full surface is in The bandura CLI.