> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/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 `.autosana/` folder. When you push to your default branch, Autosana 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.

Code-managed definitions are **read-only in the dashboard** — you edit them by changing the YAML and pushing (or opening a PR to preview first). Running is unaffected: read-only covers the definition, not execution.

## How it works

1. You define flows, suites, and hooks as files under `.autosana/` in your repo
2. On a push to your default branch, Autosana fetches `.autosana/`, validates every file, and materializes the changes
3. On a pull request, Autosana 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

<CardGroup cols={2}>
  <Card title="Files & Schema" icon="file-code" href="/code-managed-files">
    The repository layout and the full flow, suite, and hook file reference
  </Card>

  <Card title="Validation, Syncing & PRs" icon="code-pull-request" href="/code-managed-sync">
    Validate locally, preview changes on pull requests, and read the sync check
  </Card>
</CardGroup>

## Enabling code-managed flows

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

1. Go to **[Settings > Integrations > GitHub](https://autosana.ai/settings?tab=integrations\&integration=github)**
2. Find the repository you want to manage in the connected-repositories list
3. Toggle **Code-Managed Testing** on for that repo
4. Autosana runs an initial full sync of `.autosana/` immediately

The toggle is per repository, so you can opt in one repo at a time. Enabling it kicks off an initial sync; after that, every push to the default branch that touches `.autosana/` re-syncs automatically, and a nightly resync catches any drift.

<Note>
  You need to be an admin of your Autosana organization to install the GitHub App and manage integration settings.
</Note>

## Migrating existing flows

Already have flows in the dashboard? Export them to files with the `autosana` CLI, commit them, and let the sync adopt them:

First authenticate the CLI: run `autosana login` (or set `AUTOSANA_API_KEY`).

```bash theme={null}
# Write every dashboard flow, suite, and their hooks to ./.autosana (with explicit keys)
autosana flows export --all

# Or export a single suite and its flows
autosana flows export --suite "Smoke Tests"
```

Export writes each flow (`*.flow.yaml`), suite (`_suite.yaml`), and the flows' **and** suites' own setup/teardown **hooks** (`hooks/<slug>.<ext>`), adding `setup_hooks`/`teardown_hooks` and `labels` to the flow files and the suite manifests as needed. cURL hooks have no file form, so they're referenced by slug but stay dashboard-authored. Review the generated files, commit them under `.autosana/`, then enable **Code-Managed Testing**.

On the first sync, anything whose identity **matches** an active dashboard definition is **adopted** — its run history is preserved and it becomes code-managed (read-only), now driven by your files:

* a **flow** or **suite** is adopted when its `name` exactly matches one active dashboard flow/suite;
* a **hook** is adopted when its slug (its filename) matches one active dashboard hook.

<Warning>
  Adoption is by **exact, case-sensitive** identity and only on a single match. A YAML flow named the same as an *unrelated* dashboard flow — or a hook file whose slug matches an unrelated dashboard hook — will claim it and make it read-only, so review your exported names before enabling. If two dashboard flows share a name (ambiguous), the sync creates a new flow instead of claiming either. A hook slug that collides with a **different repository's** hook is still a blocking error (see [Hooks as files](/code-managed-files#hooks-as-files)).
</Warning>

## 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:

<Note>
  To change a code-managed flow, suite, or hook, 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. The repository stays the source of truth.
</Note>

Read-only applies to the **definition**, not execution — you can still run code-managed flows and suites from the dashboard. Environment variable **values** also stay defined in the dashboard; your YAML only references them via `${env:KEY}`.

<Warning>
  **Disabling the toggle does not restore dashboard editing.** Turning **Code-Managed Testing** off only stops syncing; already-synced flows, suites, and hooks stay code-managed and read-only. To make them editable in the dashboard again, first delete their files and push (which archives them), then disable the toggle. As long as the toggle is on, your YAML stays authoritative.
</Warning>

## Use with Claude Code

If you use [Claude Code](https://claude.com/claude-code), install the Autosana plugin so Claude knows the `.autosana/` 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 Autosana/claude-code-plugin
/plugin install autosana@autosana
```

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

## Next Steps

* [Learn the file schema →](/code-managed-files)
* [Validate, sync, and preview on PRs →](/code-managed-sync)
* [Run working-copy flows locally →](/local-testing#run-code-managed-flows-from-the-cli)
* [Write effective flows →](/flows)
* [Set up the GitHub Bot →](/github-integration)