Pipeline & Environments - Veltrix Documentation

Overview

The pipeline is how an approved configuration reaches the systems it manages. Veltrix shows it in four places, and defines where and how deployments go with environments, environment controls and deployment flows.

Surface	Where	Use it to
Pipeline dashboard	Sidebar, Pipeline (`/pipeline`)	See pending approvals, running and failed deployments, and open drift at a glance.
Environment matrix	Pipeline, Environments tab (`/pipeline/environments`)	See what is deployed where.
Drift	Sidebar, Drift (`/pipeline/drift`)	See drift records.
App pipeline	Apps, open an app, Pipeline (`/apps/<app>/pipeline`)	Run the pipeline for every configuration of one app.
Environments	Sidebar, Environments (`/environments`)	Create environments and set their deployment controls and promotion flows.

The Pipeline sidebar item carries a badge with the number of configurations pending approval, and the Drift item carries the number of unresolved drift records.

The stages are Draft, Validate, Approve, Deploy, Live and Monitor. Monitor is the continuous drift check that runs after a configuration is live.

The pipeline dashboard

Pipeline opens the Security-as-Code Pipeline page, with tabs for Dashboard, Environments and Drift. The Refresh button reloads it.

Card	Counts
Pending Approvals	Configurations in Pending approval.
Active Deployments	Deployments that are Queued, In progress or in Health check.
Failed Deployments	Deployments in the Failed state. This is a running total of failed deployment records, not a time window.
Drift Alerts	Drift records that are not resolved. Red when above zero.

Below the cards, the Configuration Drift panel lists up to ten unresolved drift records, each expandable to its field-by-field changes, with an Acknowledge button if you have write access. The Pipeline Activity panel repeats the four counts, and a legend shows the stages. On the Free plan the drift panel shows an upgrade prompt instead of records.

The app pipeline

Open an app from Apps, then choose Pipeline in the app's navigation. It lists every configuration of every configuration type of that app in one table, with the same actions as a type's own list.

Columns: expand arrow, Name, Type, Status, Version, Environment, Updated, Actions. The Type column shows the configuration type; Environment shows each assigned environment as a badge.
Filters: search, Status, Configuration type and Environment. Sort by Name, Type, Status or Updated.
The expand arrow shows the configuration's stage timeline (Draft, Validate, Approve, Deploy, Live), with errors and active steps highlighted.
Row actions are the ones described under The configuration list. Edit opens the configuration's type page, which owns the editor.
Deploy is enabled per row against that row's own configuration type.
Roll back is not offered in this table's details window. Use the configuration type page.

A hint under the table summarises the prerequisites: an approved configuration, an assigned environment and a registered connection.

Deploying, statuses and rollback

Deploy a configuration

Make sure the configuration is Approved (or Deploy failed or Rolled back, which can be retried), has an environment, and a matching connection exists in that environment. Zone-scoped types also need a domain.
Choose the Deploy (rocket) action. The portal says "Deployment started" and watches the deployment for about a minute.
On success you see "Deployment succeeded". On failure a Deployment failed window shows the reason; the same reason stays on the row and in the details window.
If a deployment is still running when the portal stops watching, refresh the list; the status keeps updating.

The deployment goes to the configuration's first environment, using that environment's deployment strategy. Before it runs, Veltrix checks that the configuration is deployable, that the previous environment in the flow succeeded when one is required, and that your plan allows the strategy.

Deployment statuses

Status	Meaning
Queued	Waiting for a worker.
In progress	The app's deploy handler is applying the change.
Health check	The app's health check is running (canary steps and blue/green).
Paused	Stopped between steps. Pausing and resuming are available through the REST API.
Succeeded	Live. Shown as "Live" in the environment matrix.
Failed	A target failed or a health check failed. The configuration becomes Deploy failed.
Rolling back, Rolled back	A rollback is running, or finished.

Roll back

Open the configuration's details window from its configuration type page.
Choose Roll back (shown for Deployed and Deploy failed) and confirm.
Veltrix finds the latest successful deployment and re-applies the state that was live before it.

A rollback needs an earlier deployment to return to. For a first deployment you get "No previous deployment to rollback to".
Rollbacks always run as a direct deployment and create their own deployment record.
If the environment's Auto-rollback on error is on (the default), a failed deployment queues a rollback by itself when an earlier deployment exists.

Safeguards

Deployment creation is serialized per configuration and environment, so a double-click or a retry cannot start two deployments at once.
Concurrent deployments across your organization are limited by plan: Free 1, Starter 3, Professional 10, Enterprise 50. The error reads "Concurrent deployment limit reached".
Validate, deploy, rollback and on-demand drift checks share a limit of 30 operations per minute per organization.
A deployment stuck in Queued, In progress or Health check is failed automatically after 60 minutes by default, which frees its slot.
Notification links to a deployment open the Pipeline dashboard.

Deployment strategies

The strategy is set per environment under Controls. The portal always uses it; it does not ask each time. The REST API can pass a strategy per deployment.

Strategy	How it deploys	Plan
Direct (dev/test only)	Applies to every target, then runs a final health check.	All plans
Rolling (default)	One target at a time, with a health check after each. An unhealthy target fails the deployment.	All plans
Canary (progressive %)	Deploys to an increasing share of targets following the Canary steps (default 10, 25, 50, 100), with a health check at each step.	Professional and Enterprise
Blue / Green	Deploys to all targets, health checks them, and marks the deployment live only if healthy; otherwise the existing deployment stays in service.	Professional and Enterprise

Selecting Canary or Blue / Green on a plan that does not include them is not blocked when you save Controls. The deployment is refused when you deploy, with an upgrade message.

What a target is depends on the app: a server for host-based apps, or a domain for zone-scoped types. Health checks are performed by the app's own health check handler.

The environment matrix

Pipeline, Environments tab shows what is deployed where. Each row is a configuration; each column is one of your environments, in name order.

The first column shows the configuration name, its tool and type, and its status badge. It stays in view while you scroll across environments.
A cell shows the latest deployment of that configuration to that environment: a status icon and label (Succeeded is shown as "Live"), the strategy, a health score, and how long ago it started or completed. A dash means it has never been deployed there.
The health score is green at 90% or above, amber at 70% or above, and red below.
Filter canvases matches the configuration name, tool or type. Refresh reloads.
A legend explains Succeeded, In Progress, Paused, Failed, Rolling Back, Queued and Not Deployed.

The matrix shows the most recent attempt, so a cell can show Failed even though an earlier successful deployment is still the one in place. Open the configuration's Pipeline tab for the per-environment history.

Environments and controls

Environments lists your environments with the columns Environment, Owner, Controls (a summary badge and the strategy) and Deployments (the number of deployments recorded). Actions per row are Edit, Controls and Delete; New environment and Refresh are at the top.

Create or edit an environment

Field	Meaning
Name	Required and unique within your organization (for example production).
Environment type(s)	One or more of: Production, Pre-production, Staging, QA, UAT, Development, Testing, Sandbox, DR, Demo, Other. Types are what deployment flows order stages by.
Owner	A user in your organization, or no owner.

Controls

Controls is the deployment policy for one environment. Defaults apply until you save.

Control	Default	Meaning
Require approval before deploying	On	The list shows "Approval required · N approvers" when on and "Auto-deploy" when off. When off, a deployment to this environment does not wait for the configuration to be Approved. This only applies on plans that include approval workflows; the Free plan has none, so a Free organization can deploy without approval whatever this setting says.
Minimum approvers	1	Whole number, 0 or more. How many approvals make a configuration Approved.
Required approver roles	None	Pick from your roles. Each selected role must be held by at least one approving reviewer. Leave all unchecked to allow any role. A saved role that no longer exists is shown as "(removed)".
Deployment strategy	Rolling	Direct, Canary, Blue / Green or Rolling. See strategies.
Canary steps	10, 25, 50, 100	Shown when the strategy is Canary. Comma-separated percentages, ascending, each 1 to 100.
Health check timeout (s)	300	Whole number of seconds, 0 or more. A health check that has not finished within this time counts as failed. 0 means no time limit.
Error rate threshold (%)	5	0 to 100. The share of failed checks, across the components being checked, that a deployment can tolerate. If the failed share is above this value the health check fails and the deployment is marked failed. Use 0 to tolerate no failed check.
Auto-rollback on error	On	Queues a rollback after a failed deployment when an earlier deployment exists.
Require a previous environment to pass first	Off	When on, choose the Previous environment. A deployment to this environment is refused until the configuration has succeeded there. It cannot be the environment itself.

Delete an environment

Confirm the dialog. Deletion is refused with a message such as "This environment has 3 deployment(s) and 1 drift record(s); remove or resolve them first" while any deployment or drift record refers to it.

Plan allowance

Your plan sets an environment allowance (Free 2, Starter 5, Professional 10, Enterprise 50), shown in the usage view in Billing. Creating an environment beyond it is refused with "Environment limit reached". Environments you already have are never removed or blocked.

Deployment flows (promotion)

A deployment flow defines how an app's configurations are promoted across environment types, for example Development, then Staging, then Production. It lives inside an environment's Controls: open Environments, Controls and scroll to App deployment flow.

Choose the App. The last app you used for that environment is remembered.
Choose a Preset: Direct to prod, Dev, then Prod, Dev, then Staging, then Prod, Dev, then QA, then Staging, then Prod, or Custom. The preset always reflects the stages below it. Inside an environment's Controls only presets whose types the environment carries are offered, and stage types are limited to the environment's own types.
Choose the Approval mode.
Edit the stages: pick each stage's type, move stages up or down, remove one, or Add stage. A hint under each stage lists the environments that carry that type ("no environment carries this type yet" if none).
Choose Save flow. Every stage needs a type, a type can appear only once, and an app must be selected.

Approval mode	Behaviour
Approval at every stage	Each stage requires approval.
Single approval promotes all	Only the first stage requires approval; later stages promote once the previous stage has deployed.
Auto-promote if already approved	Same as above: approve once at the first stage.
Per-stage (customize each)	Each stage has Require approval and a minimum number of approvers.

What saving does

Each stage resolves to the environments of that type. Every stage after the first requires the previous stage's environment to have a successful deployment first.
Veltrix writes app-specific policies for those environments. For that app they take precedence over the environment's own Controls for approvals; strategy, canary steps, health check timeout, auto-rollback and error rate threshold start from the values already set in the environment's Controls and are not changed by saving the flow. Environments that are no longer in the flow lose their app-specific policy and fall back to Controls.
A configuration's Pipeline tab in the details window shows the flow: the ordered stages, each environment's deployment status (Deployed, Deploying, Failed, Rolled back, Not deployed), and each stage's state: Deployed, Deploying, Failed, Blocked (with the reason, for example "Must deploy to the staging stage first"), Ready, or Pending. Without a flow it says "No promotion flow configured" and deployments go straight to the selected environment.

Plans, permissions and gotchas

Item	Free	Starter	Professional	Enterprise
Concurrent deployments	1	3	10	50
Canary and Blue / Green	No	No	Yes	Yes
Approval workflow	No	Yes	Yes	Yes
Drift detection	No	Yes	Yes	Yes
Environment allowance	2	5	10	50

Permissions

You can	Permission needed
View the dashboard, matrix and deployments	Configuration Canvas read
Validate, deploy, roll back; acknowledge drift	Configuration Canvas write
See the New environment, Edit, Controls and Delete buttons	Configuration Canvas write
Read or save an app's deployment flow	Apps read or write

Gotchas

"Auto-deploy" means the environment does not require approval. It has no effect on the Free plan, where approval is never required.
After you save a deployment flow for an app, edit that app's approval thresholds in the flow, not in the environment's Controls.
The portal deploys to a configuration's first environment. Promoting to another environment is done by changing the configuration's environment, or through the REST API's deploy and promote calls.
Pausing, resuming and promoting a running deployment are available through the REST API, not as portal buttons.