operator runbooks

Intended Documentation

Deploy and Rollback Policies

Approve, deploy, and rollback Intended authorization policies, including deployment pipelines, approval gates, rollback procedures, and version pinning.

intermediate6 min readimplemented

Deploy and Rollback Policies#

This runbook covers the full deployment lifecycle for Intended authorization policies: approval gates, deployment execution, rollback procedures, and version pinning.

Prerequisites#

The Intended CLI installed and authenticated with deployer role
A validated and reviewed policy (see Author a Policy)
Simulation results confirming acceptable impact (see Simulate Impact)

Warning

Policy deployments modify the authorization runtime immediately. Every deployment must pass through the approval pipeline. Direct runtime modifications are logged as security events.

Deployment Pipeline Overview#

The Intended deployment pipeline enforces a strict sequence of gates:

Validation — schema and semantic checks pass
Simulation — blast radius is within threshold
Approval — required reviewers have signed off
Deployment — policy is pushed to the runtime
Verification — post-deploy health check confirms expected behavior

Step 1: Check Deployment Readiness#

Before deploying, verify that all gates are satisfied:

$meritt deploy status <policy-id>

Check the deployment readiness of a policy.

--environment(-e)string

Target environment

bash

$ meritt deploy status pol_abc123 --environment production

DEPLOYMENT READINESS — pol_abc123
─────────────────────────────────────────────────
Policy:          restrict-production-deploys (v4)
Environment:     production
Current version: v3 (active since 2026-02-28)

GATES:
  ✓ Validation         passed (2026-03-07 14:30 UTC)
  ✓ Simulation         passed (blast radius: 2.1%)
  ✓ Approval           2/2 approvals received
  ○ Deployment         ready
  ○ Verification       pending deployment

Status: READY TO DEPLOY

Step 2: Approve a Deployment#

Reviewers approve deployments through the CLI or the console. Each approval is cryptographically signed.

$meritt deploy approve <policy-id>

Approve a policy deployment.

--environment(-e)string *

Target environment

--comment(-c)string

Approval comment for the audit trail

bash

$ meritt deploy approve pol_abc123 \
    --environment production \
    --comment "Reviewed simulation results. Blast radius acceptable."

Approval recorded for pol_abc123 (production)
Signed by: alice@example.com
Approval: 2/2 (threshold met)

Tip

Approvers cannot approve their own policy changes. The system enforces separation of duties — the author and the final approver must be different identities.

Step 3: Deploy#

Once all gates pass, execute the deployment:

Deploy the policy

$meritt deploy push <policy-id>

Deploy a policy to the target environment.

--environment(-e)string *

Target environment

--confirmboolean

Skip the interactive confirmation prompt

--rollback-on-errorboolean

Auto-rollback if verification fails (default: true)

bash

$ meritt deploy push pol_abc123 --environment production

Deploying restrict-production-deploys v4 to production...

  Pushing policy to runtime...         done
  Waiting for propagation...           done (3.2s)
  Running verification checks...       done

DEPLOYMENT SUCCESSFUL
  Policy:      restrict-production-deploys
  Version:     v4
  Environment: production
  Deployed at: 2026-03-08T10:15:32Z
  Deployed by: bob@example.com
  Decision token: dtk_m8x2p4q7

Verify post-deployment

The CLI runs automatic verification, but you should also confirm manually:

bash

$ meritt deploy verify pol_abc123 --environment production

POST-DEPLOY VERIFICATION
─────────────────────────────────────────────────
Runtime version:    v4 (matches expected)
Policy hash:        sha256:a3f8c1...  (matches source)
Decision rate:      nominal (no anomalies)
Error rate:         0.00%
Latency (p99):      12ms (baseline: 11ms)

Result: HEALTHY

Rollback Procedure#

If a deployment causes issues, roll back to the previous version immediately.

Danger

If you observe unexpected denials or authorization failures after deployment, rollback first and investigate second. Do not attempt to fix forward under pressure.

Initiate rollback

$meritt deploy rollback <policy-id>

Rollback a policy to a previous version.

--environment(-e)string *

Target environment

--to-versionstring

Target version to rollback to (default: previous version)

--reasonstring *

Reason for rollback (recorded in audit trail)

bash

$ meritt deploy rollback pol_abc123 \
    --environment production \
    --reason "Unexpected deny rate increase for svc:data-pipeline-runner"

Rolling back restrict-production-deploys...
  From: v4
  To:   v3

  Restoring v3 to runtime...           done
  Waiting for propagation...           done (2.8s)
  Running verification checks...       done

ROLLBACK SUCCESSFUL
  Restored version: v3
  Rolled back at:   2026-03-08T10:42:17Z
  Rolled back by:   bob@example.com
  Reason:           Unexpected deny rate increase for svc:data-pipeline-runner

Verify rollback

bash

$ meritt deploy verify pol_abc123 --environment production

POST-ROLLBACK VERIFICATION
─────────────────────────────────────────────────
Runtime version:    v3 (rollback confirmed)
Decision rate:      nominal
Error rate:         0.00%

Result: HEALTHY

Open an incident if necessary

If the failed deployment caused user-facing impact, open an incident for investigation:

bash

$ meritt incident create \
    --title "Policy v4 rollback — unexpected deny rate" \
    --severity medium \
    --related-deploy dtk_m8x2p4q7

See Incident Response for the full investigation workflow.

Version Pinning#

Pin a specific policy version to prevent automated deployments from overriding it. This is useful for compliance-critical policies that must go through a formal change process.

$meritt policy pin <policy-id>

Pin a policy to a specific version, preventing automated updates.

--version(-v)string *

Version to pin

--environment(-e)string *

Target environment

--reasonstring *

Reason for pinning

--expiresstring

Pin expiration (e.g., 30d, 2026-04-01)

bash

$ meritt policy pin pol_abc123 \
    --version v3 \
    --environment production \
    --reason "Compliance hold pending SOC2 audit" \
    --expires 2026-04-01

Policy pinned:
  Policy:      restrict-production-deploys
  Version:     v3 (pinned)
  Environment: production
  Expires:     2026-04-01T00:00:00Z
  Pinned by:   alice@example.com

Warning

Pinned policies still receive validation warnings if newer versions are available. Review pins regularly and remove them once the hold reason is resolved.

List and Remove Pins#

bash

# List all pinned policies
$ meritt policy pin list --environment production

POLICY                        VERSION  PINNED BY          EXPIRES
restrict-production-deploys   v3       alice@example.com  2026-04-01

# Remove a pin
$ meritt policy pin remove pol_abc123 --environment production

Deployment History#

Review the deployment history for audit and troubleshooting:

bash

$ meritt deploy history pol_abc123 --environment production --limit 5

VERSION  ACTION    DEPLOYED BY          TIMESTAMP              STATUS
v4       rollback  bob@example.com      2026-03-08T10:42:17Z   rolled back
v4       deploy    bob@example.com      2026-03-08T10:15:32Z   superseded
v3       deploy    alice@example.com    2026-02-28T09:00:12Z   active
v2       deploy    carol@example.com    2026-02-15T14:30:00Z   superseded
v1       deploy    alice@example.com    2026-01-10T11:00:00Z   superseded

Next Steps#

Simulate Impact — always simulate before the next deployment
Incident Response — investigate issues caused by deployments
Control Center — monitor runtime health after deployment