Configuration Exchange
Settings → Configuration Exchange moves platform configuration in and out of Hegemony. Platform configuration comes in only as YAML that an admin imports; it goes out as downloadable YAML or as scheduled exports to a Git repository. Flows linked to Git are the one exception: each is pulled from its own page (see building flows). Use it for backups, migrating between environments, and keeping your platform config in Git. It requires the platform admin role.
Export and import YAML (Platform<>YAML tab)
Download exports the platform's configuration into a single hegemony-export.yaml file - a reviewable backup you can re-import into another environment. It covers organizations and their memberships, sites, devices, flows and their attachments, variables, notification destinations and subscriptions, schedules, webhooks, Git repositories, file repositories, inventory providers, secret backends, route permission overrides, and the platform Git profiles themselves. Use Load Template for a commented example of every section. Each value is written on one line, however long, so a secret ref such as {{ secret('vault://...') }} is never split and stays easy to search for and diff.
Upload imports the same format. Paste YAML or choose a file, then:
- Preview Changes - a dry run. You get a per-section summary (created / updated / skipped / errors) and per-entity field diffs, with nothing applied yet. If the preview is clean, Apply Import commits it.
- Import - applies directly, skipping the preview.
Import rules worth knowing (the Load Template button fills the editor with a fully commented schema):
- Entities are upserted by name - existing entries are updated, new ones created; nothing is deleted by an import.
- Secrets are exported without their values: each one carries its backend, folder and key names. An import writes
valuesinto the secrets backend, or, withkeysalone, creates the keys the backend lacks with empty values for you to fill in. A secret'sbackend_refmust name a backend that exists on the importing instance, or the preview reports the secret as an error. An import never moves a secret: naming another backend than the one an existing secret of that name lives in is an error too. A webhook endpoint carries its credential the way a Git repository does — as asecret_refnaming the secret, never the value. Path tokens stay instance-local: the first import assigns one and later imports keep it, so an endpoint's URL survives updates. Read the URL from the UI after the first import. - Imported schedules arrive disabled for safety; enable them after review.
- A flow's preselected targets and a schedule's targets name each device by inventory and name, and a step's repository files by repository and path, so they survive a move to another instance. A device or file the target does not have is left out, with a warning in the preview and the import result. A bundle from an earlier version names a device alone or by id. An id is kept as it is; a bare name resolves only when exactly one device in the target has it, and is otherwise left out with a warning.
- A
flow.notifystep names its notification destination by name in a bundle, as flow subscriptions do. The import resolves the name in the target organization, and a bundle applies its destinations before its flows, so the step works as soon as it is imported. A bundle from an earlier version carries the destination's id instead and imports as it did. - Container steps' host-access options (
privileged,attach_docker_socket,network_mode,pid_modeandextra_mounts) may only be added or changed by an admin, as when a flow is saved. An import by anyone else may bring back the options a step already holds only with the step running what it ran: the same handler, settings (image, command, entrypoint, environment and so on) and files, and, when the step mounts other steps' artifacts or outputs, the same steps before it. A flow that adds an option, changes its value, or changes what a step holding one runs is counted as an error in both the preview and the import, and is not imported. The same holds for a flow attachment such a step mounts: only an admin's import may add or change it. An import by anyone else also leaves a flow uncommitted, with a warning, when its draft already changes such an attachment against the committed version. - Credential fields hold references only: git repository
auth_secret_refandssh_key_secret_ref({{ secret('…') }}), notification destination credentials ({{ secret('…') }}or{{ vars.NAME }}), and secret backend credential fields (env()without a fallback value,file()orsecret()). An item with a plaintext value is not imported. Exports never carry a plaintext value saved before this rule: git credentials are left out and other fields read***REDACTED***, which an import refuses until the value is replaced with a reference. - A bundle that changes organizations, memberships, IdP mappings or permission overrides needs the rights the matching pages need (
org:manage,org_member:manageororg_idp_mapping:managefor that organization, andpermission:manage, which only the platform admin holds), or the platform admin role. Without them its preview, import or apply is refused with 403 before anything is applied; entries that match what is installed need no extra rights. The import checks each such entry again as it applies it: one the caller may not change is left as it is and reported as a warning. - Flows from bundles exported by earlier versions, whose steps carry
phase:/kind:fields or alabels:map (and whoseflow_defaults.nodehands every stepphase: null/kind: null), are upgraded on import: the values are folded into each step'stagsmap - an explicittagsentry wins, thenlabels, thenphase/kind- and the old keys are dropped, so re-importing such a bundle stays a no-op. The upgraded map must satisfy the step-tag rules (at most 12 tags, identifier keys, printable values); a bundle whose step breaks them is refused at import, naming the step. New bundles write them as tags (tags: {phase: VERIFY}); a step definition sent to the API withphase,kindorlabelsas a field is refused. - Platform Git profiles from bundles exported by earlier versions carry
mode,destructive_policyandauto_apply_non_destructive. The last two are dropped.mode: backupandmode: bidirectionalimport as an ordinary profile, which only exports.mode: mirroris refused, naming the profile: a Mirror profile read Git into the platform and never wrote to it, so importing it as an export would start writing the platform over the files it read. Remove the entry, or remove itsmodeline to export there.
Copy flows between organizations (Org→Org tab)
Use this to build and test flows in one organization (a staging organization, say) and then copy them to the organization that runs them. Pick the organization to copy from, the one to copy to, and the flows. Preview Changes shows what the copy holds and what it would create or update in the target; Copy applies it. Nothing is removed from the source, so to move a flow, copy it and then delete it in the source.
A copied flow brings what it needs to work:
- its attachments;
- the flows its
flow.runsteps start, and what those need in turn; - the notification destinations its
flow.notifysteps use; - the variables any of them names as
vars.NAME; - the devices it preselects as targets, with their sites, when the target does not have a device of that name.
Two checkboxes add more:
- schedules, webhooks and notification subscriptions of the copied flows, with the destinations they notify and the devices the schedules target that the target lacks. Schedules arrive turned off, and a webhook endpoint gets a new URL in the target;
- replace devices the target already has. A device the target has under the same name is otherwise used as it stands there; with this, the source's version replaces it.
The copy is an ordinary import into the target organization, so the import rules above apply: objects are matched by name, an existing one is updated, and the copy shows in Operations History as a plan and an apply. The preview also lists what to check by hand:
- Secrets are not copied. A reference under
orgs/<source>/is pointed atorgs/<target>/; the preview lists every secret the copied objects name, and each must exist in the target before they can use it. - Git links are not copied. The copy of a flow linked to Git is not linked, so that two flows never write the same file.
- A
flow.runstep or a webhook endpoint that pins a flow version runs the newest version in the target, where versions are numbered again. - A target device that comes from an inventory provider is not copied. If the target does not have it, the flow or schedule is imported without it.
A webhook endpoint whose flow no longer exists is left out.
Run history and the contents of file repositories stay in the source.
Export to Git (Platform→Git tab)
Platform Git profiles export the platform's configuration to a Git repository, on demand or on a schedule. A profile picks one of your configured Git repositories (URL and credentials live there, not here), a branch and a base path, and which resource families (flows, sites, devices, ...) to export. Each export writes one file per resource and a manifest.yaml under the base path, removes the files of resources that no longer exist, and pushes one commit. An export that finds nothing changed pushes nothing. Long values stay on one line, as in the YAML download; files written by versions that folded them over several lines change once, in line breaks only, on their next export.
The platform stays the source of truth: Git never changes the platform. Each profile's detail page offers a manual Export and the profile's run history.
Applying configuration kept in Git
To keep configuration in Git and apply it to Hegemony, have your CI pipeline call the Configuration Exchange import API (POST /config-exchange/operations) with an API token that has the admin scope: preview the import (a dry run) on the pull request, and import it when the change merges. Review happens in Git, the token makes the trust explicit, and every change still goes through the one import path, with its preview and its rules above. An import never deletes anything.
Upgrading from Mirror and Bidirectional profiles
Earlier versions also let a profile plan and apply Git back into the platform (Mirror and Bidirectional modes), with conflict resolution and destructive authorizations. That is gone. On upgrade:
- Bidirectional profiles keep exporting on their schedule, as they did.
- Mirror profiles never exported, so they are turned off rather than start writing the platform over the files they read. Their last error says so. Turn one back on to export the platform to that path, or delete it.
- Run history stays, including runs recorded as
planorapply. Plans, conflict state and destructive authorizations are deleted. - The profile API treats the old keys like an import does:
mode: backupandmode: bidirectionalare ignored along with the apply settings, andmode: mirroris refused.
Flows<>Git tab
A read-only inventory of flows linked to Git repositories, with their sync mode, status, and last sync time. Pull, push, and detach live on each flow's own page - see building flows.
Operations History tab
Every export, import, plan, and apply - YAML and Git alike - is recorded with its scope, transport, status, actor, and duration. Use it to audit who moved configuration and when.
Related
- Instance bootstrap - importing configuration automatically when a fresh instance starts.
- Git integration - configuring the repositories profiles use.