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
- 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.
- The build runs as usual. If it fails, nothing waits and nobody is asked to review it.
- 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.
- 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.
- 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 admins | A workspace’s approvers | Everyone else | |
|---|---|---|---|
| Turn approvals on or off, choose which deployments need approval, and choose each workspace’s approvers | Yes | No | No |
| Approve or deny a deployment | Yes, in every workspace, including their own | Yes, in their workspace, except their own | No. They can open a read-only Preview |
| Their own deployments wait for approval | Yes | Yes | Yes |
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
- Open the user menu and choose Organization settings.
- Under Policies, choose Deployments.
- Under Which deployments need approval, tick the deployments to hold.
- 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
| Option | A deployment waits when |
|---|---|
| Every deployment | Always. Ticking it also ticks and locks the other two |
| New apps | The 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 authentications | It 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.
- In Organization settings, under Policies, choose Deployments. Who approves appears once approvals are on.
- In the list of workspaces, choose Add approvers next to the workspace, or Edit if it already has some.
- 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:
| Status | What it means |
|---|---|
| Awaiting approval | Built 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 name | Approved, and it went live |
| Denied, with Denied by and a name | Denied, so it never went live |
| Withdrawn | A 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
| Who gets it | When | |
|---|---|---|
| Approval needed | The 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 one | The build succeeds and the deployment starts waiting |
| Approved | The deployer, with the approver’s message if there is one | Someone approves the deployment |
| Rejected | The deployer, with the approver’s message | Someone denies the deployment |
| Replaced | The deployer, unless they made the newer deployment themselves | Someone 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 deploysays when the deployment needs approval and why, with a link to its review.helix deploy --waitandhelix deployment waitstop once the build is waiting for approval, say the deployment isn’t live yet, and exit 0. If the deployment was denied,helix deployment waitexits 1 and shows who denied it and their message.helix deployment getshows 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 deploywarns 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:
| Action | Recorded when |
|---|---|
| Changed the deployment approval policy | Someone turns approvals on or off, or changes which deployments need approval |
| Changed the deployment approvers | Someone changes a workspace’s approvers. The entry names the workspace |
| Approved a deployment | Someone approves a deployment, including each one approved by turning approvals off |
| Denied a deployment | Someone 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 happens | What to do |
|---|---|
| Approving fails because the deployment uses an authentication that was deleted, or that you can’t access | Deny it with a message, and ask the deployer to deploy again |
| The deployment couldn’t finish going live | It is still waiting. Choose Try again |
| The review says Helix is still building the deployment | Wait for the build to succeed, then review it |
| The review says there’s nothing left to decide | Someone else decided first, or a newer deployment replaced it |
| You’re one of the workspace’s approvers, and your own deployment opens in Preview | Approvers 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 it | You’re no longer one of the workspace’s approvers, or your access to the workspace is below Contributor. Ask the owner or an admin |