Skip to content
Helix Docs

Deployment approvals

Hold deployments until they're approved. Choose which deployments wait and who approves them in each workspace, then review and decide.

For IT teams Updated Nov 6, 2026
View as Markdown

Deployment approvals hold a deployment until someone approves it. You choose which deployments need approval: every deployment, or only new apps and deployments that add an authentication. The organization owner and admins can approve any deployment, and you can give each shared workspace its own approvers. A deployment waiting for approval is built but not live, and the version that was live before keeps serving until someone approves the new one.

Deployment approvals are separate from tool approval, where an agent pauses before running a tool.

How approvals work

  1. Someone deploys. Helix checks the policy when the deployment starts. Everyone’s deployments follow it, including the owner’s and admins’, and deploys from CI.
  2. The build runs as usual. If it fails, nothing waits and nobody is asked to review it.
  3. The deployment waits. Once the build succeeds, the deployment shows Awaiting approval, and the workspace’s approvers get an email. If the workspace has no approvers besides the deployer, the organization owner and admins get it instead.
  4. An approver decides. That’s the organization owner, an admin, or one of the workspace’s approvers. Approving puts that exact build live, without rebuilding it. Denying means it never goes live.
  5. The deployer hears back by email, with the approver’s message if they left one.

While a deployment waits, the project keeps serving whatever was live before, including its scheduled jobs. The waiting deployment’s own scheduled jobs start only once it goes live. For a new app, nothing is live until its first deployment is approved, and the app doesn’t appear in the App Library until then.

Who can do what

The organization owner and admins approve deployments in every workspace. A shared workspace can also have its own approvers, who approve that workspace’s deployments.

Organization owner and adminsA workspace’s approversEveryone else
Turn approvals on or off, choose which deployments need approval, and choose each workspace’s approversYesNoNo
Approve or deny a deploymentYes, in every workspace, including their ownYes, in their workspace, except their ownNo. They can open a read-only Preview
Their own deployments wait for approvalYesYesYes

You can’t exempt a person or an API user from the policy. To change who approves in every workspace, change people’s organization roles under Organization settings, on Members. To choose who approves in one workspace, see Choose a workspace’s approvers.

Because the owner and admins can approve their own deployments, approvals don’t guarantee that a second person reviews their changes. A workspace’s approvers can’t approve their own. The activity trail records who approved each deployment, so you can check after the fact.

Turn on approvals

  1. Open the user menu and choose Organization settings.
  2. Under Policies, choose Deployments.
  3. Under Which deployments need approval, tick the deployments to hold.
  4. Choose Turn on approvals.

The same deployments need approval in every workspace in the organization, and there are no per-project rules. Only who approves can differ from one workspace to another.

It applies to deployments that start after you turn it on. Apps that are already live stay live, and a deployment that is already building when you save isn’t held.

Which deployments need approval

OptionA deployment waits when
Every deploymentAlways. Ticking it also ticks and locks the other two
New appsThe project has nothing live yet. That covers an app’s first deployment, and any deployment of a project whose earlier deployments all failed, were denied, or were withdrawn
New authenticationsIt uses an authentication that the live deployment doesn’t. Keeping the same authentications, or removing some, doesn’t count

New apps and New authentications are ticked by default. With both ticked, a deployment waits if either applies. You need at least one.

To change the choice later, change the ticks and choose Save. Narrowing it doesn’t release deployments already waiting, so approve or deny those yourself.

Choose a workspace’s approvers

Give a shared workspace its own approvers when someone other than the organization owner and admins should review its deployments, such as the team that owns it. Its Approval needed emails then go to its approvers instead of the owner and admins, and its approvers can approve or deny its deployments. The owner and admins can still approve them too.

  1. In Organization settings, under Policies, choose Deployments. Who approves appears once approvals are on.
  2. In the list of workspaces, choose Add approvers next to the workspace, or Edit if it already has some.
  3. Tick the members who should approve, then choose Save.

The list has every shared workspace in the organization, including ones you aren’t a member of. Each shows its approvers, or Owner and admins when it has none.

  • Approvers must be members of the workspace with Contributor access or higher. Viewers are listed, but you can’t pick them. Change someone’s access on the workspace’s Members page.
  • API users can’t be approvers.
  • A workspace can have up to 50 approvers.
  • Only shared workspaces can have approvers.
  • To hand a workspace back to the owner and admins, remove all its approvers and save.

A change applies straight away, including to deployments already waiting: someone you add can decide them, and someone you remove can’t. A waiting deployment still names, and has already emailed, the approvers its workspace had when the deployment started.

An approver who drops below Contributor access, or leaves the workspace, can no longer approve its deployments and isn’t emailed about new ones. They stay in the workspace’s list, and saving its approvers fails, naming them, until you remove them.

Each change is recorded in the activity trail.

Review a deployment

Waiting deployments are in three places:

  • The Review deployment button in the Approval needed email.
  • The project’s Deployments tab in the dashboard.
  • Deployments in the Admin console, for the organization owner and admins. A banner at the top counts the deployments waiting. View them, or the Awaiting approval switch, lists only those, longest wait first, with the reason each one needs approval, who deployed it, and how long it has waited.

A workspace’s approvers can’t open the Admin console, so the button in their email opens the review on the project’s Deployments tab.

Review opens the deployment with what you need to decide:

  • Who deployed it and when, and the note they left for you, if any.
  • What Helix checked: whether this is the app’s first deployment, and which authentications it adds or removes compared with the live deployment.
  • The project and its workspace, the AI-written description of the app, and who can use the app.
  • Download (.zip) for the deployment’s source. The review doesn’t show a code diff, so download the source to read the code.

Then choose one:

  • Approve and go live. The build goes live straight away and replaces the live version. A message is optional, and goes to the deployer in their Approved email.
  • Deny. Write a message to the deployer first. You can’t deny without one. The deployment never goes live, and the deployer’s email includes your message.

A message can be up to 1,000 characters.

Both take effect immediately, with no confirmation step. A denied deployment can’t be approved later: the deployer has to deploy again, and the new deployment goes through the policy like any other.

If someone else has already decided, the review shows who decided and when.

What deployers see

Leave a note for the reviewer

Deploy with -m to tell the reviewer what changed and why (CLI 1.17.0 and later):

helix deploy -m "Adds the Salesforce lookup to the quote form"

The note can be 1 to 500 characters. If it’s blank or longer, the command stops before uploading anything. Reviewers see it in the Approval needed email and in the review, and it also shows on the deployment in the project’s Deployments tab and in helix deployment get. Don’t put secrets in it. Projects created with CLI 1.17.0 or later also tell coding agents to leave a note on every deploy.

In the dashboard

The project’s Deployments tab shows each deployment’s approval state:

StatusWhat it means
Awaiting approvalBuilt and waiting for a decision. The row also says what is still serving: an earlier deployment, or nothing yet for a new app
Success, with Approved by and a nameApproved, and it went live
Denied, with Denied by and a nameDenied, so it never went live
WithdrawnA newer deployment replaced it while it waited, so it never went live

A waiting deployment’s details, and its Preview, say who it’s waiting for, such as “Waiting for Ana Silva or Ben Ito to approve it”. Past three names, it shows two and counts the rest. With no workspace approvers to name, it’s waiting for an organization owner or admin.

Anyone who can’t decide a waiting deployment gets Preview instead of Review: the same details, read-only, ending with who it’s waiting for. A workspace’s approvers get Preview on their own deployments.

By email

EmailWho gets itWhen
Approval neededThe workspace’s approvers, except the deployer. If the workspace has no other approvers, the organization owner and every admin, including the deployer if they’re oneThe build succeeds and the deployment starts waiting
ApprovedThe deployer, with the approver’s message if there is oneSomeone approves the deployment
RejectedThe deployer, with the approver’s messageSomeone denies the deployment
ReplacedThe deployer, unless they made the newer deployment themselvesSomeone else’s newer deployment or restore withdraws the waiting one

The emails’ buttons open the project’s Deployments tab, except in the Approval needed email to the owner and admins, which opens the review in the Admin console. The emails say “rejected” where the dashboard says Denied. Both mean the same thing.

A deployment made with an API user token, as CI deploys are, sends no Approved, Rejected, or Replaced email, because an API user has no email address. The Approval needed email still goes out. Check the Deployments tab for the decision.

In the CLI and in CI

CLI 1.18.0 and later show where a deployment stands with approvals:

  • helix deploy says when the deployment needs approval and why, with a link to its review.
  • helix deploy --wait and helix deployment wait stop once the build is waiting for approval, say the deployment isn’t live yet, and exit 0. If the deployment was denied, helix deployment wait exits 1 and shows who denied it and their message.
  • helix deployment get shows the approval: awaiting, approved or denied with who decided, when, and their message, or withdrawn by a newer deployment. Its exit code follows the build, not the approval.
  • helix deploy warns you before it replaces a deployment that’s waiting for approval. See One waiting deployment per project.

Earlier CLI versions report a waiting deployment as ready and exit 0, as if it were live. Update the CLI and SDK together.

A coding agent that deploys for you reads the same status. Projects created with CLI 1.18.0 or later tell coding agents that a deployment can wait for approval, so they don’t report it as live or deploy again to get past it. If an agent says a deploy succeeded and you don’t see the change, look for Awaiting approval on the Deployments tab.

In CI, the workflows helix ci init generates run helix deploy --wait, so the deploy job passes once the build succeeds, whether or not the deployment needs approval. With approvals on, a passing job means the build succeeded. The deployment goes live when it’s approved. Each workflow installs the CLI version that helix ci init wrote into it, and upgrading the SDK doesn’t change that version, so the job log shows approvals only after you bump both to 1.18.0 or later.

One waiting deployment per project

A project has at most one deployment waiting for approval, so reviewers only ever see its newest build:

  • When a newer deployment builds successfully and needs approval too, it replaces the waiting one. The older one becomes Withdrawn, and a new Approval needed email names the deployment it replaces.
  • When a newer deployment that doesn’t need approval goes live, it withdraws the older one that was waiting.
  • A newer deployment that fails to build leaves the waiting one as it is.

Before uploading, helix deploy checks for a waiting deployment (CLI 1.18.0 and later). In a terminal, it says who deployed the waiting one and when, and asks Deploy anyway?, which defaults to no. Without a terminal, such as in CI, it deploys and prints the same notice.

When someone else’s deployment or restore withdraws yours, you get a Replaced email saying who deployed the newer version. If your changes aren’t in it, talk to them before you deploy again.

A withdrawn deployment can’t be approved. Deploying the same change again doesn’t get it past review: the new deployment matches the policy the same way, and waits in its turn.

Restores skip approval

Restoring an earlier deployment from the Deployments tab puts it live without approval, whatever the policy says. Only a deployment that was approved, or never needed approval, can be restored: Restore this version is unavailable on deployments that are waiting, denied, or withdrawn. A restore that goes live also withdraws an older deployment waiting for approval.

So anyone who can deploy a project can put an earlier approved version back live without a new review, and nobody can use a restore to put an unapproved build live.

Turn approvals off

Choose Turn off on the Deployments policy page. The confirmation says how many deployments are waiting. Choose Turn off approvals to go ahead. From then on, new deployments go live without approval.

Deployments already waiting are approved on your behalf. Each one goes live as if you had approved it, and the activity trail records you as its approver. A deployment that can’t go live, for example because it uses an authentication you can’t access, stays waiting until someone approves or denies it. Its workspace’s approvers can still decide it. A deployment that was still building when you turned approvals off isn’t released either: it starts waiting once its build succeeds, and someone has to approve or deny it.

Your choice of which deployments need approval is kept, and is ticked again when you next turn approvals on. Each workspace’s approvers are kept too.

What gets recorded

Approvals add four actions to the organization’s activity trail, which org admins read in the Admin console under Recent activity:

ActionRecorded when
Changed the deployment approval policySomeone turns approvals on or off, or changes which deployments need approval
Changed the deployment approversSomeone changes a workspace’s approvers. The entry names the workspace
Approved a deploymentSomeone approves a deployment, including each one approved by turning approvals off
Denied a deploymentSomeone denies a deployment

The approver’s message goes to the deployer by email and isn’t part of the activity entry. A deployment starting to wait, or being withdrawn, isn’t recorded as an action of its own.

When a review doesn’t go through

What happensWhat to do
Approving fails because the deployment uses an authentication that was deleted, or that you can’t accessDeny it with a message, and ask the deployer to deploy again
The deployment couldn’t finish going liveIt is still waiting. Choose Try again
The review says Helix is still building the deploymentWait for the build to succeed, then review it
The review says there’s nothing left to decideSomeone else decided first, or a newer deployment replaced it
You’re one of the workspace’s approvers, and your own deployment opens in PreviewApprovers can’t decide their own deployments. Ask another approver, the organization owner, or an admin
Approving or denying says only the workspace’s approvers and the organization owner and admins can do itYou’re no longer one of the workspace’s approvers, or your access to the workspace is below Contributor. Ask the owner or an admin

Loading search…

Jump to a section

tab to move · esc to close