Release Approval

Overview

Release Approval is a capability of Praxis that writes, validates, and installs the pre-release hook behind Facets release approval.

You describe the rule in plain language, for example "require approval for prod" or "gate anything touching the database". Praxis produces the script, proves it works against synthetic payloads, shows it to you, and installs it only after you say yes.

This page covers generating the hook. For what the hook does, the exit-code contract and the release-context schema, see the Pre-Release Hook Script Reference. For the approval workflow itself, see Configuring Release Approval.

Key Benefits

• No hand-written safety-critical script. The exit-code contract is the part that is easy to get catastrophically wrong, and Praxis never rewrites it.
• Stays editable in the visual builder. A builder-mode hook round-trips into the Facets Release Approval settings, so you are not locked into chat.
• Nothing installs unreviewed. Every hook is dry-run and shown to you before it reaches your blueprint.

How to Access and Use

Ask Praxis directly. The capability triggers on phrasings like:

• "Require approval for prod"
• "Gate releases that touch the database"
• "Add a release approval rule"

It also triggers on the terms pre-release hook, release approval, approval gate, pending approval, and approval workflow.

You can also start from the Facets control plane. The project's Release Approval settings can hand off to Praxis with the project already selected and a first message written, so the conversation opens with your context loaded.

After a hook exists, you can ask Praxis to inspect it, change the rule, switch language, or remove it.

What Changes When Praxis Writes It

The gating criteria, the two authoring modes and the two languages are all Facets platform concepts. Three things behave differently in a Praxis conversation.

You are never asked to think in boolean logic. When your rule spans more than one criterion, Praxis asks in everyday words whether a release should be gated if it matches any of them or all of them, and stores your answer as the operator. With a single criterion the question is skipped.

Criteria are checked against the real project first. Environments and resources are read back from your project before anything is generated, so a typo or a resource that does not exist gets caught in conversation instead of at release time.

Praxis tells you when a rule will cost you the visual builder. A rule the builder schema cannot express, such as one keyed on change type or a count threshold, is written as a custom hook. Praxis says so up front, because a custom hook becomes read-only in the Facets Release Approval settings.

Validation Before Install

Validation is mandatory. Nothing is installed that has not just been dry-run.

Praxis builds two synthetic release payloads in a temporary directory, never in your repo. One satisfies the configured rule, one matches nothing. It runs the generated script against each and checks the exit code: the gating case must return 2 and the non-gating case must return 0.

The payloads are tailored to the actual rule. A gated resource means the payload includes a matching resource entry. An "all of these" rule means the gating case satisfies every category, with one dropped to build the non-gating case.

A wrong exit code is a hard stop. Praxis treats the script as broken, regenerates it, and re-validates until both codes match. You see the dry-run result before you approve the install.

Installing the Hook

Installation runs through raptor, the local Facets CLI.

1. Preflight. Praxis checks that raptor is present and your session is authenticated. If raptor is missing it asks you to install it. If the session is not authenticated it asks you to run raptor login. It never asks you to paste a token.
2. Review. Praxis shows you the full script, the criteria in plain English, and the dry-run result.
3. Confirm. Install runs only after you explicitly say yes.
4. Apply. Praxis runs the install command, then reads the hook back to verify it landed.

raptor apply hook --type pre-release -p PROJECT --language python --script-file /tmp/pre_release_hook.py
raptor get hook --type pre-release -p PROJECT
raptor delete hook --type pre-release -p PROJECT --yes

For a Shell hook, pass --language shell and the .sh file instead.

What Praxis Will and Will Not Do

• Will not write a hook from scratch. The base templates are the source of truth, and the harness that enforces the exit-code contract is never rewritten by hand.
• Will not skip the review, ever. A language swap, a re-apply and a one-line edit all generate a fresh script, so all three go through confirmation again. "The change seems minor" is explicitly not a reason to skip it. The only exception is when you tell Praxis up front to apply without review.
• Will not emit any exit code other than 0 or 2 from the decision path.
• Will not install raptor for you, and will not ask you to paste a token.
• Will not invent config fields in builder mode. A criterion the schema cannot express goes to custom mode with the editability warning, or needs a coordinated change across the templates, the control plane UI, and the backend. Praxis flags that as a code change rather than faking it.
• Validates in a temporary directory, never in your repository.

Permissions

There is nothing feature-specific on the Praxis side. Installing, reading, and deleting the hook all go through raptor, so the project-level permissions the control plane enforces on those operations apply. You need a working raptor login session.

Who can approve or reject a gated release is separate, and covered in Release Approval permissions.

Example Interactions

Scenario: Gate production You ask for approval on prod releases. Praxis confirms prod is a real environment on the project, generates the hook, dry-runs it, shows you the script, and installs it after you confirm.

Scenario: Gate a specific service You ask for approval when a named service changes, combined with an environment. Because two criteria are in play, Praxis asks whether a release should be gated if it matches any of them or all of them.

Scenario: Custom rule You ask for approval on any resource deletion. The builder schema cannot express change types, so Praxis switches to custom mode and tells you up front that the hook will no longer be editable in the visual builder.

Troubleshooting

FAQ

Is this a separate agent from Praxis? No. Release Approval hook generation is a built-in capability of Praxis.

Can I still edit the rule in the Facets UI afterwards? Yes for builder-mode hooks. No for custom-mode hooks, which the builder treats as read-only.

Does installing change my repository? Yes. The script is committed to the project's blueprint repository, and the commit appears in the repository history.

Do I need to write any code? No. You describe the rule in plain language and review what Praxis generates.

Related

• Release Approval - How gating works, and the permission model
• Configuring Release Approval - The settings page, the Builder, and custom scripts
• Pre-Release Hook Script Reference - Exit codes, the release context JSON, and sample scripts