Skip to main content
This is the complete file reference for code-managed flows: where files live under .BugRadar/, and every recognized key in flow files, suite manifests, and hook scripts.

Repository layout

Everything BugRadar manages lives under a single .BugRadar/ folder — at your repository root by default, or under a subdirectory you point BugRadar at (see Monorepos). Flows are *.flow.yaml files, a suite is a directory containing a _suite.yaml manifest, and hooks are script files under a hooks/ directory.
The sync reads BugRadar.md at the root of .BugRadar/, files that end in .flow.yaml, are named exactly _suite.yaml, or scripts directly inside a hooks/ folder with a supported extension. Every other file under .BugRadar/ is ignored, including config.yaml, which only the CLI reads.

Flow files

A flow file ends in .flow.yaml. The only required keys are name and instructions, where instructions is either a single multiline prompt or a YAML list of steps. As a multiline prompt:
Or as a list of steps:
The recognized top-level keys are:
Any top-level key that isn’t in the table above is a hard error. A typo like instructoins: fails validation with a “Did you mean ‘instructions’?” suggestion on the BugRadar - Code-Managed Flows check, so mechanical mistakes are caught before they merge.
Let the path derive your key. If you omit key, the key comes from the file path (.BugRadar/smoke/checkout.flow.yaml becomes smoke/checkout). Set an explicit key when you want the key to stay stable even if you move or rename the file — see Deleting and renaming.

Exporting caching settings

CLI 0.9.15 and later preserve each caching mode when exporting flows. Older CLI versions export an explicit Standard limit as caching Off, because their boolean format cannot preserve that limit. Upgrade the CLI before exporting to retain the exact setting.

Referencing variables

Define flow overrides in *.flow.yaml and suite defaults in _suite.yaml with variables:
Flow variables override suite defaults. Hooks read them as environment variables (see Variables). Values must be literal strings; quote numbers and booleans (CODE: "00123", ENABLED: "false"). Names use letters, digits, and underscores, and cannot start with a digit. A supplied map replaces that flow’s or suite’s overrides on sync. Omit variables to keep existing values, or use variables: {} to clear them. Keep secrets in Environments, since YAML values are committed to your repository.

Referencing hooks

Attach hooks to a flow with setup_hooks and teardown_hooks, each an ordered list of hook slugs:
A slug resolves against every active hook in your organization — not just repo files — so you can also reference hooks authored in the dashboard, including cURL hooks (which can only be created in the dashboard). Find a dashboard hook’s slug on the hook in the Hooks page. See Hooks as files for how a repo file’s slug is derived. Built-in hooks don’t need to be added from the Hook Library first. Reference Lease email address as lease-email-address and Lease phone number as lease-phone-number, and the sync adds the hook to your organization if it isn’t there yet. If one of your own hooks already uses that slug, your hook is used instead. Duplicate slugs within one list are rejected. The same slug may appear in both setup_hooks and teardown_hooks — that’s legal. To reference a hook by name inside your instructions at run time, use ${hooks:Hook Name} (by display name); see Hooks. On a run pinned to a commit (an API run with ref, BugRadar run --ref, BugRadar’s pull-request test runs, or a CI run with a branch build’s app_build_id), the branch’s hook file of that name runs, including one the branch adds. Working-copy runs (--local or --cloud) use your local file. When the list mixes scripts with a launch-args (.json) hook, the app starts where that hook sits — see when launch configuration runs.

Labels

Attach labels to a flow or suite with labels, a list of label names:
Names match case-insensitively against your org’s labels; unknown names are auto-created. Omitting labels leaves the flow/suite’s existing labels untouched — an explicit labels: [] clears them. Labeled flows and suites dispatch via run-by-label as usual. The built-in snoozed label is the exception. List it to snooze a flow:
  • Remove snoozed from the file to unsnooze the flow on the next sync. Omitting labels, or labels: [], also removes it.
  • A snooze added in the dashboard stays even when the file leaves snoozed out, including labels: []. Only the dashboard removes it.
  • When both the file and the dashboard snoozed a flow, it stays snoozed until both remove it. Unsnooze in the dashboard removes only the dashboard’s snooze. When only the file snoozes a flow, Unsnooze is unavailable, and the API refuses with 409.
  • A branch or commit run reads snoozed from the file at that commit. A flow snoozed in the dashboard is also skipped there.

Suites

A suite is a directory containing a _suite.yaml manifest. The suite’s key is its directory path (a smoke/ directory gives the suite key smoke). The only required key is name:
The recognized keys are: The Lease email address and Lease phone number built-in hooks may be listed in a suite’s setup_hooks. Unlike ordinary suite setup scripts, a lease hook is inherited by every member flow and creates a separate inbox or number for each flow run. The suite’s setup_flow, when configured, receives its own lease too. This also applies when parallelize_flows: true. These built-ins are setup-only and are rejected in teardown_hooks. Reference them as lease-email-address and lease-phone-number; you don’t need to add them from the Hook Library first. References in flows and setup_flow resolve sibling-first: a flow directly in the suite’s own directory wins, otherwise the reference is matched against every flow in the repo. A suite directory cannot hold directories of tests; the sync fails and names the directory to move out. Flow keys and suite keys must each be unique across the whole repo. An unknown reference, or the same flow listed twice, is a validation error.
The _suite.yaml file must live inside a directory — it cannot sit at the .BugRadar/ root, because a suite is a directory. Membership is defined by the suite (its flows list or its directory), never declared inside the flow files themselves.
YAML parses bare no, yes, on, and off as booleans (the “Norway problem”). Because setup_flow and name must be strings, setup_flow: no fails validation — quote the value if you really mean the string "no".
For how variables and setup flows propagate across a suite’s flows, see Suites.

Folders

Each directory under .BugRadar/ that holds tests, at any depth, shows as a folder on the Flows page. The top folder from a repo shows the repo’s name, linked to that directory in your repo. Directories can nest as deep as you like.
  • A suite directory (one with _suite.yaml) is a suite, not a folder. It cannot hold directories of tests.
  • A flow file the suite lists shows under the suite only. A flow file the suite leaves out shows in the folder that holds the suite.
  • hooks/ directories, and everything below them, are not folders.
  • Spaces at the start or end of a directory name are dropped from the folder name.
  • Folders from a pull request appear when it merges to your default branch.
Directories set where a test starts. On the Flows page you can drag a flow or suite from your repo to a new spot, another folder, or a section, and it stays there: a push moves it only when its file moves to another directory. To see every test where its file is, select Show repo file structure, the folder tree button at the start of the toolbar above the list. If you remove or rename a directory that still holds flows, suites, or folders made in the dashboard, the folder stays with those items and becomes an ordinary dashboard folder. If you disconnect or remove the repository, its folders all stay as dashboard folders, and its flows become dashboard flows in the same folders. Only empty folders are removed.

Moving files

Moving a flow file to another directory keeps its run history when the file name stays the same. If several moved files share a name, a file keeps its history only when exactly one new file matches it on the folder around it as well as the name, and that new file matches no other old file as closely. For example, renaming Checkout/ to Payments/ keeps the history of both Checkout/web/happy-path.flow.yaml and Checkout/ios/happy-path.flow.yaml. If that’s not clear-cut, those files start as new tests. Moving a suite directory works the same way, matched on the directory name. Otherwise the old test is archived and a new one starts. That includes moving and renaming a file in one commit, or moving it across two commits. What a move does not carry over:
  • Results of runs on a branch, which are saved by key, stay under the old key.
  • A branch cut before the move still has the old path. Its runs create a separate test under the old key.
Moving or renaming a directory changes the key of every flow inside it, because keys come from the path. A suite’s flows or setup_flow entry that names an old key then stops the whole sync. When only one flow could be the moved one, the error names its new key. CI scripts that name keys need updating too. To keep keys fixed when you move files, set key: in each file.

Hooks as files

Hooks live as script files inside a hooks/ folder — either .BugRadar/hooks/ or <suite>/hooks/. The file extension determines the hook type, and the filename becomes the hook’s slug. The slug is derived from the filename with its final extension removed: lowercased, with runs of non-alphanumeric characters collapsed to -. So Seed DB.sh becomes slug seed-db, and reset.env.json becomes reset-env. This slug is what you reference in setup_hooks / teardown_hooks. The display name is the humanized filename (reset-test-env.sh shows as “Reset Test Env”).
Hook slugs are unique across your whole organization — the folder a hook lives in has no scoping effect. Two files that slugify the same (seed-db.py and seed_db.sh), or a slug that collides with a different repository’s hook, fail the sync with a rename error. A slug that matches an existing dashboard-authored hook is not an error — that hook is adopted (its run history preserved), the same way flows adopt by name; see Migrating existing flows. Rename the file if that isn’t what you intend.
The file content is the hook script, stored verbatim. Empty or whitespace-only files are rejected. A .json launch-args hook must parse as valid JSON, and a filename with no letters or digits (so it produces an empty slug) is rejected.
Script hooks (.py, .js, .ts, .sh) read environment variables natively — os.environ.get(...) in Python, process.env in JavaScript/TypeScript, $VAR in Bash. Launch-args (.json) hooks — and dashboard-authored cURL hooks — use the ${env:KEY} token instead, since they aren’t executed scripts. cURL hooks have no file form; reference an existing dashboard cURL hook by slug, or use a .sh hook that runs curl. See Hooks for the full hook model.

Config file

config.yaml at the root of .BugRadar/ sets defaults for BugRadar run. It is not a test: the sync never reads it and the CLI never uploads it. How the defaults apply is on Running from the CLI.
Any other key, an unknown platform, or a mobile entry without bundle_id (or a web entry without app_id) is an error. BugRadar flows validate reports it, and BugRadar run refuses to start until it is fixed.

Monorepos

By default BugRadar looks for .BugRadar/ at your repository root. If your definitions live in a subdirectory — common in a monorepo — point BugRadar at that folder with the repo’s Root directory setting.
  1. Go to Settings > Integrations > GitHub
  2. On the connected repo, set Root directory to the folder that contains .BugRadar/ (for example, services/mobile for services/mobile/.BugRadar/)
  3. Leave it blank to use the repository root
Flow and suite keys stay relative to .BugRadar/, so moving your definitions into a subdirectory doesn’t change any keys — a flow at services/mobile/.BugRadar/login.flow.yaml still has the key login. The GitHub links on each row point at the full path in your repo.
Saving a new Root directory doesn’t re-sync on its own. Click Resync on the repository card, or push to the default branch to sync from the new location. Once .BugRadar/ has been detected, the nightly resync also checks it for drift.

Next Steps