Skip to main content
A suite that only runs on your machine is a useful tool. A suite in your workspace is a monitored one: versioned, runnable by anyone with access, schedulable, and wired into assets, checks, issues and alerts. Two stages, in the app under Health → Reconciliations:

​
Save to Development

Prints the suite id. Requires SCOPE_RECON_EDIT.
Every save creates a new version. The change summary is what makes the version history readable six months later. If you do not give --change-summary, upload-config saves a summary that gives the file name.
A backend run never reads row values, so the workspace refuses a suite with reporting.level: detailed. The save, the promote and the run each fail with a message that names the reconciliations. A run of such a suite fails as an invalid configuration and is not retried. Use with_keys or count_only instead. See privacy levels.
suite yaml gives you a stored suite as a file that you can edit, also a suite that someone made in the wizard. Get it, edit the file, and upload-config it again. Use the same steps to copy a suite to a different workspace.

​
Bind connections to integrations

A backend run does not see the credentials in your YAML. It uses integrations: the database credentials that your workspace manages.
By default each connection name binds to the integration whose id matches it. Map them explicitly when the names differ:
In the app this is the Bind suite connections to integrations dialog.
N connection(s) could not be bound to an integration means a suite connection has no matching integration, or the integration is not enabled for reconciliation. Check the names with connections remote list --recon-deployable, or bind explicitly with --map.
If this difference is new to you, read connection vs integration. The same YAML key has two meanings in the two kinds of run, and it is the most frequent cause of confusion.

​
Start a backend run

The run is asynchronous. --wait blocks until it finishes and sets a meaningful exit code; without it, poll with synq-recon audit-logs get <invocation-id>.--invocation-id <id> makes the submission idempotent. A second submission with the same id does not start a second run. A pipeline that retries needs this.
Pass --drill=false explicitly if you do not want a drill. Omitting the flag does not mean “off”.With promote, an omitted flag keeps the stored setting. An ad-hoc run has no deployment to get a setting from. Thus, if you omit --drill, the run uses the default of the server, which is drill-down on, for each reconciliation with bisection.enabled true (the default). On a suite with many real differences, this can change a two-minute run into a fifteen-minute run with no useful result.

​
Promote to production

Promoting creates a deployment: an immutable snapshot of the suite plus its schedule, bindings, run settings and annotations.
After the promote, each reconciliation in the deployment is a platform asset that gives a check result on every run. It shows in search and lineage, is part of check categorisation, and opens issues that go through your alerts and ownership rules.

​
Schedules

Two forms, mutually exclusive:
Both take --timezone (for example UTC or Europe/Warsaw). --ical also accepts --dtstart as a start point. Use iCal for schedules that cron cannot express, for example the last Thursday of the month, the second Tuesday, or business days.

​
Two different timeouts

--timeout and --execution-timeout are unrelated, and mixing them up is easy:
  • --timeout is the budget of a local run. Default: the suite’s execution.timeout, else 5m.
  • --execution-timeout is the budget of a backend run, set on a deployment or per trigger. The server clamps it to its supported range.
A backend run takes the most specific timeout that is set: the one passed for that run, then the deployment’s, then the suite’s execution.timeout, then the server default of 15 minutes. A deployment inherits the suite’s value through its snapshot, so leave the deployment’s timeout unset unless production needs a different budget than development.

​
Editing a deployment

A deployment edit keeps the settings that you omit. deployment update always does this, and a second promote of the same suite does too. Thus a new snapshot of the suite never removes the schedule or turns off the API trigger by accident.
Removing a schedule is therefore always explicit.
A first promote applies defaults, and one of them can surprise you. With no deployment to keep settings from, a promote uses these defaults: no schedule, no API trigger, the default execution timeout of the server, and drill-down on.If you want a scheduled production run that never drills, pass --drill=false on the first promote. Do not rely on omission.
A deployment is a snapshot, not a pointer. If you edit the suite in Development, Production does not change until you promote it again. The suite card in the app shows this: “Dev has unpromoted changes” or “Up to date with prod”. Read that line before you decide that a fix did not work.

​
Keep the deployment id stable

A deployment’s id is part of every reconciliation’s asset path. Rebuilding a deployment from scratch under a new id re-homes its checks and drops their history. A second promote of the same suite uses the same id automatically. Thus this is a problem only when you rebuild a deployment on purpose. In that case, set the id:

​
Pause, resume, unpromote

Pause is for a planned maintenance window: the deployment stays configured and stops running. Unpromote deactivates it entirely; its history is kept, and re-promoting brings it back under the same id.
deployment is not active; re-promote to modify means the deployment was unpromoted. Re-promote before changing or tearing it down.

​
Inspecting what ran

A run’s --trigger says how it started, which is often the first thing you want to know: deployment history is append-only and records every promote, unpromote, schedule change, binding change, annotation edit, pause and resume. When production behaviour changed and nobody remembers why, it is the first place to look.

​
Copy production back to Development

To iterate on what production is actually running, rather than on what Development happens to contain:

​
Permissions

The app hides controls whose call would be refused, so a missing scope shows up as a missing button rather than an error. CI/CD and automation maps these to roles and to the credentials an unattended caller uses.

​
Next

Investigating results

Reading a run, and following a finding to the rows.

CI/CD and automation

trigger --wait as a release gate, exit codes and credentials.