> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Code-Managed Flows

> Define flows, suites, and hooks as files in your repository, synced via GitHub

Keep your flows, suites, and hooks in version control by defining them as files in your repository's `.BugRadar/` folder. When you push to your default branch, BugRadar syncs those files and materializes them as flows and suites in your dashboard. This is GitOps for your tests: your repository is the source of truth, changes go through pull requests, and every definition is code-reviewed alongside the app it tests.

## How it works

1. You define flows, suites, and hooks as files under `.BugRadar/` in your repo
2. On a push to your default branch, BugRadar fetches `.BugRadar/`, validates every file, and materializes the changes
3. On a pull request, BugRadar previews the proposed flow definitions and posts a GitHub check
4. The dashboard shows the resulting flows and suites as **read-only**; edit them by pushing to the repo

> [card] [Files & Schema](/docs/code-managed-files.md)
>
> The repository layout and the full flow, suite, hook, and config file reference

> [card] [Running from the CLI](/docs/code-managed-cli.md)
>
> Run your tests on your own device, on cloud devices, or from a branch

> [card] [Syncing & Pull Requests](/docs/code-managed-sync.md)
>
> Validate locally, preview changes on pull requests, and read the sync check

> [card] [Migrating](/docs/code-managed-migrate.md)
>
> Export the flows you already have and let the sync adopt them

## Enabling code-managed flows

Code-managed flows are powered by the [GitHub Bot](/docs/github-integration.md), so install the GitHub App first if you haven't.

1. Connect your repository in **[Settings > Integrations > GitHub](https://usebugradar.com/settings?tab=integrations\&integration=github)**
2. Commit your flow, suite, and hook files under `.BugRadar/`
3. Push to the default branch to sync them, or open a pull request to preview the changes

Code-managed flows work automatically for connected repositories. Every push to the default branch reconciles the files, and a nightly resync catches drift in repositories where `.BugRadar/` has been detected. For a folder below the repository root, set the repo's **Root directory** first (see [Monorepos](/docs/code-managed-files.md#monorepos)).

Using GitLab? Sync from a CI job instead of the GitHub App: see [GitLab CI](/docs/gitlab-ci.md).

> [!NOTE]
>
> You need to be an admin of your BugRadar organization to install the GitHub App and manage integration settings.

## Read-only in the dashboard

A flow, suite, or hook is code-managed when it originates from a connected repository. Code-managed rows are **read-only** in the dashboard: to change one, edit the YAML (or script) in your repository and push, or open a PR to preview the change first. On the Flows page, use **View** to inspect a flow or suite without editing it, or select the GitHub icon to open its source file directly.

Read-only applies to the **definition**, not execution. You can still run code-managed flows and suites from the dashboard, and from the [terminal](/docs/code-managed-cli.md). Environment values stay in the dashboard. Flow and suite overrides can be defined in YAML with [`variables`](/docs/code-managed-files#referencing-variables).

You can still mix code-managed and dashboard tests. Add a dashboard flow to a code-managed suite, or remove one you added; flows listed in the suite file come first and can only be changed in the file. A dashboard suite can also use a code-managed flow as a member or as its authentication flow.

Deleting files and pushing archives their corresponding flows, suites, and hooks. Their history remains available; removing a file does not turn its archived definition into a dashboard-editable flow.

## Repository context

Add `.BugRadar/BugRadar.md` to share plain Markdown context with the test agent. Use it for app terminology, navigation hints, and conventions that apply across tests. No frontmatter or YAML is required. The file must be UTF-8 text, at most 64 KiB.

```markdown title=".BugRadar/BugRadar.md" theme={null}
# App context

A workspace contains projects. Switch workspaces from the account menu.
Dismiss the optional product tour before starting a test.
```

Each flow receives context from the repositories associated with that flow, its suite, and its app build. Each repository is included once per flow; context from an unrelated flow in the same run is not shared. These sources are combined without a precedence order.

When you select a branch or commit for a run, BugRadar reads context at the resolved commit for that repository. Otherwise, it uses the latest successfully synced default-branch context. An app build identifies a relevant repository but does not select the build's commit for context. Local working-copy runs can use uncommitted context from the working copy.

Default-branch context becomes available after the repository syncs. Builds can still run without a connected repository, and existing repositories can run while their first context sync completes. An explicit context read failure stops the run with an error.

Missing or empty context files add nothing to the agent's prompt. Each run saves its selected context and source details, so later repository changes do not change the historical snapshot. Edit context in Git, just like code-managed flow definitions.

Open **Settings → Integrations → GitHub** and select **View BugRadar.md** on a repository to read its latest synced default-branch file and see the source commit. This view also reports missing files and sync failures.

## Migrating existing flows

Already have flows in the dashboard? Export them to files and let the first sync adopt them with their history: see [Migrating](/docs/code-managed-migrate.md).

## Use with Claude Code

If you use [Claude Code](https://claude.com/claude-code), install the BugRadar plugin so Claude knows the `.BugRadar/` schema, the validate-before-push workflow, and the gotchas. It can then scaffold and fix flows, suites, and hooks for you in one pass, and validate them before you push:

```
/plugin marketplace add BugRadar/claude-code-plugin
/plugin install BugRadar@BugRadar
```

Invoke it with `/BugRadar:code-managed-flows`, or just start editing files under `.BugRadar/` and Claude pulls in the skill automatically. The plugin is open source at [BugRadar/claude-code-plugin](https://github.com/BugRadar/claude-code-plugin).

## Next Steps

* [Learn the file schema →](/docs/code-managed-files.md)
* [Run your tests from the terminal →](/docs/code-managed-cli.md)
* [Validate, sync, and preview on PRs →](/docs/code-managed-sync.md)
* [Write effective flows →](/docs/flows.md)
* [Set up the GitHub Bot →](/docs/github-integration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.