Skip to main content

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".

Which version this page describes

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​

WhereWhat it does
Tiet · Studio → Workflows → Builder → Deploy menuSets 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 → EnvironmentsManages 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 pageThe 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:

TabWhat 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 & workflowsImport 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 sourcesSource instances that tried to deploy here, with Key fingerprint, Trust and Revoke.
ApprovalsReleases waiting for approval, with Approve and Reject.
RetentionTrace 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".

ItemState
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 YAMLActive
Enable schedule, Enable trigger, Push to external platform instance, Deployment historyShown but disabled
Pipelines are not release artefacts

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​

TermMeaning
EnvironmentA named stage of your organization. Local is a stage on this instance; remote is another platform instance that you deploy to by push.
Default environmentWhere a run executes when it names none.
RouteAn allowed promotion path, for example development → staging. An environment with routes into it is reached only by promotion.
Policyprotected, allow_direct_deploy, allow_draft_execution, and promotion rules: min_approvers, four_eyes, approver_permission, require_change_reference, approval_ttl_hours.
ManifestA 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.
ReleaseA signed set of manifests going to one environment, with who asked, why and the change reference. Every release is signed, even inside one instance.
ReceiptThe target's signed confirmation of what it applied.

Two rules explain most behaviour:

  1. An environment whose policy allows draft execution runs what you ask for. Any other environment runs exactly the version deployed to it.
  2. 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.

EnvironmentDefaultProtectedDirect deployDraft executionApproval needed to enter
developmentyesnoyesyesnone
stagingnonono1 (direct deploy is off)
productionyesnono1, four-eyes, change reference required

Routes: development → staging → production.

Promotion path from development to staging to 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:

CheckFailure
You may export every item403 cannot export ...
A route from → target exists, and from is given when routes lead into the target422 there is no promotion route ..., environment ... is reached by promotion only
Each item is deployed in from, at the same version409 ... is not deployed in ..., ... runs <slug>@<version>, not ...
The hash matches what from runs409 ... differs from what ... runs
A change reference, when the policy requires one422 environment "..." requires a change reference
The instance has a signing key503 this instance has no signing key (...); it cannot sign releases
The environment is active409 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.

Signed push from a source instance to a target instance, with approval and receipt

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:

StatusMeaning
plannedDry run only
pending_trustThe target does not trust the source key yet
pending_approvalHeld for approval (HTTP 202)
appliedApplied; for a remote target, a receipt was verified
refusedA check failed; nothing moved
unknownThe 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 (403 releases 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 permission approve:hydra.promotion are not in the permission catalog of the auth service on dev (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.

Something unclear? Send documentation feedback by email.