Skip to main content
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

Files & Schema

The repository layout and the full flow, suite, and hook file reference

Validation, Syncing & PRs

Validate locally, preview changes on pull requests, and read the sync check

​
Enabling code-managed flows

Code-managed flows are powered by the GitHub Bot, so install the GitHub App first if you haven’t.
  1. Go to Settings > Integrations > 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.
You need to be an admin of your Autosana organization to install the GitHub App and manage integration settings.

​
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).
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.
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).

​
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 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.
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}.
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.

​
Use with Claude Code

If you use 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:
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.

​
Next Steps