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.

​
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, hook, and config file reference

Running from the CLI

Run your tests on your own device, on cloud devices, or from a branch

Syncing & Pull Requests

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

Migrating

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, so install the GitHub App first if you haven’t.
  1. Connect your repository in Settings > Integrations > GitHub
  2. Commit your flow, suite, and hook files under .autosana/
  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 .autosana/ has been detected. For a folder below the repository root, set the repo’s Root directory first (see Monorepos).
You need to be an admin of your Autosana 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. Environment values stay in the dashboard. Flow and suite overrides can be defined in YAML with variables. 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 .autosana/autosana.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.
.autosana/autosana.md
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, Autosana 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 autosana.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.

​
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