Guía / kits

Guía de kits: compón artifacts en un release

Usa un kit para publicar una composición versionada y nombrada que el equipo pueda instalar como una unidad, mientras cada artifact conserva su propio ciclo de vida.

Qué es un kit

Un kit es una composición del manifest. Contiene members, no otro snapshot de files: cada miembro es un deployment local de artifact en el mismo hubbound.json o una referencia remota exacta tag/version.

Esto separa bien las responsabilidades: los artifacts poseen comportamiento y contenido; los kits poseen el bundle del equipo y su versión.

  • Despliega primero los artifacts cuando el kit referencia deployments locales.
  • Usa versiones exactas para miembros remotos; el kit debe ser reproducible.
  • Un kit puede ser public, org o private según visibility.

1. Define el kit

Un deployment de kit necesita kind, path, tag, version, visibility y members. Prohíbe artifact_type, content y files porque el release del kit no sube su propio bundle de artifact.

{
  "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. Entiende las formas de members

Cada miembro debe contener exactamente una de las dos formas. Las referencias locales se resuelven por nombre de deployment y deben apuntar a un artifact, no a otro kit. Las remotas se validan como tag más versión SemVer exacta.

{ deployment: "auditor" } Deployment local de artifact. Al desplegar el kit se incluye automáticamente en el orden de preparación.
{ tag: "vendor/rule", version: "1.4.0" } Release remoto de artifact. La versión forma parte de la composición y nunca flota a latest.
tag duplicado Se rechaza. Un kit no puede tener dos miembros con el mismo tag efectivo.
cycle Se rechaza. Un miembro local no puede crear un ciclo de dependencias entre deployments.

3. Valida y despliega

Ejecuta dry-run sobre el kit. HubBound valida cada artifact local, expande el grafo, ordena artifacts antes que kits y revisa el plan completo. Después ejecuta el kit sin dry-run; los artifacts locales se preparan primero y la composición se envía por la ruta de kits.

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

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

Guía de deploy

4. Instala el kit

Los consumidores pueden instalar el kit con versión exacta. HubBound resuelve el kit, obtiene sus artifacts miembros, descarga cada bundle necesario y aplica cada tipo mediante los applicators del provider. Por eso un install de kit produce los mismos archivos de provider que instalar los miembros por separado, conservando además la procedencia del kit en el estado local.

$ hubbound install kit vendor/security-kit@2.0.0

$ hubbound list --json

$ hubbound manage

5. Versiona la composición

Sube la versión del kit cuando cambie la membresía, las versiones de miembros o el contrato esperado por el equipo. Sube la versión de un artifact cuando cambie su propio contenido o comportamiento. Separar estos límites vuelve claros los upgrades y rollbacks.

  • No uses latest en un manifest v2 ni en un miembro remoto de kit.
  • Publica el nuevo artifact antes de publicar un kit que lo referencia.
  • Guarda el JSON de dry-run y el JSON final en CI cuando el kit sea un release gobernado.
  • Verifica visibility pública por separado del estado de commit autenticado.

Errores de kits

Si un kit falla validación, revisa primero la forma de members antes de investigar el backend. Las causas comunes son un nombre local inexistente, un nombre local que apunta a otro kit, tags efectivos duplicados, SemVer remoto inválido o fields de kit que incluyen files/content por error.

Archivo HubBound Comando install