Minctrl Docs
Guides

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:

checkrefused (422, nothing created) when
formatit is not a minctrl.bundle/v1 document
trustit is signed by a key this company does not trust, or one that was revoked
signatureany 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 hashthe graph it carries is not the graph whose hash it declares
duplicateit 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, uploadprocess.promoteprocesses:promote
map a connectorprocess.promote + connectors.manage— (people only)
promotion log, drift checkany memberprocesses:read
signing key, trusted installationssettings.environments— (people only)

Owners and admins hold process.promote and settings.environments; a custom role can be granted them.

endpointwhat
GET /environments/key · POST /environments/keythe installation id and public key · create or rotate
GET/POST /environments/trusted · DELETE /environments/trusted/{id}trusted installations
GET /environments/processes/{slug}/bundledownload the signed bundle (version, include_tests)
POST /environments/bundles/previewverify + diff + connector needs, nothing written
POST /environments/bundles/importimport with mappings {tool_id: connection_id}, with_tests
POST /environments/bundlesupload the bundle file itself (CLI)
PUT /environments/promotions/{id}/connectors/{tool_id}map one connector of an import
GET /environments/promotions · POST /environments/bundles/driftthe 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.

On this page