Proceso de lanzamiento
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Loom sigue SemVer: el servidor, ambos SDK, la aplicación web, las skills raíz (loom-code, loom), el plugin de Cursor y el paquete Agent Plugins que las distribuyen, y la extensión de Gemini CLI comparten una misma versión X.Y.Z. Los plugins de Claude Code y Codex comparten su propia versión, que se incrementa cuando cambia el comportamiento de cualquier archivo que el plugin distribuye (hooks/, lib/, bin/, skills/, .mcp.json, el plugin-defaults.json de Codex): los clientes instalados solo reciben un cambio en un hook mediante una nueva versión del plugin. MIN_SERVER_VERSION en el lib/server-version.mjs de los plugins indica el servidor más antiguo que sus hooks admiten: cuando GET /v1/health del servidor informa de una version anterior, SessionStart imprime una línea loom: que pide actualizar el servidor, y no dice nada cuando no se puede leer la versión. Sube con cada lanzamiento (publicar el lanzamiento, paso 2).
Dónde reside la versión
.venv/bin/python scripts/release/prepare.py bump X.Y.Z actualiza cada uno de estos archivos en el commit de la versión, salvo los plugins de Claude Code y Codex, y escribe las notas de la versión:
| Componente | Archivos |
|---|---|
| Servidor | server/__init__.py (__version__), pyproject.toml, uv.lock y server.json |
| SDK de Python | sdk/python/pyproject.toml y sdk/python/loom/_version.py |
| SDK de TypeScript | sdk/typescript/package.json, sdk/typescript/package-lock.json, sdk/typescript/src/version.ts |
| Aplicación web | frontend/package.json y frontend/package-lock.json |
| Skills raíz | .claude-plugin/plugin.json, .cursor-plugin/plugin.json, plugin.json y el metadata.version de skills/loom-code/SKILL.md y skills/loom/SKILL.md |
| Extensión de Gemini CLI | gemini-extension.json |
| Helm chart | deploy/helm/loom/Chart.yaml: appVersion (la etiqueta por defecto de las imágenes del servidor y del extractor, y la etiqueta app.kubernetes.io/version del chart) y el version propio del chart: una versión menor para una versión mayor o menor, un parche para una versión de parche |
| Plugins de Claude Code y Codex | integrations/claude-code-plugin/.claude-plugin/plugin.json, integrations/codex-plugin/.codex-plugin/plugin.json (su propia versión; increméntala cuando cambie el comportamiento de cualquier archivo que el plugin incluye: hooks/, lib/, bin/, skills/, .mcp.json, el plugin-defaults.json de Codex) |
El servidor lee su versión solo de server/__init__.py; la informan el documento OpenAPI, el serverInfo de MCP, loom report y GET /v1/health (comprobado por tests/unit/test_health_problems.py). Estas comprobaciones mantienen los números coherentes:
| Comprobación | Verifica |
|---|---|
tests/unit/test_release_version.py |
que cada superficie informa la versión del servidor y que server.json mantiene la forma del listado del registro |
npm run check:version (SDK de TypeScript) |
que sus cuatro fuentes de versión coinciden |
tests/unit/test_codex_plugin.py |
que ambos manifiestos de plugin tienen una misma versión y que MIN_SERVER_VERSION no es más reciente que la versión del servidor |
tests/unit/test_release_prepare.py |
que cada archivo que prepare.py actualiza nombra la versión del servidor |
prepare.py check, check-tag, check-chart |
el job version de la versión (paso 1): una sola versión en todas partes, el orden de los candidatos, el chart actualizado |
Dos pull requests de plugins que suben al mismo número se fusionan sin conflicto, y la segunda no entrega nada a los clientes que ya se actualizaron con la primera. Comprueba la versión del plugin en main antes de incrementarla.
Notas de la versión
La ejecución que crea el GitHub Release genera sus notas a partir de los commits desde la etiqueta de la versión final anterior (prepare.py previous), de modo que una versión final sobre el commit de su candidata también los lista;
una nueva ejecución o el despacho posterior al registro las mantiene tal como están. Lo que los commits no pueden decir va en una
sección “Release notes” de la descripción del pull request de la versión, de modo que se revisa antes de la etiqueta:
las entradas del changelog de los pull requests, agrupadas por su categoría del changelog (los pull requests de una
categoría que no necesita entrada se omiten), luego los pasos para operadores (nuevos ajustes, backfills, reconstrucciones de tablas)
y los cambios de protocolo visibles para el cliente, incluidos todos los campos de solicitud eliminados y las opciones retiradas.
No existe un registro de campos eliminados, así que las notas de la versión son donde un cliente se entera de uno.
prepare.py escribe la sección en release-notes.md (sin commit), a partir de los squash merges
desde la etiqueta final más alta por debajo de la versión:
- la entrada del changelog de cada pull request bajo su categoría, en el orden de la plantilla, o su título cuando la entrada está vacía; aquel cuya descripción no nombra una única categoría se lista bajo “Unclassified” para que el autor lo ubique;
- cada elemento de “Operator steps”, tal como está escrito, bajo el número de su pull request, de todos los pull requests,
incluido uno de una categoría que no necesita entrada; un elemento que dice que no hay ninguno (
none,N/A,No operator steps.) o que es el texto propio de la plantilla se omite, y el autor elimina el resto que no nombre ningún paso; - la diferencia del protocolo (generación de código).
Una corrección que un parche de una línea anterior ya publicó se lista de nuevo, y también un pull request revertido en el mismo rango, junto a su reversión; el autor los elimina.
Obtiene por sí mismo las etiquetas del repositorio upstream, lee los pull requests con gh y la diferencia del protocolo a través del registro del servidor, por lo que necesita un gh con sesión iniciada y el entorno del proyecto
(uv sync). .venv/bin/python scripts/release/prepare.py notes X.Y.Z imprime de nuevo la sección
sin cambiar ninguna versión: ejecútalo tras hacer rebase del pull request de la versión justo antes de que se fusione,
y de nuevo en el commit de la candidata con el número más alto antes de la etiqueta final, para que las notas nombren todos los pull requests
que incluye la etiqueta.
Publicar la versión
-
Comprueba que una ejecución programada de
.github/workflows/docker-smoke.ymlenmainde la última semana haya pasado:gh run list -R ClickHouse/loom --workflow docker-smoke.yml --event schedule --branch main -L 1 --json conclusion,createdAt,headShaO inicia una nueva con
gh workflow run docker-smoke.yml -R ClickHouse/loom --ref mainy léela con--event workflow_dispatchen lugar de--event schedule. Analiza ambas imágenes igual que lo hace la versión, y el fallo de una ejecución programada solo notifica a la última persona que editó su programación. Un análisis en rojo nombra el paquete: mueve primero enmainla fijación que lo incorpora (unARGdelDockerfileo el digest de la imagen base, o un archivo de bloqueo). Los paquetes propios de la imagen base solo cambian con un nuevo digest de la imagen base; un paquete que añade una capaapt-get installcambia con cualquier compilación sin caché. -
En una rama a partir de
main, ejecuta.venv/bin/python scripts/release/prepare.py bump X.Y.Zy abre un pull request con sus cambios y conrelease-notes.mdcomo la sección de notas de la versión de su descripción; edita las notas donde alguna entrada lo necesite. CI debe pasar, incluidosmake schema-checky el ensayo estricto de migraciones. Cuando la entrada del changelog de un pull request fusionado indica que necesita la próxima versión del servidor, ese mismo pull request subeMIN_SERVER_VERSIONenintegrations/claude-code-plugin/lib/server-version.mjsa esta versión, lo sincroniza con el plugin de Codex y sube la versión de ambos plugins: los clientes lo reciben solo mediante una nueva versión del plugin. -
Después de fusionar el pull request de la versión, etiqueta su commit de fusión y sube la etiqueta. Para probar antes un candidato a versión, etiqueta ahí
vX.Y.Z-rc.1en su lugar, y la versión final más tarde sobre el commit del candidato con el número más alto (más abajo):git tag vX.Y.Z <merge commit> git push origin vX.Y.Z -
La subida de la etiqueta ejecuta
.github/workflows/release.yml(más abajo), publica las imágenes del servidor y del extractor, y solo entonces crea el GitHub Release; después comprueba desde fuera el instalador publicado (release-check). Lee esa ejecución antes del paso 5. -
Para publicar los SDK y la entrada del MCP Registry, ejecuta manualmente el mismo workflow sobre la etiqueta:
gh workflow run release.yml --ref vX.Y.ZCuando los jobs
pypiynpmde esa ejecución pasen, comprueba los SDK tal como los instala un usuario, con la actualización desde la versión anterior:gh workflow run release-check.yml -f version=X.Y.Z -f previous_version=<previous X.Y.Z>.previous_versiondebe ser una versión publicada anterior aversionque incluyainstall.shyloom-stack.tar.gz; omítela cuando no haya ninguna. -
Pega las notas de la versión generadas en el commit de la etiqueta final (notas de la versión) en el GitHub Release, encima de las notas generadas.
Un candidato a versión es una etiqueta vX.Y.Z-rc.N y crea un GitHub pre-release; la publicación rechaza cualquier
otra etiqueta de prelanzamiento. El primer candidato va sobre el commit de fusión del pull request de la versión, cuyos
archivos nombran X.Y.Z, de modo que el servidor del candidato ya informa X.Y.Z; uno posterior, tras una corrección,
va sobre un commit posterior de main. La etiqueta final vX.Y.Z va sobre el commit del candidato con el número más alto
tras la prueba. El paquete de la versión final conserva la versión de ClickHouse del candidato con el número más alto
en ese commit que tenga un paquete publicado; sus imágenes se construyen de nuevo desde el mismo
commit, sin caché, así que un paquete del sistema operativo puede ser más reciente que en la imagen probada. Se rechaza la ejecución de una
etiqueta de candidato posterior a su versión final. A una en el commit de la versión final se le indica que ejecute la final. Una
con número inferior al del candidato más alto en el commit de la versión final, como un candidato antiguo
lanzado para publicar sus SDK, no tiene nada que ejecutar, y su etiqueta permanece. Cualquier otra es una etiqueta huérfana: además
hace fallar las ejecuciones posteriores de la versión final hasta que se elimine. El appVersion del chart también nombra X.Y.Z,
así que una prueba en Kubernetes establece image.tag y extractor.image.tag en X.Y.Z-rc.N.
Solo la versión final más alta se convierte en el Latest release del repositorio (releases/latest sirve el
instalador) y mueve :latest: un prelanzamiento o un parche de una línea anterior deja ambos donde están.
Las versiones se leen de las etiquetas del repositorio, así que elimina una etiqueta final que no vaya a publicarse, o
Latest se queda por debajo de ella.
Ensayar un release
Una ejecución de prueba (dry run) compila, verifica y ejecuta pruebas de humo de todo lo que haría un release, en cualquier rama, y no publica nada: ni push de imágenes, ni GitHub Release, ni subida a registros.
gh workflow run release.yml --ref <branch> -f dry_run=true
Se ejecuta con la versión que indica server/__init__.py y conserva sus artefactos un día (un release los conserva 30 días, mientras se pueda volver a ejecutar una corrida). Sus imágenes van a los artefactos de la ejecución en lugar de ghcr.io, sin las atestaciones de procedencia ni de SBOM, que solo conserva un registro, y docker-smoke las carga desde ahí. El job preflight informa de cada requisito previo que falta como una advertencia en lugar de fallar. Lo que solo ejercita un release publicado, una ejecución de prueba no lo ejercita: docker-tag (unir los dos digests de cada imagen, la decisión de Latest, :latest), sign, el GitHub Release y las firmas de sus archivos, las publicaciones en registros, release-check, la comprobación de imágenes publicadas (scripts/release/published_images.sh) con la ruta de compilación omitida que selecciona, la comprobación del orden de candidatos (prepare.py check-tag, que una ejecución de prueba de una rama omite con un aviso) y la comprobación del chart cuando la versión ya está etiquetada en otro commit.
Antes del primer release
Un release publica paquetes públicos, y una versión de un registro nunca puede reutilizarse, por lo que el workflow
rechaza un release desde un repositorio privado. El job preflight comprueba, en segundos y antes de cualquier build,
lo que solo un propietario puede conceder, e indica la solución para cada requisito que falte:
| Requisito | Comprobado por |
|---|---|
| El repositorio es público | preflight |
ghcr.io/clickhouse/loom y loom-extractor dan acceso de escritura (Write) a este repositorio |
preflight (una sesión de subida que abre y cancela) |
| Ambos paquetes son públicos, ya que una instalación descarga sin iniciar sesión | preflight (un token de descarga anónimo) |
Un entorno pypi y un trusted publisher de PyPI para release.yml |
el job pypi |
Un entorno npm y un trusted publisher de npm para release.yml |
el job npm |
Un entorno mcp-registry con las mismas reglas de protección que pypi y npm |
el job mcp-registry |
| La retención de artefactos del repositorio es de al menos 30 días (Settings > Actions) | nada |
Las ramas release/** están protegidas como main (comprobaciones obligatorias, sin push directo) |
nada |
Solo un push crea un paquete de ghcr.io, y lo crea como privado. Para una imagen que ningún release ha subido
todavía, preflight emite una advertencia en lugar de fallar, y los jobs docker-smoke de esa ejecución fallan al descargarla: configura
la visibilidad del paquete como pública en su configuración y luego vuelve a ejecutar los jobs fallidos.
Hasta que un release se haya firmado, haz que la siguiente etiqueta sea un release candidate (vX.Y.Z-rc.1). Su ejecución
firma las imágenes y las verifica desde fuera, y un candidato nunca mueve :latest, así que un fallo
ahí cuesta un número de candidato, no una versión final.
Qué hace el workflow de release
.github/workflows/release.yml compila una vez, verifica los archivos exactos y publica esos mismos archivos.
Al hacer push de una etiqueta (v*):
versiontoma la versión de la etiqueta (vX.Y.Z→X.Y.Z) y rechaza una referencia que no sea una etiquetav*(salvo que la ejecución sea un ensayo) o que no seaX.Y.ZniX.Y.Z-rc.N. Falla cuando alguna de estas condiciones es falsa (paravX.Y.Z-rc.N, respecto deX.Y.Z):prepare.py check:server/__init__.pycontiene__version__ = "X.Y.Z", y todos los demás archivos de versión, incluidoserver.json, nombran esa versión;prepare.py check-tag: un candidatovX.Y.Z-rc.Nantes de etiquetarvX.Y.Z, y unvX.Y.Zfinal sobre el commit de su candidato con el número más alto;prepare.py check-chart: la versión del chart es superior a la de la release anterior;
preflighthace fallar la ejecución si falta un requisito previo;clickhousenombra la release de ClickHouse que ejecuta el bundle de Compose (scripts/release/release_clickhouse.sh), migra un servidor nuevo de esa release y ejecutamake schema-checkantes de quebuildpueda fijarla, y rechaza un downgrade de ClickHouse (véase el paso 8), de modo que una ejecución así se detiene antes de compilar y publicar imágenes (cuándo se detiene). La release es la primera de estas:- la que el bundle ya publicado de esta versión ya nombra, de modo que volver a ejecutar el comando de instalación
para una versión nunca mueve ClickHouse (una release sin bundle se resuelve de nuevo, ya que
github-releasenunca reemplaza uno, así que nadie puede haberla instalado); - el
clickhouse_imagede un dispatch, que para una versión final se usa en lugar de cualquier release que sus candidatos sobre el mismo commit hayan publicado; - para una versión final, la release con la que se probó el candidato de número más alto sobre el mismo commit que tenga un bundle publicado;
- la release que
clickhouse/clickhouse-server:latestnombra ahora (dev/clickhouse_release.sh);
- la que el bundle ya publicado de esta versión ya nombra, de modo que volver a ejecutar el comando de instalación
para una versión nunca mueve ClickHouse (una release sin bundle se resuelve de nuevo, ya que
buildescribe la versión en las fuentes del SDK de Python (en su forma PEP 440,X.Y.ZrcNpara un candidato) y en las fuentes del SDK de TypeScript, y compila el wheel y el sdist del SDK de Python, el tarball de npm (después delcheck:distdel SDK de TypeScript) y los zips de los dos plugins (loom-claude-code-plugin-vX.Y.Z.zip,loom-codex-plugin-vX.Y.Z.zip); también compila el bundle de Compose sin código fuente y su archivo SHA-256 (que nombra esa release de ClickHouse), elinstall.shde la release, que instala esta versión, yagent-setup.txt, el contrato de configuración del agente con esta versión y este commit rellenados (scripts/release/agent_setup.py);verifycomprueba esos archivos exactos: sus nombres y versiones incrustadas, los manifiestos de los plugins, que no haya tests en el zip de Claude Code, los bits de ejecución que registra git, y que el bundle nombre la release de ClickHouse que comprobó el jobclickhouse, queinstall.shinstale esta versión y queagent-setup.txtla fije, y ejecuta una prueba de humo del wheel en un venv limpio (scripts/gates/sdk_wheel_smoke.py);dockercompilaghcr.io/clickhouse/loom(con el commit de la etiqueta comoLOOM_BUILD_COMMIT, lo que/v1/healthinforma comobuild_commit) yghcr.io/clickhouse/loom-extractor(el servicio extractor de documentos), cada una para linux/amd64 y linux/arm64 en el runner propio de esa arquitectura y sin caché de compilación (es decir, a partir de los paquetes tal como están ese día), con procedencia y un SBOM, publica cada una por digest y la escanea;docker-tagune los dos digests de cada imagen bajo sus etiquetas, y no etiqueta ninguna imagen hasta que las cuatro hayan pasado (un fallo ahí puede dejar una etiquetada, y volver a ejecutarlo etiqueta ambas);signfirma después, por digest, el índice quedocker-tagcreó para cada imagen, con una firma sin clave (cosign, con la identidad de GitHub de la ejecución, de modo que el certificado nombrarelease.ymly la etiqueta); una ejecución sobre una etiqueta cuyas imágenes ya están publicadas no firma nada. Cada ejecución verifica entonces las firmas de ambas imágenes como lo hacen los usuarios, de modo que la GitHub Release, PyPI, npm y el MCP Registry esperan una firma que se verifique (una etiqueta o firma fallida);docker-smokeinstala el bundle con esas imágenes, sobre la release de ClickHouse que nombra, en amd64 y arm64, comprueba que la imagen del servidor nombre el commit de la etiqueta y luego ejecuta elinstall.shy el bundle de la propia release como el comando de una línea en contenedores limpios de Debian, Ubuntu y Alpine (instalación, ida y vuelta, nueva ejecución, un downgrade rechazado con elshy elawkpropios de cada uno, y una actualización sobre el instalador de la release final anterior o, en un ensayo de un commit posterior a la release de su versión, sobre el de esa misma release;scripts/gates/installer_rehearsal.py);github-releasecrea la GitHub Release una vez que ambas imágenes existen y están verificadas, con notas generadas a partir de los commits desde la release final anterior (prepare.py previous, una salida deversion; las notas de un candidato también empiezan ahí), o la actualiza en una nueva ejecución, conservando sus notas tal como están, y adjunta los archivos verificados. Un bundle que la release ya lleva se conserva, y también su checksum (si la release lo perdió, se escribe de nuevo a partir del bundle): reemplazar un recurso lo borra primero, y una subida fallida dejaría una versión instalada sin su bundle. Un bundle nuevo nunca nombra una release de ClickHouse más antigua que la de los bundles de las 30 releases más recientes (prereleases incluidas), ya que una instalación que actualice a él arrancaría un servidor más antiguo sobre datos que escribió uno más nuevo; en su lugar el job falla, salvo que el dispatch añada-f allow_clickhouse_downgrade=true. Este job se ejecuta para una etiqueta a la vez, de modo que dos etiquetas publicadas juntas no pueden pasar ambas la comprobación contra el mismo bundle más antiguo. Solo espera un job más de este tipo: la publicación de una tercera etiqueta cancela el que espera, que entonces debe volver a ejecutarse a mano (Re-run failed jobs). Un rechazo aquí llega después de quedocker-taghaya publicado las etiquetas de imagen de la etiqueta (y:latestcuando es la versión final más alta). Una nueva ejecución conserva las entradas de la ejecución y vuelve a fallar, así que hay que hacer dispatch de la etiqueta, lo que además publica los SDK y la entrada del MCP Registry. Hágase dispatch o bien con la release más reciente que nombra el error, cuando esa release volcó elschemas/schema.sqlde la etiqueta:gh workflow run release.yml --ref vX.Y.Z -f clickhouse_image=clickhouse/clickhouse-server:A.B.C.D; o bien aceptando el downgrade:gh workflow run release.yml --ref vX.Y.Z -f allow_clickhouse_downgrade=true. Cuando no se toma ninguna de las dos, devuelva:latest(si se movió) y, para una versión final,:X.Ya la release anterior en ambas imágenes, como en una etiqueta o firma fallida;sign-filesdescarga cada archivo que la release sirve ahora, como lo hacen los usuarios (scripts/release/download_release_files.sh), y firma cada uno que sea idéntico byte a byte a la compilación de esta ejecución con una firma sin clave como la de las imágenes, en un bundle de Sigstore<file>.sigstore.json(scripts/release/sign_release_files.sh). El bundle del stack y el checksum que la release conservó de una ejecución anterior mantienen sus bundles de Sigstore cuando estos se verifican; cualquier otro archivo que no sea la compilación de esta ejecución hace fallar el job, sin firmar nada (una etiqueta o firma fallida). Después verifica cada archivo como lo hacen los usuarios (scripts/release/verify_release_files.sh). Mantiene el token OIDC de la ejecución en un job propio, con contents de solo lectura;attach-signaturessube entonces los bundles de Sigstore que creó (uno conservado se queda como está, ya que reemplazar un recurso lo borra primero). Un dispatch compila los archivos de nuevo ygithub-releaselos reemplaza, así que hasta que terminen sus propiossign-filesyattach-signatures, los bundles de Sigstore de la ejecución de la etiqueta no verifican los archivos reemplazados;release-check(en un push de etiqueta) ejecuta.github/workflows/release-check.ymlcontra lo que se acaba de publicar, sin iniciar sesión en nada: el comando de una línea desde github.com en los mismos contenedores limpios, descargando ambas imágenes de forma anónima, y verifica las firmas de ambas imágenes y de cada archivo de la release, que deben provenir derelease.ymlen esa etiqueta, como lo hace un usuario (imágenes de contenedor, archivos de la release); un archivo sin su.sigstore.jsonfalla. Una release publicada antes de que el workflow de release firmara sus imágenes o sus archivos carece de esas firmas, por lo que una comprobación de ella hace fallar su jobsignatures.
Las imágenes del servidor y del extractor se publican antes que la GitHub Release, de modo que un instalador mostrado en la página de la release nunca apunte a una imagen inexistente.
En dispatch manual (workflow_dispatch sobre una referencia de etiqueta), se ejecutan los mismos jobs excepto
release-check, sin compilar ninguna imagen cuando las imágenes ya están publicadas (más abajo). build también
ejecuta npm run check del SDK de TypeScript (lint, tipos, versión, ejemplos del README, tests). Después se ejecutan
tres jobs de publicación:
| Job | Publica | Cómo |
|---|---|---|
pypi |
clickhouse-loom (solo el SDK de Python) en PyPI |
el wheel y el sdist verificados; trusted publishing (OIDC); los archivos que PyPI ya tiene se omiten |
npm |
@clickhouse/loom en npm con procedencia |
el tarball verificado; una versión publicada se omite; latest solo para la versión final más alta, una prerelease a next, un parche a una línea anterior a release-X.Y; trusted publishing (OIDC) |
mcp-registry |
server.json en el MCP Registry como io.github.ClickHouse/loom |
el archivo confirmado, cuya versión el job version comprueba contra la etiqueta; inicio de sesión con GitHub OIDC con un mcp-publisher fijado; una versión ya listada y una prerelease se omiten; preflight rechaza un repositorio privado antes de cualquier compilación |
Las imágenes ya están publicadas por la ejecución de la etiqueta: un dispatch sobre una etiqueta cuyas imágenes llevan
la versión no compila ni etiqueta ninguna (scripts/release/published_images.sh), hace pruebas de humo de las
publicadas y continúa con los registros. Las imágenes de la release se compilan sin caché, por lo que una recompilación
movería las etiquetas de la versión a otros bytes.
Nunca mueva una etiqueta X.Y.Z publicada: published_images.sh falla cuando una imagen publicada se compiló
desde un commit distinto al de la ejecución, y una corrección necesita una versión nueva.
Una nueva ejecución tras una publicación parcial es segura: cada job de publicación omite lo que ya existe. La única excepción es una ejecución de etiqueta cuya firma de archivos falló, que una etiqueta o firma fallida recupera.
Por qué publicar los archivos verificados. Un job que recompilara su propio artefacto podría publicar bytes sin comprobar. Publicar lo que verify aprobó significa que la GitHub Release y los registros llevan los mismos bytes.
Por qué el servidor no está en PyPI. El servidor se despliega junto a ClickHouse, no se importa como biblioteca; se distribuye como imagen. El pyproject.toml raíz está marcado como Private :: Do Not Upload, y PyPI solo contiene el SDK. Los jobs pypi y npm necesitan trusted publishers registrados para este repositorio (sus entornos de GitHub).
Por qué la publicación de los SDK es manual. Una publicación en un registro no se puede deshacer: PyPI nunca acepta una versión dos veces. Publicar los SDK solo con dispatch permite comprobar primero los archivos de la release. La imagen del servidor es automática porque es un requisito previo del instalador de la GitHub Release, y crear la etiqueta de release firmada es su puerta de revisión.
Una etiqueta o firma fallida
Un docker-tag fallido (una imagen etiquetada, la otra no) o un sign fallido (Sigstore caído, por ejemplo):
- Use “Re-run failed jobs” en la ejecución que etiquetó las imágenes (el push de la etiqueta, o el dispatch que
las compiló y etiquetó), dentro de los 30 días posteriores; los artefactos de la ejecución se conservan otro tanto, salvo que el
límite de retención de artefactos del repositorio sea más corto. Ese intento conserva su resultado de
preflighty los digests dedocker-tag, así que etiqueta la misma compilación y firma lo que etiquetó. - Una vez que la ejecución de etiquetado ha firmado, un dispatch fallido o un segundo push sobre la etiqueta se recupera con su propio “Re-run failed jobs”, o con un nuevo dispatch.
- No vuelva a ejecutar nunca una ejecución que falló antes de etiquetar una vez que otra ejecución ha etiquetado: su
preflightno vio imágenes, así que recompila y movería las etiquetas publicadas. - Una vez que “Re-run all jobs” ha reemplazado el intento de la ejecución de etiquetado, o han pasado los 30 días, ninguna
ejecución puede etiquetar ni firmar esa compilación: una ejecución sobre una versión medio etiquetada falla su
preflight, y una ejecución sobre una etiqueta publicada verifica las firmas pero no puede crearlas. Publique una versión nueva.
Hasta que esa versión salga, las etiquetas móviles de la compilación siguen nombrándola. Apunte :latest (si se movió) y,
para una versión final, :X.Y de nuevo a la release anterior que llevaba cada una, en ambas imágenes. Una X.Y.0 no tiene
una release anterior que lleve :X.Y, que nombra esta compilación hasta que salga X.Y.1. Con
<previous> la versión de esa release, la etiqueta se mueve solo una vez que la firma de esa release se verifica:
digest=$(docker buildx imagetools inspect ghcr.io/clickhouse/<image>:<previous> \
--format '{{json .Manifest}}' | jq -re .digest)
cosign verify "ghcr.io/clickhouse/<image>@$digest" \
--certificate-identity https://github.com/ClickHouse/loom/.github/workflows/release.yml@refs/tags/v<previous> \
--certificate-oidc-issuer https://token.actions.githubusercontent.com >/dev/null \
&& docker buildx imagetools create -t ghcr.io/clickhouse/<image>:<tag> "ghcr.io/clickhouse/<image>@$digest"
Para un <previous> publicado antes de que el workflow de release firmara, que no lleva firma, ejecute
la línea digest= y luego el comando docker buildx imagetools create sin el
cosign verify … && anterior. En ambos casos, compruebe que la etiqueta nombra el digest:
[ -n "$digest" ] && [ "$(docker buildx imagetools inspect ghcr.io/clickhouse/<image>:<tag> --format '{{json .Manifest}}' | jq -re .digest)" = "$digest" ] \
|| { echo "<tag> does not name $digest" >&2; false; }
Un sign-files o attach-signatures fallido (Sigstore o la API de GitHub caídos, por ejemplo) deja archivos en
la release sin un bundle de Sigstore que los verifique. Cualquier ejecución posterior los firma de nuevo mientras
el bundle del stack y el checksum de la release lleven bundles de Sigstore que se verifiquen: “Re-run failed jobs” en
la ejecución que falló. Cuando no llevan ninguno, porque falló la propia firma de la ejecución de la etiqueta, solo “Re-run
failed jobs” en la ejecución de la etiqueta los firma, mientras sus artefactos se conserven (30 días, salvo que el
límite de retención de artefactos del repositorio sea más corto) y antes de cualquier dispatch: un dispatch, “Re-run all
jobs” o un segundo push de la etiqueta recompila el bundle del stack y el checksum pero conserva los que la
release lleva, que entonces ninguna ejecución puede firmar. Pasado ese punto, publique una versión nueva.
Un release-check que falla en un listado o una descarga: “Re-run failed jobs”. Uno que encuentra un
bundle de Sigstore que no se verifica después de que sign-files y
attach-signatures de la última ejecución de release hayan pasado significa que la release cambió después de firmarse: un incidente de seguridad
(SECURITY.md). Una ejecución cuya firma falló se recupera como se indicó arriba.
sign-files rechaza cualquier archivo que no sea de la compilación de esta ejecución, excepto un bundle de stack o una suma de verificación conservados cuyo bundle de Sigstore se verifique. Un archivo adjuntado a la release a mano: elimínelo de la release cuando el workflow no lo genere y luego pulse “Re-run failed jobs”. Un bundle de stack o una suma de verificación conservados sin bundle de Sigstore nunca se firmaron (arriba). Cualquier otro rechazo, y un archivo conservado cuyo bundle de Sigstore no se verifique fuera de una caída de Sigstore, significa que el archivo se modificó fuera del workflow: es un incidente de seguridad, no un fallo de firma.
Cuando el job clickhouse se detiene
Una ejecución que se detuvo en clickhouse no publicó nada.
latestapunta a una release defectuosa: lance el tag con una release exacta,gh workflow run release.yml --ref vX.Y.Z -f clickhouse_image=clickhouse/clickhouse-server:A.B.C.D. Un bundle ya publicado conserva el suyo, y la ejecución avisa de que ignoró el valor indicado.- La release no genera el
schemas/schema.sqldel tag: regenérelo con esa release (los comandos del volcado del esquema conLOOM_CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:A.B.C.D) y haga commit. Para un candidato, cree el siguiente tag-rc.Nen el commit de la corrección. Para una versión final (una sin ningún candidato en su commit que haya publicado un bundle, ya que solo ese resuelvelatest), elimine su tag (git push origin :refs/tags/vX.Y.Z, ygit tag -d vX.Y.Zen cada clon que lo haya descargado, ya que un fetch nunca elimina un tag) y después cree un nuevo candidato en el commit de la corrección. En ambos casos lance el nuevo candidato con el mismo-f clickhouse_image=..., ya que el push de su tag vuelve a resolverlatest; déjelo en observación y cree ahí el tag de la versión final, lo que conserva esa release. - Un downgrade durante la observación: también se comprueba una versión final que lleva la release de su candidato, de modo que un
parche a una línea anterior publicado durante la observación con una release más reciente la detiene. Hay dos salidas:
- elimine el tag de la versión final como se indicó (no publicó nada), cree un nuevo candidato en ese commit,
déjelo en observación y vuelva a crear ahí el tag de la versión final. El push del tag del candidato resuelve
latest; cuando esa release es anterior a la que nombra el error, lance el candidato con esa release:gh workflow run release.yml --ref vX.Y.Z-rc.N -f clickhouse_image=clickhouse/clickhouse-server:A.B.C.D; - o lance la versión final con
-f allow_clickhouse_downgrade=truey acepte el downgrade para las instalaciones de ese parche.
- elimine el tag de la versión final como se indicó (no publicó nada), cree un nuevo candidato en ese commit,
déjelo en observación y vuelva a crear ahí el tag de la versión final. El push del tag del candidato resuelve
Cada lanzamiento anterior también ejecuta los jobs pypi y npm, así que un candidato lanzado publica
sus SDK una vez aprobados sus entornos; rechace esas aprobaciones para publicar solo las imágenes y
la GitHub Release.
Instalación desde un GitHub Release
Cuando los registros no se han publicado, instala desde los recursos del release:
gh release download vX.Y.Z --repo ClickHouse/loom --pattern 'clickhouse_loom-*.whl'
pip install ./clickhouse_loom-*.whl
gh release download vX.Y.Z --repo ClickHouse/loom --pattern 'clickhouse-loom-*.tgz'
npm install ./clickhouse-loom-*.tgz
Los plugins para agentes de programación se instalan desde los marketplaces del repositorio (claude plugin marketplace add ClickHouse/loom, codex plugin marketplace add ClickHouse/loom). Los archivos zip son para máquinas sin acceso al repositorio.
Listados
Los agentes y las personas encuentran Loom a través de estos listados. Cada uno lee archivos de este repositorio:
| Listado | Lee | Cómo se actualiza |
|---|---|---|
| MCP Registry y los directorios que lo copian | server.json: sus metadatos y un remoto en https://{loom_host}/mcp con un encabezado Authorization secreto opcional |
el job mcp-registry en cada versión final despachada |
Página de PyPI de clickhouse-loom |
los metadatos de [project] de sdk/python/pyproject.toml y sdk/python/README.md como cuerpo de la página |
el job pypi en cada versión despachada; la página muestra la versión final más alta, o el candidato más alto antes de la primera versión final |
Página de npm de @clickhouse/loom |
los metadatos de sdk/typescript/package.json y sdk/typescript/README.md como cuerpo de la página |
el job npm en cada versión despachada; la página muestra la versión etiquetada como latest, que el job asigna solo a la versión final más alta |
| Directorio de plugins de Claude | integrations/claude-code-plugin/.claude-plugin/plugin.json (displayName, description, keywords, icon, documentationUrl, supportUrl, privacyPolicyUrl) y el README |
se envía una sola vez en el portal para desarrolladores; las versiones posteriores se toman de la rama seguida. El icono se lee solo en el primer envío |
| Sugerencias de plugins de Claude Code | el bloque relevance de la entrada loom en .claude-plugin/marketplace.json: el comando loom, los archivos de configuración de Loom, una dependencia del SDK en un manifiesto |
se lee del marketplace en la rama predeterminada; se muestra solo donde un administrador incluye el marketplace en la lista de permitidos (pluginSuggestionMarketplaces) |
| Cursor Marketplace | .cursor-plugin/plugin.json (displayName, description, keywords, logo, variables), .cursor-plugin/marketplace.json |
no se envía; un envío en cursor.com/marketplace/publish se revisa a mano, y también cada actualización |
| Marketplace de Awesome Copilot | el plugin.json y el mcp.json de la raíz (el paquete Agent Plugins), en la etiqueta de versión y el commit que indica el envío |
no se envía; un envío pasa por el formulario de incidencia de plugins externos de github/awesome-copilot, que comprueba el paquete y lo instala con Copilot CLI; una versión nueva es un pull request a plugins/external.json de ese repositorio |
| Directorio de plugins de Codex | integrations/codex-plugin/.codex-plugin/plugin.json (interface) |
se envía en el portal de plugins; un plugin con hooks de ciclo de vida no es elegible allí, así que el listado público necesita una compilación sin ellos |
| Índice de documentación para agentes de código | context7.json |
se actualiza desde la rama predeterminada una vez que el repositorio se ha añadido una vez |
| Índice de Agent Skills | skills/loom-code, skills/loom y las skills del plugin de Claude Code; las skills para colaboradores están marcadas como internas en su frontmatter y no se ofrecen |
se ordena por las instalaciones de npx skills add ClickHouse/loom; no hay nada que enviar |
El job mcp-registry se ejecuta en el entorno mcp-registry. Dale las mismas reglas de protección que a pypi y npm antes del primer despacho: GitHub crea un entorno que falta sin ninguna. Su inicio de sesión no necesita ningún secreto.
Después de cambiar el manifiesto de Claude o la entrada del marketplace, y antes de hacer push, ejecuta claude plugin validate integrations/claude-code-plugin --profile directory --strict para el plugin y claude plugin validate . para el marketplace: ejecutan las comprobaciones estructurales del directorio, y las del plugin deben pasar sin ninguna advertencia.
Después del release
- Despliégalo (actualizaciones). Los pasos para operadores de las notas del release son la lista de verificación del despliegue.
- Los plugins de cliente se actualizan mediante el gestor de plugins de cada cliente, no mediante un despliegue del servidor.
Relacionado
- Campos desconocidos y eliminados: cómo ve un cliente un campo que una versión ha eliminado
- Contribuir