Guide / kits

Kit guide: compose artifacts into one release

Use a kit to publish a named, versioned composition that teams can install as one unit while each artifact keeps its own lifecycle.

What a kit is

A kit is a manifest-level composition. It contains members, not another files snapshot: each member is either a local artifact deployment in the same hubbound.json or an exact remote tag/version reference.

This gives you a useful split: artifacts own behavior and content; kits own the team-level bundle and its version.

  • Deploy artifacts first when the kit references local deployments.
  • Use exact versions for remote members; a kit should be reproducible.
  • A kit can be public, org or private according to visibility.

1. Define the kit

A kit deployment needs kind, path, tag, version, visibility and members. It forbids artifact_type, content and files because the kit release does not upload its own artifact bundle.

{
  "security-kit": {
    "kind": "kit",
    "path": "packages/security-kit",
    "tag": "vendor/security-kit",
    "version": "2.0.0",
    "visibility": "public",
    "members": [
      { "deployment": "auditor" },
      { "deployment": "secure-hook" },
      { "tag": "vendor/shared-rule", "version": "1.4.0" }
    ]
  }
}

2. Understand member forms

Each member must contain exactly one of the two forms below. Local references are resolved by deployment name and must point to an artifact, not another kit. Remote references are validated as a tag plus exact SemVer version.

{ deployment: "auditor" } Local artifact deployment. Deploying the kit automatically includes it in the preparation order.
{ tag: "vendor/rule", version: "1.4.0" } Remote artifact release. The version is part of the kit composition and never floats to latest.
duplicate tag Rejected. A kit cannot contain two members with the same effective tag.
cycle Rejected. A local kit member cannot create a deployment dependency cycle.

3. Validate and deploy

Run dry-run on the kit. HubBound validates every local artifact, expands the dependency graph, sorts artifacts before kits and checks the full release plan. Then deploy the kit without dry-run; local artifacts are prepared first and the kit composition is sent through the kit release route.

$ hubbound deploy security-kit --path . --dry-run --json

$ hubbound deploy security-kit --path . --json

Deploy guide

4. Install the kit

Consumers can install the kit by exact version. HubBound resolves the kit, obtains its member artifacts, downloads each artifact bundle as needed and applies each type through the provider applicators. A kit install therefore produces the same provider files as installing the members individually, with kit provenance retained in local state.

$ hubbound install kit vendor/security-kit@2.0.0

$ hubbound list --json

$ hubbound manage

5. Version the composition

Bump the kit version when membership, member versions or the intended team contract changes. Bump an artifact version when its own content or behavior changes. Keeping these version boundaries separate makes upgrades and incident rollback understandable.

  • Do not use latest in a v2 project manifest or remote kit member.
  • Publish the new artifact before publishing a kit that references it.
  • Record the dry-run JSON and final release JSON in CI when the kit is a governed release.
  • Verify public visibility separately from authenticated commit state.

Kit errors

If a kit fails validation, inspect the member form before investigating the backend. The most common causes are a local name that does not exist, a local name that points to another kit, duplicate effective tags, invalid remote SemVer or kit fields that incorrectly include files/content.

HubBound file Install command