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

# Validation, Syncing & Pull Requests

> Validate code-managed flows locally, preview changes on pull requests, and read the BugRadar - Code-Managed Flows check

[Code-managed flows](/docs/code-managed-flows.md) sync on every push to your default branch and preview on every pull request. This page covers the workflow around that sync: validating before you push, reading the **BugRadar - Code-Managed Flows** check, what applies on a PR versus at merge, and how deletes and renames behave.

## Validating locally

Validate your `.BugRadar/` folder before you push with the `BugRadar` CLI ([install it](/docs/install-cli.md) if you haven't). By default it checks the `.BugRadar` directory in the current folder; pass a path to validate somewhere else, handy for a monorepo:

```bash theme={null}
BugRadar flows validate
BugRadar flows validate services/mobile/.BugRadar
```

The CLI runs the **flow- and suite-YAML** rules exactly as the sync does — required keys, unknown keys, `instructions` shape, suite references, key uniqueness — and reports each error per file with the offending line. It exits non-zero on errors, so you can wire it into a pre-commit hook or CI step.

It also checks the hook slugs your files reference, including built-in hooks like `lease-email-address`, against your organization's hooks. That needs you to be logged in: run `BugRadar login` or set `BugRadar_API_KEY`.

> [!NOTE]
>
> A few checks still run **only** server-side and appear on the BugRadar - Code-Managed Flows check after you push: `app:` name resolution, hook slugs that clash with another repository's hooks, and hook-file contents (empty scripts, invalid launch-args JSON). A green local run doesn't guarantee a green check if a flow references an unknown app.

> [!TIP]
>
> Beyond validating, you can **run** the tests you are editing, on your own device or on cloud devices, without committing. See [Running from the CLI](/docs/code-managed-cli.md).

## Sync status & validation

Every sync posts a GitHub check named **BugRadar - Code-Managed Flows** on the head commit — on both pushes and pull requests. It concludes as a failure if there are any issues, otherwise success. The summary reports how many files synced (or lists the errors found), and parse errors are attached as inline annotations anchored to the offending line where one is known, with any "Did you mean" hint appended.

> [!NOTE]
>
> This check used to be called **BugRadar Flows**. If you list it as a required status check in a branch protection rule, change that rule to `BugRadar - Code-Managed Flows` — GitHub matches required checks by exact name, so a rule still naming the old one waits forever for a check that no longer reports.

> [!WARNING]
>
> **One broken file freezes the whole repo's materialization.** The apply step runs only when the entire `.BugRadar/` folder validates with zero issues. If any file has an error, the check reports everything, but no changes are applied and previously synced flows stay as they were until you fix it. The check makes this loud.

## Pull request behavior

In **Settings → Integrations → GitHub**, expand your repository and choose a **Pull request behavior** under **Code-Managed Testing**:

* **Sync and run changed flows** (default): validate and sync changes, then automatically run changed flows on pull requests.
* **Sync only**: validate and sync changes without automatically running changed flows.

**E2E Autopilot** is independent and can still select and run tests when enabled. Turn it off too if you want no automatic test runs. You can still run tests manually from the dashboard, CLI, or by tagging `@BugRadar`. Both modes keep syncing on pushes to the default branch.

## Pull request workflow

Open a pull request that changes `.BugRadar/` and BugRadar previews your flow changes without touching mainline:

* Each changed or added `*.flow.yaml` gets a **PR-scoped flow version** pinned to the PR, so the PR's test runs use the proposed definitions
* The **BugRadar - Code-Managed Flows** check runs on the PR. For mechanical typos on lines you changed, BugRadar also posts inline GitHub *suggestion* comments you can apply in one click
* Suite manifest (`_suite.yaml`) changes are **preview-only** on a PR — a warning notes that suite changes apply when the PR merges
* Removed flow files are ignored during preview; the archival happens on merge
* **Hook files are not previewed.** A PR's runs use the mainline hook scripts, and hook changes (plus their slug-conflict validation) apply on merge. A PR touching *only* hook files posts no check at all

> [!WARNING]
>
> **The PR check validates each changed flow file on its own.** Cross-file checks — repo-wide key uniqueness, suite references, hook slugs and conflicts, and `app:` names — run at merge on the mainline sync, not on the PR. A PR can go green and still fail after merge (for example, a new file whose key duplicates an existing flow). Run `BugRadar flows validate` before merging to catch cross-file issues early.

> [!NOTE]
>
> **Pull requests from forks are skipped** — no flow versions are minted and no check is posted. Fork-authored YAML never touches your organization; it's validated and applied by the mainline sync only after the PR merges.

When the PR merges, the merge lands as a push to your default branch, and the mainline sync materializes everything for real: new flows go live, PR-created flows are promoted to mainline, and suite, hook, and deletion changes apply.

## Deleting and renaming

Removing a definition is a soft delete. When you delete a `.flow.yaml`, `_suite.yaml`, or hook file and push to your default branch, BugRadar **archives** the corresponding flow, suite, or hook — it's deactivated and hidden, but its run history is kept. If a file with the **same key** returns later, the exact same record is reactivated (history intact). If a file is [moved](/docs/code-managed-files.md#moving-files) onto that key instead, the moved test takes over the key and keeps its own history; the archived one stays archived.

> [!WARNING]
>
> **Renaming a flow file without an explicit `key` splits its history.** Because the key defaults to the file path, renaming `login.flow.yaml` to `sign-in.flow.yaml` archives the old flow (`login`) and creates a new one (`sign-in`). A move that keeps the file name usually keeps the history; see [Moving files](/docs/code-managed-files.md#moving-files). Set an explicit `key:` (see [Flow files](/docs/code-managed-files.md#flow-files)) so the record — and its run history — always follows the file.

Deleting a **hook file** while any flow or suite still references its slug fails the whole sync with an "unknown hook" error. Remove the `setup_hooks` / `teardown_hooks` references in the same commit as the hook file.

## Troubleshooting

### My changes didn't appear in the dashboard

**Possible Causes:**

* The repository is not connected to the BugRadar GitHub App
* The push wasn't to the default branch
* Your `.BugRadar/` folder isn't at the repository root and no **Root directory** is set for the repo
* Another file in `.BugRadar/` has a validation error, so the whole apply step was skipped
* After a **force-push** that rewinds the branch to older-dated commits, the sync may be skipped as stale — use **Resync** in the repository’s GitHub integration settings

**Solutions:**

* Connect the repository in **[Settings > Integrations > GitHub](https://usebugradar.com/settings?tab=integrations\&integration=github)**
* Confirm you pushed to the default branch, or use **Resync** in the repository’s GitHub integration settings
* Open the **BugRadar - Code-Managed Flows** check on the commit and fix every reported error — apply only runs at zero issues

### The BugRadar - Code-Managed Flows check failed

**Possible Causes:**

* An unknown top-level key or a malformed `instructions` value
* A suite reference that doesn't match any flow key, or a duplicate flow/suite key
* A `setup_hooks` / `teardown_hooks` slug that doesn't match any hook, or two hook files whose slugs collide
* An `app:` name that doesn't match a linked app — or an omitted `app:` when the repo is linked to more than one app
* A hook file that's empty, or a `.json` launch-args hook that isn't valid JSON

**Solutions:**

* Read the inline annotations and any "Did you mean" suggestions on the check
* Run `BugRadar flows validate` locally to reproduce the flow/suite YAML errors before pushing (app and hook errors surface only on the check)

### My PR check passed but nothing applied after merge

**Possible Causes:**

* The PR check validates each changed flow file on its own; cross-file checks (duplicate keys, suite references, hook slugs/conflicts, `app:` names) run at merge

**Solutions:**

* Open the **BugRadar - Code-Managed Flows** check on the merge commit and fix the reported cross-file errors
* Run `BugRadar flows validate` on the whole `.BugRadar/` folder before merging

### A run from the terminal fails

Errors from `BugRadar run` (an app that isn't found, a flow key that isn't found, a suite refused because a file on the branch could not be read) are covered in [Running from the CLI](/docs/code-managed-cli.md#troubleshooting).

### The dashboard won't let me edit a flow

**Possible Causes:**

* The flow is code-managed and therefore read-only in the dashboard

**Solutions:**

* Edit the linked `.BugRadar/` YAML file in your repository and push, or open a PR to preview the change

## Next Steps

* [Learn the file schema →](/docs/code-managed-files.md)
* [Run your tests from the terminal →](/docs/code-managed-cli.md)
* [Set up the GitHub Bot →](/docs/github-integration.md)
* [Sync from GitLab CI →](/docs/gitlab-ci.md)


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