Promoting between environments
Move a published process from one Minctrl installation to another as a signed release bundle — Ed25519 signatures, trusted installations, import into review, connector mapping, the promotion log and a drift check.
Staging, a validation installation, production — each is its own Minctrl with its own database. A release bundle carries one published version of a process from one to the next, signed by the installation that published it, so the receiving side knows exactly where it came from and that nothing changed on the way.
What travels, and what never does
A bundle (minctrl.bundle/v1) carries the graph exactly as published — steps, edges, gate
forms, approvals policies, deadlines (SLA), decision tables — the process name, the source
installation, version and graph hash, who exported it and when, and the connectors the steps
call by tool-id and catalog template. It never carries a connector's URL, token, client
secret or any other credential: the receiving installation binds its own.
1. The signing key (source installation)
Settings → Environments → This installation shows the installation id and the company's
Ed25519 signing key. The first export makes one; Create signing key makes it now. Copy the
public key (minctrl-ed25519:…) and give it to the people who run the receiving
installation. The private key is sealed at rest (MINCTRL_SECRETS_KEY) and never shown or
returned by any endpoint.
Rotate key retires the active key and makes a new one. The retired key is kept and listed: bundles it signed still import wherever it is still trusted. Bundles signed after the rotation import only once the receiving side trusts the new public key too.
The signing identity is the company on its installation: on an installation several companies share, another company's trust in you never lets a third company's bundles in.
2. Trust the source (receiving installation)
Settings → Environments → Trusted installations: a name and the source's public key, then
Trust. Only bundles signed by a key listed there import; Revoke stops a key (the record
stays). Adding and revoking are audited (environment_trust_added, environment_trust_revoked).
3. Export
On the process's Versions panel, select the published version and press Export bundle
(tick with its test cases to carry the process's test suite). Only a published version is
exported. The export is audited (process_bundle_exported) and shows in the panel's promotion log.
From a script, with an API key holding processes:promote:
curl -fsS -H "Authorization: Bearer $MINCTRL_API_KEY" \
-o claims.bundle.json \
"https://staging.example.com/api/environments/processes/claims/bundle?include_tests=true"4. Import
Settings → Environments → Import a release bundle: pick the file. Before anything is written the bundle is checked:
| check | refused (422, nothing created) when |
|---|---|
| format | it is not a minctrl.bundle/v1 document |
| trust | it is signed by a key this company does not trust, or one that was revoked |
| signature | any value in it changed after signing (the signature covers the RFC 8785 canonical JSON of everything but the signature block — so a re-indented or re-parsed copy still verifies) |
| graph hash | the graph it carries is not the graph whose hash it declares |
| duplicate | it was imported here already (409) |
The preview shows who signed it, the source version, the diff against the version published here (the same diff as publishing), the test cases it carries, and every connector it needs:
- a catalog connector is mapped to one of your connections of the same template (pick it in the list) — it is bound through the catalog, so an irreversible action is bound in shadow until an owner binds it live;
- an HTTP connector needs a connector with the same tool-id configured on Settings → Connectors;
- a built-in tool needs nothing.
Import into review stores the bundle as the next version of the process, in review,
with you as its author. Unmapped connectors do not stop the import, but the version cannot be
published until each is mapped — map them later from the promotion log. The import is audited
(process_imported, source: bundle) with the bundle id, the key, the trusted source and the
source installation and version.
From a script (the version lands in review; map connectors afterwards):
curl -fsS -H "Authorization: Bearer $MINCTRL_API_KEY" -H "Content-Type: application/json" \
--data-binary @claims.bundle.json "https://prod.example.com/api/environments/bundles"5. Publish
Publishing follows the publishing rules: an owner or admin who is not the version's author — so with separation of duties on, the person who imported it does not publish it. Runs start from it once it is published.
Promotion log and drift
Each process's Versions panel lists its promotions — exported (out) and imported (in), with the source and the connectors still to map. Drift check compares the version published here with any bundle file: in sync when both run the same executable graph, otherwise the diff. The signature is checked and reported, not required — a drift check writes nothing.
Permissions and API
| permission (people) | API-key scope | |
|---|---|---|
| export, preview, import, upload | process.promote | processes:promote |
| map a connector | process.promote + connectors.manage | — (people only) |
| promotion log, drift check | any member | processes:read |
| signing key, trusted installations | settings.environments | — (people only) |
Owners and admins hold process.promote and settings.environments; a custom
role can be granted them.
| endpoint | what |
|---|---|
GET /environments/key · POST /environments/key | the installation id and public key · create or rotate |
GET/POST /environments/trusted · DELETE /environments/trusted/{id} | trusted installations |
GET /environments/processes/{slug}/bundle | download the signed bundle (version, include_tests) |
POST /environments/bundles/preview | verify + diff + connector needs, nothing written |
POST /environments/bundles/import | import with mappings {tool_id: connection_id}, with_tests |
POST /environments/bundles | upload the bundle file itself (CLI) |
PUT /environments/promotions/{id}/connectors/{tool_id} | map one connector of an import |
GET /environments/promotions · POST /environments/bundles/drift | the log · drift check |
The SDKs wrap them: Python client.environments.download_bundle / upload_bundle / preview / import_bundle / map_connector / promotions / drift, TypeScript mc.environments.downloadBundle / uploadBundle / preview / importBundle / mapConnector / promotions / drift.
Publishing processes
Every save is a draft. Its author submits it for review, an owner or admin publishes it after reading the diff — with separation of duties on, one who did not write it — and runs start only from the published version. Rollback publishes an earlier version again.
Testing processes
Write test cases for a process — inputs, the answer each gate gets, the path and outcome the run must take — run them against any version without touching a live system, compare two versions on the same suite, and make publishing require a green suite.