Skip to main content
Code-managed flows 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 Autosana - Code-Managed Flows check, what applies on a PR versus at merge, and how deletes and renames behave.

​
Validating locally

Validate your .autosana/ folder before you push using the autosana CLI. Install it (requires 0.8.0 or newer, which adds the flows commands):
Then validate — by default it checks the .autosana directory in the current folder; pass a path to validate somewhere else (handy for a monorepo):
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.
The CLI can’t see your organization’s data, so a few checks run only server-side and appear on the Autosana - Code-Managed Flows check after you push: app: name resolution, hook-slug references and conflicts, 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 or hook.
Beyond validating, you can run a working-copy flow or suite on a local device with autosana run <flow> --local, or on a local web server with autosana run <flow> --local --app-id <APP_ID>. No commit, push, or cloud device is required. See Local Testing.

​
Run a branch’s tests

You do not have to merge, or even open a pull request, to run the tests on a branch. Point the CLI at the branch and it reads that branch’s .autosana/ files:
Name the flow with --flow here. The shorter autosana run login form is for --local runs only, and a cloud run refuses it. The dashboard runs branches too — the run dialogs on the Flows page take a branch and a build, and the build you pick there need not come from that branch. By default the run uses the app build made from the same commit as the tests, so every result names a single commit. Two flags change which build runs: The last row is the one to reach for when you changed only test files: no build exists at your commit, and rebuilding an app that did not change is wasted work. Naming a build is itself the choice to run it — a build and the tests it runs are separate things, and they may come from different commits. Reach for --build-match branch-latest when you want the branch’s newest build but do not have its ID to hand — in CI, say, where looking one up costs an extra call. If the option you choose matches no build, the run is refused and says so. Autosana never quietly falls back to the app’s active build, because a result that does not name the build it came from is worse than no result.
--build-match needs CLI 0.9.4 or newer, and a branch name: pass a full commit sha as --ref and the flag is refused, because a sha names no branch to take a latest build from. Name the build with --app-build-id instead, which works with any ref.

​
Sync status & validation

Every sync posts a GitHub check named Autosana - 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.
This check used to be called Autosana Flows. If you list it as a required status check in a branch protection rule, change that rule to Autosana - 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.
One broken file freezes the whole repo’s materialization. The apply step runs only when the entire .autosana/ 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 workflow

Open a pull request that changes .autosana/ and Autosana 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 Autosana - Code-Managed Flows check runs on the PR. For mechanical typos on lines you changed, Autosana 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
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 autosana flows validate before merging to catch cross-file issues early.
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, Autosana 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).
Renaming or moving a flow file without an explicit key splits its history. Because the key defaults to the file path, moving login.flow.yaml to auth/login.flow.yaml archives the old flow (login) and creates a new one (auth/login). Set an explicit key: (see Flow files) so the record — and its run history — 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 Code-Managed Testing toggle isn’t enabled for the repository
  • The push wasn’t to the default branch, or didn’t touch any file under .autosana/ (or under <root-directory>/.autosana/)
  • Your .autosana/ folder isn’t at the repository root and no Root directory is set for the repo
  • Another file in .autosana/ 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 — push a newer commit, or toggle Code-Managed Testing off and on to force a full resync
Solutions:
  • Enable the toggle in Settings > Integrations > GitHub
  • Confirm you pushed to the default branch and edited a file under .autosana/
  • Open the Autosana - Code-Managed Flows check on the commit and fix every reported error — apply only runs at zero issues

​
The Autosana - 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 autosana 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 Autosana - Code-Managed Flows check on the merge commit and fix the reported cross-file errors
  • Run autosana flows validate on the whole .autosana/ folder before merging

​
My suite won’t run against a branch

Running a suite against a branch fails with an error naming one or more flow files, instead of starting the run:
Autosana refuses to run a suite when one of its tests is missing. A suite that runs four tests out of five and still reports a pass would hide the fact that a test never ran. This happens when the suite has no flows: list. Without one, its tests are every .flow.yaml file sitting next to its _suite.yaml — and on that branch, one of those files couldn’t be read. Only runs you start against a branch are refused this way. The automatic check on a pull request is unaffected, because suite changes there don’t apply until you merge (see Pull request workflow). Possible Causes:
  • The file has a YAML error
  • The file couldn’t be downloaded from GitHub
  • Two files claim the same key, so both were dropped
Solutions:
  • Fix or delete every file the error names. It lists them all at once, so you can repair them in a single commit
  • Run autosana flows validate to reproduce a YAML error or a duplicate key
  • If a file failed to download, start the run again — nothing is wrong with the file. If the same error comes back, check that the file is committed on that branch
  • Give the suite an explicit flows: list. Its tests are then the ones you name rather than whatever the folder happens to contain. A branch run reads this list from the branch, so it takes effect immediately

​
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 .autosana/ YAML file in your repository and push, or open a PR to preview the change

​
Next Steps