Policy Governance

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

This walkthrough shows how policy bundles are created, inspected, and attached to governed releases in the current Orqestra implementation.

1. Inspect existing policy bundles


curl -s http://localhost:8000/v1/policies \
  -H "X-Actor-Ref: developer@acme.com" | jq .

The convenience endpoint returns all assets where asset_kind = policy_bundle.

To inspect the latest version content for one bundle:


curl -s http://localhost:8000/v1/policies/{bundle_id} \
  -H "X-Actor-Ref: developer@acme.com" | jq .

2. Create a restrictive policy bundle

Create the asset


curl -s -X POST http://localhost:8000/v1/assets \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "slug": "strict-safety-policy",
    "asset_kind": "policy_bundle",
    "owner_ref": "team:governance"
  }' | jq .

Create a version


curl -s -X POST http://localhost:8000/v1/assets/{asset_id}/versions \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "version_label": "v1",
    "content": {
      "rules": [
        {
          "id": "KNOWLEDGE-BASE-BLOCKED",
          "condition": "match",
          "match_fields": {"resource_kind": "knowledge_base"},
          "outcome": "deny",
          "reason_code": "KNOWLEDGE_BASE_BLOCKED"
        },
        {
          "id": "RESTRICTED-LANE",
          "condition": "expression",
          "expression": "service_lane == '\''restricted'\''",
          "outcome": "require_approval",
          "reason_code": "RESTRICTED_LANE"
        },
        {
          "id": "FINANCE-KNOWLEDGE-ACCESS",
          "condition": "expression",
          "expression": "resource_kind matches '\''kb-finance-*'\''",
          "outcome": "allow_with_obligations",
          "obligations": [
            {"type": "capture_evidence"},
            {"type": "require_human_review"}
          ],
          "reason_code": "FINANCE_KNOWLEDGE_ACCESS"
        },
        {
          "id": "DEFAULT-ALLOW",
          "condition": "always",
          "outcome": "allow",
          "reason_code": "DEFAULT_ALLOW"
        }
      ]
    }
  }' | jq .

3. Attach the policy to a release

In the current implementation, a release should carry both:

policy_bundle_id on the release record
a release binding with role policy_bundle

Create the release


curl -s -X POST http://localhost:8000/v1/releases \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "workload_id": "<workload_id>",
    "environment": "production",
    "target_lane": "all",
    "policy_bundle_id": "<policy_asset_id>"
  }' | jq .

Bind the policy bundle version


curl -s -X POST http://localhost:8000/v1/releases/{release_id}/bindings \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{
    "asset_version_id": "<policy_version_id>",
    "role": "policy_bundle"
  }' | jq .

If you skip the policy_bundle binding, release activation can fail even if policy_bundle_id is set on the release.

4. Promote the release through governance


curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: developer@acme.com" \
  -d '{"to_state": "review_ready"}' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/approvals \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: reviewer@acme.com" \
  -d '{
    "outcome": "approved",
    "subject_kind": "release",
    "subject_ref": "<release_id>"
  }' | jq .
 
curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: reviewer@acme.com" \
  -d '{"to_state": "approved"}' | jq .

If the release has the required bindings, it can then be activated:


curl -s -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -H "X-Actor-Ref: deployer@acme.com" \
  -d '{"to_state": "active"}' | jq .

5. What happens at runtime

At runtime, a policy bundle can produce:

Outcome	Effect
`allow`	Execution continues
`deny`	Execution is blocked
`require_approval`	Execution pauses pending approval
`allow_with_obligations`	Execution continues with recorded obligations

Policy decisions and obligations are then visible in execution evidence and operator/auditor surfaces.