Environments & Promotion
The platform can move agents and workflows between stages (development, staging, production) and between platform instances (for example from the Tietai cloud to a hospital). You can use it through Tiet · Hub → Platform → Environments and through the REST API. Read the next section first, because three different things in the product carry the word "environment" or "deploy".
The navigation below matches frontend feat/849-light-rebrand at 3a99cf9. The Environments page is under Tiet · Hub → Platform; its route remains /studio/environments.
What you can use today
| Where | What it does |
|---|---|
| Tiet · Studio → Workflows → Builder → Deploy menu | Sets a pipeline's status to deployed:<environment slug> for the environment you pick, and exports JSON or YAML. It does not check hashes, ask for approval or record a receipt. |
| Admin Console → Platform → Environments | Manages organization environments in the auth service: name, description, icon, region, cluster name, default flag and variables. It has no routes, policies, approvals or releases. |
Tiet · Hub → Platform → Environments (/studio/environments) | The page for the environments described here: environments with policies, routes, manifests, trusted sources, approvals and trace retention. See below. |
| The REST API described on this page | The same system, for scripts: environments, routes, manifests, signed releases, promotion, approvals and receipts. |
The shipped hydra command line has no export, diff, apply, deploy, env or approvals commands. Use the page or the API.
The Environments page
Everyone with access:hydra can read it. Changing anything needs superuser or the Manage Environments permission (manage:hydra.environment); without it the page says You can view environments. Changing them needs the Manage Environments permission. The page has a Run in selector (see Tiet · Studio Builder) and, for managers, the buttons Register remote instance and New environment. Its tabs:
| Tab | What it holds |
|---|---|
| Environments (n) | A table with Environment, Slug, Rank, Status (badges Default, Protected, Entry, Remote, Archived) and, for managers, Actions: move up or down, Deploy to the environment, What runs in it, Variables of it (local environments), Test connection and Reconnect (remote ones), Edit, Archive. The default environment cannot be archived. Show archived (n) lists archived ones. |
| Routes (n) | The Promotion graph and a Routes editor: Route from, Route to, Save routes. No routes: every environment is an entry environment. The server refuses cycles, self-routes and routes to unknown or archived environments. |
| Agents & workflows | Import agents and workflows from manifest YAML files (with I reviewed the permission findings and Create drafts), and a list of agents and workflows with a download per manifest. |
| Trusted sources | Source instances that tried to deploy here, with Key fingerprint, Trust and Revoke. |
| Approvals | Releases waiting for approval, with Approve and Reject. |
| Retention | Trace payload retention in days per scope. Needs the Manage Compliance permission to change. |
The New environment and Edit dialog has Name, Slug, Description, Colour, Rank (display order only; routes decide promotion) and a Policy section: Protected, Allow direct deploy, Allow draft execution, Default environment, Promotion into this environment (Approvers required, Four-eyes (requester cannot approve), Approver permission, Require a change reference, Approval expires after (hours), Required compliance gate), Rollback (four-eyes) and Reason for the change. Register a remote instance asks for API URL, Name here, Slug here, Environment on the target and Token issued by the target, then pins the key fingerprint the target presents. The deploy dialog for a remote environment asks for Promote from (Choose the environment the versions come from), a Reason and a Change reference. I read these screens in the source; I did not run them.
The Builder Deploy menu
The Deploy button in the Builder toolbar opens a menu with the header "Pipeline version · environment of the active project".
| Item | State |
|---|---|
Deploy version to environment (one per other active environment; No other environments. if none) | Active. Saves the pipeline, then sets its status to deployed:<slug>. |
| Export as JSON, Export as YAML | Active |
| Enable schedule, Enable trigger, Push to external platform instance, Deployment history | Shown but disabled |
A pipeline saved from the Builder is not a versioned release. It runs only in environments whose policy allows draft execution. The versioned, hash-checked promotion below applies to published workflow versions and agents.
Concepts
| Term | Meaning |
|---|---|
| Environment | A named stage of your organization. Local is a stage on this instance; remote is another platform instance that you deploy to by push. |
| Default environment | Where a run executes when it names none. |
| Route | An allowed promotion path, for example development → staging. An environment with routes into it is reached only by promotion. |
| Policy | protected, allow_direct_deploy, allow_draft_execution, and promotion rules: min_approvers, four_eyes, approver_permission, require_change_reference, approval_ttl_hours. |
| Manifest | A portable YAML or JSON document for one agent or workflow version. It refers to other items by slug@version and carries no credentials. Its SHA-256 identifies the version. |
| Release | A signed set of manifests going to one environment, with who asked, why and the change reference. Every release is signed, even inside one instance. |
| Receipt | The target's signed confirmation of what it applied. |
Two rules explain most behaviour:
- An environment whose policy allows draft execution runs what you ask for. Any other environment runs exactly the version deployed to it.
- A version is promoted only from an environment that runs it, with the same hash.
Default environments
An organization with no environments gets these on first use (pkg/deployenv/defaults.yaml). All of it can be edited afterwards.
| Environment | Default | Protected | Direct deploy | Draft execution | Approval needed to enter |
|---|---|---|---|---|---|
development | yes | no | yes | yes | none |
staging | no | no | no | 1 (direct deploy is off) | |
production | yes | no | no | 1, four-eyes, change reference required |
Routes: development → staging → production.
Export a manifest and dry-run it
All paths are relative to the instance API root, /api on hydra-server. Authenticate with a login token or an API token that holds the scope shown.
# list exportable workflows (needs read:hydra.builder or scope manifests:read)
curl -s "$HYDRA/api/manifests/workflows" -H "Authorization: Bearer $TOKEN"
# one manifest as YAML; the hash is in the X-Hydra-Manifest-SHA256 header
curl -si "$HYDRA/api/manifests/workflows/triage/1.0.0" -H "Authorization: Bearer $TOKEN"
# plan an apply without writing anything
curl -s -X POST "$HYDRA/api/manifests/apply?dry_run=true" \
-H "Authorization: Bearer $TOKEN" --data-binary @triage.yaml
GET /api/manifests/{agents|workflows}/{slug}[/{version}] accepts ?format=json. POST /api/manifests/apply also takes mode=deploy|draft, environment=<slug> and review_token=<slug>:<token>. A deploy through this endpoint is accepted only into the organization's default local environment, and only if it allows direct deploy. Every item is planned first; if one is refused, nothing is written. The body is limited to 4 MiB.
Deploy or promote to an environment
POST /api/environments/{slug}/deployments works for local and remote environments.
curl -s -X POST "$HYDRA/api/environments/staging/deployments" \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
-d '{
"from": "development",
"items": [{"kind": "workflow", "slug": "triage", "version": "1.0.0"}],
"reason": "QA sign-off",
"change_reference": "CR-1234",
"dry_run": true
}'
The answer has a status (planned for a dry run), the release, and one entry per item with an action (create, update, unchanged or refused). Send the same body with "dry_run": false to deploy.
What is checked:
| Check | Failure |
|---|---|
| You may export every item | 403 cannot export ... |
A route from → target exists, and from is given when routes lead into the target | 422 there is no promotion route ..., environment ... is reached by promotion only |
Each item is deployed in from, at the same version | 409 ... is not deployed in ..., ... runs <slug>@<version>, not ... |
The hash matches what from runs | 409 ... differs from what ... runs |
| A change reference, when the policy requires one | 422 environment "..." requires a change reference |
| The instance has a signing key | 503 this instance has no signing key (...); it cannot sign releases |
| The environment is active | 409 archived |
A promotion into itself is refused (422). Checks run again when a held release is finally approved. If anything changed while it waited, the release fails and nothing moves.
Remote environments
A remote environment is registered with POST /api/environments and "location": "remote", a remote object (base_url, key_id, environment) and a token. Each instance needs an Ed25519 signing key (HYDRA_INSTANCE_SIGNING_KEY_FILE) and ENCRYPTION_MASTER_KEY. GET /api/instance is public and shows the instance id and key fingerprint (key_id); the two administrators compare fingerprints out of band.
The source sends the signed release to the target's POST /api/deployments/receive using a token with the deployments:write scope. The target accepts only from a source key its administrator trusted (GET /api/instance/trust, then POST /api/instance/trust/{id}/trust or revoke). The first push from an unknown key answers pending_trust; trust the key on the target, then deploy again. Credentials never travel in the release: the target uses its own variables and connectors.
Promotion statuses
On the source, the deployment answer and release record use these statuses:
| Status | Meaning |
|---|---|
planned | Dry run only |
pending_trust | The target does not trust the source key yet |
pending_approval | Held for approval (HTTP 202) |
applied | Applied; for a remote target, a receipt was verified |
refused | A check failed; nothing moved |
unknown | The request did not complete. Check what runs on the target before deploying again |
On the target, the approvals inbox (GET /api/deployments/pending[?status=]) uses pending, applied, rejected, expired and failed.
Approvals
A release is held when the target environment's policy requires approvals, does not allow direct deploy, or is protected. At least one approval is required in the last two cases.
curl -s "$HYDRA/api/deployments/pending?status=pending" -H "Authorization: Bearer $JWT"
curl -s -X POST "$HYDRA/api/deployments/pending/$SOURCE_INSTANCE/$RELEASE_ID/approve" \
-H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -d '{"comment":"Reviewed"}'
Rules enforced by the server:
- Approvers hold the environment's approver permission (default
approve:hydra.promotion). - Each person decides once (409
you already decided on this release; another approver is needed). - The requester cannot approve (403
the requester cannot approve their own release). API tokens cannot approve (403releases are approved by people, not API tokens). - The last required approval re-checks and applies the release. Any rejection ends it.
- A held release expires after the policy's
approval_ttl_hours; the default is 72.
For a remote target, the source collects the outcome with POST /api/environments/{slug}/releases/{id}/refresh. See what runs in an environment with GET /api/environments/{slug}/deployments and the push history with GET /api/environments/{slug}/releases.
Rolling back
There is no rollback operation. For workflows, deploy the previous published version again through the normal route and approvals. For agents, an instance has one live version, so you publish a new agent version with the previous content and deploy that.
Limits
- Runs started by inbound triggers (for example HL7 over MLLP) and other internal paths carry no environment. They use the instance configuration and current versions.
- An agent can be deployed to a local environment only at its live version. A later change shows as drift, and runs of that agent there are refused until you deploy again.
- Push only: the target must be reachable from the source over HTTPS.
manage:hydra.environment, required to manage environments and deploy, and the default approver permissionapprove:hydra.promotionare not in the permission catalog of the auth service ondev(I searched it), so in practice only superusers can manage environments.- A release gate (the policy's
required_gate_profile, shown as Required compliance gate) can hold or refuse a local deployment. A gated environment refuses releases received from another instance (environment "..." has a release gate; releases into it are deployed on this instance, not received, 422). I read this in the source and did not run it.
Related
- Run on Mesh: executing across sites
- Tiet · Studio Builder: the Deploy menu
- Administration: organization environments in the Admin Console
Something unclear? Send documentation feedback by email.