Group Bundles
Marketplace publish/fork bundles.
Group bundles are the distribution format for shareable workflow sub-graphs. An operator publishes a bundle to the marketplace; any workspace can install (fork) it, then customise the copy independently.
Bundle anatomy
A bundle is a gzip-compressed JSON envelope with this structure:
{
"version": 1,
"metadata": {
"slug": "pr-review-gate",
"name": "PR Review Gate",
"version": "1.2.0",
"description": "Summarise and human-gate a PR review",
"author": "rensei",
"category": "sdlc"
},
"definition": { ... } // SerializedGroupDefinition
}| Field | Constraints |
|---|---|
slug | Lowercase alphanumeric + hyphens; globally unique in the catalogue |
version | Semver (1.0.0, 2.0.0-beta.1, etc.) |
category | Free-form: sdlc, bfsi, integration, etc. |
The bundle bytes are stored in workflow_group_versions.bundle keyed by SHA-256 of the gzipped bytes. A denormalised metadata column stores a fingerprint summary so the catalogue can render previews without decompressing every row.
Publishing a bundle (operator)
Publishing a bundle requires operator-admin access. End-users fork bundles; they do not publish them.
Navigate to Admin → Workflow Groups and open the group you want to publish.
Edit the draft definition. The editor validates the definition in real time against hard-error checks (scope isolation, no struct ports at boundary) and advisory warnings.
Click Validate to run the full bundle validator:
POST /api/admin/workflow-groups/{id}/validateThis returns errors[] and warnings[]. Fix all errors before proceeding; warnings are advisory.
Click Publish (or call the API):
POST /api/admin/workflow-groups/{id}/publish
Content-Type: application/json
{ "version": "1.2.0", "changeNote": "Add timeout handling" }A new row is created in workflow_group_versions with a (group_id, version) unique key and the latest_version pointer is updated atomically.
Bulk publish
The admin API supports publishing multiple versions in one request:
POST /api/admin/workflow-groups/bulk-publish
Content-Type: application/json
{
"items": [
{ "groupId": "wfg_abc", "version": "2.0.0" },
{ "groupId": "wfg_def", "version": "1.5.0" }
]
}Forking a bundle (workspace)
When a workspace installs a bundle, the platform creates a fork - an independent copy of the group definition. Changes to the published bundle do not automatically propagate to forks; the workspace must explicitly sync (see Groups: Upstream diff).
Fork via API:
POST /api/workflow-groups/{slug}/fork
Content-Type: application/json
Authorization: Bearer rsk_live_...
{
"version": "latest", # or a specific semver
"targetWorkflowId": "wf_abc123",
"groupName": "My PR Review Gate"
}The fork response includes a groupNodeId that can be placed on a workflow canvas.
Fork via editor: On the workflow canvas, open the node palette, find the bundle under Marketplace, and drag it onto the canvas. The platform forks latest automatically.
Versioning and latest_version
Every published bundle version is immutable. The latest_version pointer on the workflow_groups row tracks the most recently published semver. When a workspace forks with version: "latest", the fork is pinned to the exact version number at fork time - not to the floating latest pointer - so your workflow is never silently updated.
Bundle validation rules
State machine in bundles
A bundle's definition may include an optional metadata.stateMachine field (see State Machine). The state machine travels with the bundle and is installed into the forked group's metadata. This allows bundles that model a linear SDLC lifecycle to carry their state vocabulary with them.
Admin API reference
| Endpoint | Method | Purpose |
|---|---|---|
/api/admin/workflow-groups | GET | List all groups |
/api/admin/workflow-groups | POST | Create a new group |
/api/admin/workflow-groups/{id} | GET | Get group + version history |
/api/admin/workflow-groups/{id}/validate | POST | Validate current draft |
/api/admin/workflow-groups/{id}/publish | POST | Publish a new version |
/api/admin/workflow-groups/{id}/draft | POST | Save a draft |
/api/admin/workflow-groups/bulk-publish | POST | Publish multiple groups at once |
/api/workflow-groups/{slug}/fork | POST | Fork a bundle into a workspace |
Related pages
- Groups - group container model and upstream diff
- State Machine - embedding state machines in bundles
- Required Policies - enforcing bundle installs across projects