Package Approval Workflow

Workloom enforces a review process for package versions before they can be consumed by workspaces. This ensures that configuration changes go through appropriate oversight.

Version Lifecycle

Every package version moves through a defined approval pipeline:

draft → pending_review → approved
                       → rejected

Status	Meaning
draft	Work in progress, not yet submitted
pending_review	Submitted and awaiting reviewer action
approved	Reviewed and accepted for use
rejected	Reviewed and declined (with optional reason)

Who Can Do What

Action	Required Role
Create draft versions	developer+
Submit for review	developer+ (version author)
Approve versions	maintainer, admin, owner
Reject versions	maintainer, admin, owner

Submitting for Review

When a draft version is ready, submit it for review:

CLI:

wl publish --scope @acme --name coding-standards --version 1.2.0

API:

curl -X POST \
  https://registry.example.com/api/v1/packages/@acme/coding-standards/versions/1.2.0/submit \
  -H "Authorization: Bearer wl_your_token"

Web UI: Navigate to the package detail page → Version History → click Submit next to the draft version.

The version status changes to pending_review and an audit entry is created.

Reviewing Versions

Reviewers (maintainer+) can approve or reject pending versions.

Approving

API:

curl -X POST \
  https://registry.example.com/api/v1/packages/@acme/coding-standards/versions/1.2.0/approve \
  -H "Authorization: Bearer wl_your_token"

Web UI: Package detail → Version History → click Approve next to the pending version.

The response includes approvedBy (reviewer ID) and approvedAt (timestamp).

Rejecting

API:

curl -X POST \
  https://registry.example.com/api/v1/packages/@acme/coding-standards/versions/1.2.0/reject \
  -H "Authorization: Bearer wl_your_token" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Missing security review section" }'

Web UI: Package detail → Version History → click Reject next to the pending version. Optionally provide a reason.

The rejection reason is stored and visible in the version history.

Security Scanning

Versions are automatically scanned for security issues. Scan results are available on the package detail page and via the API:

curl https://registry.example.com/api/v1/packages/@acme/coding-standards/versions/1.2.0/scan \
  -H "Authorization: Bearer wl_your_token"

Reviewers should check scan results before approving. A version with findings can still be approved if the findings are acceptable, but the scan results provide visibility into potential risks.

Package Status vs. Version Status

These are independent concepts:

• Package status (draft, active, deprecated, yanked) — controls whether the package is visible and usable in the registry
• Version status (draft, pending_review, approved, rejected) — controls whether a specific version can be consumed

A package must be active for its approved versions to be pulled by workspaces.

Audit Trail

All approval actions are logged:

Action	Audit Entry
Submit	package_version.submitted
Approve	package_version.approved
Reject	package_version.rejected

View these in the Audit Logs section of the web UI, filtered by resourceType: package_version.

Best Practices

1. Review scan results before approving — check for injection patterns, unsafe hooks, and policy violations
2. Use rejection reasons — help authors understand what to fix
3. Separate authoring from review — the submitter should not approve their own version
4. Automate submission — use CI to auto-submit after tests pass
5. Monitor pending versions — set up alerts for versions waiting more than 24 hours