Approval Workflows

Approval workflows require releases to be reviewed and approved before distribution. Workflows can be configured per tenant or product, require single or multiple approvers, and support expiration and auto-approval rules. All approval decisions are recorded in audit logs.

Prerequisites

• API credentials with workflow management permissions
• Understanding of your organization’s release approval requirements
• List of approvers and their roles

Understanding Approval Workflows

Approval workflows are optional and configurable. When enabled:

• Releases require approval before being distributed to clients
• Approvers review release metadata, artifacts, and verification status
• Approved releases become available to clients
• Rejected releases remain in the catalog but are not distributed
• All approval actions are recorded in audit logs

Workflows can be configured at:

• Global level — Applies to all releases
• Tenant level — Applies to all releases for a tenant
• Product level — Applies to all releases for a product
• Channel level — Applies to releases on a specific channel

Step 1: Check Current Workflow Configuration

Query existing workflow configuration:

curl "${BP_BASE_URL}/v1/workflows/approval" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "workflow_id": "wf_abc123",
  "scope": "tenant",
  "scope_id": "tenant_abc123",
  "enabled": true,
  "required_approvals": 1,
  "approvers": [
    "admin@example.com"
  ],
  "auto_approve_channels": ["internal"],
  "approval_expiration_hours": null
}

Step 2: Create Approval Workflow

Create a workflow for a tenant:

curl -X POST "${BP_BASE_URL}/v1/tenants/tenant_abc123/workflows/approval" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "required_approvals": 1,
    "approvers": [
      "admin@example.com",
      "security@example.com"
    ],
    "auto_approve_channels": ["internal"],
    "approval_expiration_hours": null
  }'

Response:

{
  "workflow_id": "wf_abc123",
  "scope": "tenant",
  "scope_id": "tenant_abc123",
  "enabled": true,
  "required_approvals": 1,
  "approvers": [
    "admin@example.com",
    "security@example.com"
  ],
  "auto_approve_channels": ["internal"],
  "approval_expiration_hours": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Configure Multiple Approvers

Require multiple approvals for critical releases:

curl -X PUT "${BP_BASE_URL}/v1/workflows/wf_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "required_approvals": 2,
    "approvers": [
      "admin@example.com",
      "security@example.com",
      "product-manager@example.com"
    ]
  }'

When multiple approvals are required, each approver must independently approve the release. The release is distributed only after the required number of approvals is reached.

Step 4: Configure Approval Expiration

Set approvals to expire after a period:

curl -X PUT "${BP_BASE_URL}/v1/workflows/wf_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_expiration_hours": 168
  }'

Approvals expire after 168 hours (7 days). Expired approvals require re-approval before distribution.

Step 5: Configure Auto-Approval

Auto-approve releases on specific channels:

curl -X PUT "${BP_BASE_URL}/v1/workflows/wf_abc123" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_approve_channels": ["internal", "beta"]
  }'

Releases on internal or beta channels are automatically approved and distributed without manual review.

Step 6: Approve a Release

When a release requires approval, approvers review and approve:

curl -X POST "${BP_BASE_URL}/v1/releases/rel_abc123/approve" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "approved_by": "admin@example.com",
    "approval_notes": "Reviewed release notes and verified artifacts. Approved for production."
  }'

Response:

{
  "release_id": "rel_abc123",
  "status": "approved",
  "approved_at": "2024-01-15T10:30:00Z",
  "approved_by": "admin@example.com",
  "approval_count": 1,
  "required_approvals": 1
}

Step 7: Reject a Release

If a release does not meet requirements, reject it:

curl -X POST "${BP_BASE_URL}/v1/releases/rel_abc123/reject" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rejected_by": "security@example.com",
    "rejection_reason": "Security scan detected vulnerabilities. Requires remediation before approval."
  }'

Response:

{
  "release_id": "rel_abc123",
  "status": "rejected",
  "rejected_at": "2024-01-15T10:30:00Z",
  "rejected_by": "security@example.com",
  "rejection_reason": "Security scan detected vulnerabilities. Requires remediation before approval."
}

Rejected releases remain in the catalog but are not distributed to clients. They can be updated and resubmitted for approval.

Checking Approval Status

Query a release’s approval status:

curl "${BP_BASE_URL}/v1/releases/rel_abc123/approval-status" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "release_id": "rel_abc123",
  "status": "pending_approval",
  "required_approvals": 2,
  "current_approvals": 1,
  "approval_history": [
    {
      "action": "approved",
      "actor": "admin@example.com",
      "timestamp": "2024-01-15T10:30:00Z",
      "notes": "Reviewed release notes and verified artifacts."
    }
  ],
  "pending_approvers": [
    "security@example.com"
  ]
}

Viewing Approval History

View complete approval history for a release:

curl "${BP_BASE_URL}/v1/releases/rel_abc123/approval-history" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Response:

{
  "release_id": "rel_abc123",
  "history": [
    {
      "action": "submitted",
      "actor": "release-bot",
      "timestamp": "2024-01-15T09:00:00Z"
    },
    {
      "action": "approved",
      "actor": "admin@example.com",
      "timestamp": "2024-01-15T10:30:00Z",
      "notes": "Reviewed release notes and verified artifacts."
    },
    {
      "action": "approved",
      "actor": "security@example.com",
      "timestamp": "2024-01-15T11:00:00Z",
      "notes": "Security scan passed."
    },
    {
      "action": "distributed",
      "actor": "system",
      "timestamp": "2024-01-15T11:00:00Z"
    }
  ]
}

Workflow Precedence

Workflows are evaluated in precedence order:

1. Channel-level — Highest precedence
2. Product-level — Applies to all channels for a product
3. Tenant-level — Applies to all products for a tenant
4. Global-level — Default for all releases

When multiple workflows apply, the highest precedence workflow is used.

Common Workflow Patterns

Single Approver

Simple workflow requiring one approval:

{
  "enabled": true,
  "required_approvals": 1,
  "approvers": ["admin@example.com"]
}

Security Review Required

Require security team approval for production releases:

{
  "enabled": true,
  "required_approvals": 2,
  "approvers": [
    "admin@example.com",
    "security@example.com"
  ],
  "auto_approve_channels": ["internal", "beta"]
}

Time-Limited Approvals

Approvals expire after 7 days:

{
  "enabled": true,
  "required_approvals": 1,
  "approvers": ["admin@example.com"],
  "approval_expiration_hours": 168
}

Best Practices

Review before approval: Always review release metadata, artifacts, and verification status before approving.

Document decisions: Include approval notes explaining why a release was approved or rejected.

Separate approvers: Use different approvers for different aspects (security, product, operations).

Monitor pending approvals: Track releases awaiting approval to avoid delays.

Audit trail: Approval history provides an audit trail for compliance and troubleshooting.

Related Documentation

• Approving a Release — Step-by-step approval process
• Audit Readiness — Review approval audit logs
• Compliance Reporting — Generate approval reports