Releases
Releases deploy blueprint changes to a cloud environment via Terraform apply, covering release types, statuses, sign-off, labels, and metadata.
A release deploys changes to a cloud environment. Every change to a running environment, a new Redis, a new application build, a changed alert, goes out through a release. Facets runs releases with terraform apply, doing a three-way comparison to work out and apply only what needs to change:
- The current state of the environment.
- The state defined by the Terraform generated from your blueprint.
- The desired end state.
Scheduling and queueing
Releases can run on a schedule, and you can trigger one manually at any time. Changes made between releases (disk expansion, a new build, changed alert definitions) accumulate and go out together in the next release.
If a release is already in progress, a manually triggered release joins a queue rather than being rejected, so you never have to wait for the current one to finish before starting the next. Queueing is a status, not a release type: a queued release has no release ID until it is dispatched. A scheduled release that lands while another is queued is skipped, it does not stack up.
Types of release
| Type | What it does |
|---|---|
| Full | The default. Synchronises every change in the environment. |
| Selective | Deploys a chosen set of resources, typically for an out-of-turn hotfix. |
| Plan | Previews the changes for review and approval before applying. Covers the whole environment (Full Plan) or selected resources (Selective Plan); the reviewed plan is then deployed as an Apply Plan. |
| Custom | Lets power users issue Terraform commands directly for full control. |
| Launch | Launches a new environment for the first time. |
| Destroy | Tears down all resources Facets provisioned. |
| Maintenance | Applies Infrastructure as Code (IaC) upgrades. |
| Rollback Plan / Apply Rollback Plan | Previews, then applies, a restore of a previous release's deployment context. See Rolling back. |
A few more types appear in an environment's release history, raised by specific actions rather than triggered as a release: UNLOCK_STATE (the Unlock State button, which releases a held Terraform state lock by lock ID); SCALE_UP and SCALE_DOWN (the Scale Up and Scale Down actions, also raised by a time-sensitive environment on bring-up and teardown); and TERRAFORM_EXPORT (the Export Terraform action, which generates the downloadable Terraform configuration, also available as raptor create terraform-export -p PROJECT -e ENVIRONMENT).
Release statuses
| Status | Meaning |
|---|---|
| SUCCEEDED | Completed successfully |
| FAILED | Encountered errors |
| IN_PROGRESS | Currently executing |
| QUEUED | Waiting to execute |
| PENDING_APPROVAL | Requires approval before proceeding |
| ABORTED | Manually stopped |
| REJECTED | Approval was denied |
| TIMED_OUT | Exceeded the execution time limit |
| STOPPED | Terminated |
Managing a release
Signing off
Sign-off marks a release as approved for production deployment. Open the release from the Releases tab, confirm it succeeded and review the changes, then click Sign Off and confirm.
Sign-off typically gates production deployments. Make sure the release is validated before signing off.
Labels
Attach labels to categorise and filter releases.
Using prompt
Tag the last release to dev as stable.or
Using command
raptor set release-labels RELEASE_ID -p PROJECT -e ENVIRONMENT --label stableThis replaces the release's whole label set rather than adding to it, which is what the
console's label picker does too. Pass every label the release should end up with, repeating
--label, or --clear to remove them all. A label name that does not exist yet is created
with the default colour.
Name the release by its id, or by the trace id it was triggered with using --trace-id.
New to the CLI? Install it first.
- Open the release.
- Click Attach Labels.
- Select labels from the list.
- Click Apply.
raptor get labels lists the labels available to attach. raptor create label NAME adds
one ahead of time, with --color for a hex colour, and raptor delete label NAME removes
it from every release carrying it.
Metadata
Upload custom metadata as a JSON file to integrate with external systems: open the release, click Upload Metadata, select the file, and click Upload. The metadata is stored in S3 for later retrieval.
Praxis (Facets' AI agentic platform) helps with releases in two ways: Release Approval gates a release behind manual approval, and it can diagnose a failed one (see Debug a failed release below).
Debug a failed release
When a release fails, Praxis (Facets' AI agentic platform) can find out why. Click the AI debug icon next to a failed release on the Releases tab, or ask Praxis to "debug this release", and it opens with the deployment context already loaded.
Praxis investigates read-only: it reads the full deployment logs (delegating long ones to a focused log-analysis sub-agent), checks the resource configuration against its schemas, inspects the module's Terraform when needed, and reads Kubernetes and Helm state (pod status, events, revision history). It then classifies the failure, whether configuration, permission, state lock, Helm conflict, Kubernetes timeout, or a module bug, and reports the root cause with the exact fix, backed by evidence rather than a guess.
It recommends but never changes: Praxis cannot restart, delete, deploy, or edit infrastructure, so you review the diagnosis and apply the fix yourself, through the UI or a new release. Inspecting Kubernetes and Helm state needs a connected environment. For the permission, credential, and safety model behind this, see How Praxis works.
Troubleshooting
| Problem | Solution |
|---|---|
| Null release type error during deployment creation | Specify a release type. The error is raised when it is null. |
| BadRequestException, ProdReleaseDisabled, or ReleasePausedException | Check environment configuration and release permissions. These halt release creation. |
| Deployment ID not found | Verify the deployment exists. The error is raised for an invalid deployment ID. |
| Log streaming timeout | The connection closes automatically after a timeout. Refresh to reconnect. |
| Log stream EOF | Normal for a finished release. It signals log completion. |
| Helm rollback failure | Review the error logs. Helm exceptions carry their original cause. |
FAQ
What is a release in Facets? A way to deploy changes to a cloud environment. Facets runs it with terraform apply and a three-way comparison of state to work out and apply only what needs to change.
What is a Full Release? The default release type, which synchronises every change in the environment.
What is a Selective Release? A release that deploys a chosen set of resources, commonly used for out-of-turn hotfixes.
What happens to a scheduled release when one is already queued? It is skipped. It does not enter the queue or interrupt the release in progress.
Explore
Strategies
- Canary releases: roll out to a subset of pods first, then promote or abort.
- Parallel releases: run non-conflicting selective releases at once.
- Guardrail policies: enforce standards on blueprints with Rego, gating releases on violations.
Approval and control
- Approval workflow: gate a release behind manual sign-off.
Operations
- Releasing: perform a release, step by step.
- Validation panel: catch broken references and policy violations before release.
- Rolling back: restore a previous known-good state.
Custom Domains (Ingress)
Map a custom domain to services in a Facets environment by adding a domain alias and URL on the Ingress resource, then creating a CNAME at your DNS provider.
Canary releases
Configure Argo Rollouts canary deployments for Facets services: set rollout behavior, trigger a release, monitor pods, then promote or abort.