Pasar de una versión a otra

Cada repositorio de Airframe ejecuta una combinación fija y probada de las herramientas de la plataforma, llamada versión de la plataforma, y pasa a una más nueva a propósito, con un merge request pequeño. Esta página es la guía práctica para ese paso, para volver atrás, para el día en que un pipeline dice que su versión fue revocada y, para quienes mantienen la plataforma, para crear una versión nueva. Versiones de la plataforma explica qué es una versión y por qué existe.

Una versión tiene un identificador con fecha de la forma YYYY.MM.DD-N, como 2026.09.30-2. La lista de versiones que pueden ejecutarse es releases/permitted.yaml de control-plane en main, y nada más: una versión está permitted o revoked.

1. Ve qué versión ejecuta

En este sitio: el pie de cada página nombra la versión que describe el sitio. Se lee, cuando se construye el sitio, del propio archivo de pipeline del repositorio del sitio web.
En un repositorio: su .gitlab-ci.yml incluye los componentes de la plataforma como gitlab.com/projectairframe/control-plane/<component>@<commit>. El manifiesto de una versión, releases/<id>.yaml en control-plane, nombra el commit de control-plane que le corresponde.
En un pipeline: abre el trabajo gate:integrity. Imprime el veredicto de la compuerta de aprobación, que nombra la versión que ejecuta el pipeline: un identificador, unknown para un commit que ninguna versión nombra o una referencia que se mueve, o none para un pipeline sin componentes de la plataforma.

2. Instala el comando una vez

El comando airframe vive en el directorio cli/ de control-plane. Instala el comando desde un clon de control-plane con un enlace en tu ruta:

ln -s "$PWD/cli/airframe" ~/.local/bin/airframe

El comando lee las versiones de ese clon, así que actualiza tu main antes de mover un repositorio; un clon desactualizado no conoce la versión más nueva.

3. Mueve un repositorio a una versión

Dónde: el repositorio que va a mover, en una rama.

Ejecuta el comando con la versión que quieres:
Ventana de terminal
```
airframe pin --release <id>
```
Reescribe cada referencia que llevan los archivos de pipeline del repositorio a los commits de esa versión: las inclusiones de componentes, los commits de la plantilla y de golden-path, la inclusión de las políticas de seguridad, y el identificador de la versión donde un archivo lo nombra. Imprime cada archivo que cambió. Rechaza una versión revocada o que no está en la lista.
Lee el diff. Solo cambia archivos de pipeline, nunca el código de la aplicación ni la infraestructura.
Ejecuta airframe pin --check para listar cualquier inclusión que siga en una referencia que se mueve.
Abre un merge request con ese cambio y nada más.
Quién aprueba: para un producto, alguien del equipo del producto o del equipo de plataforma que no sea el autor, y después la compuerta de aprobación, porque el archivo de pipeline pertenece a los dos; para un repositorio de la plataforma, el equipo de plataforma y después la compuerta. Basta una aprobación de la plataforma mientras una sola persona la mantiene; el diseño pide dos. Hoy quienes aprueban son las propias cuentas del mantenedor: el mecanismo está aplicado, pero la separación entre dos personas todavía no es real.
Haz el merge. El siguiente pipeline ejecuta la versión nueva.

4. Vuelve atrás

Volver es el mismo comando con la versión anterior, y el mismo tipo de merge request. Solo puede volver a una versión que siga permitted: el comando rechaza una revocada, y la compuerta también lo haría.

5. Cuando un pipeline dice que la versión fue revocada

Una versión revocada es una en la que una revisión encontró un defecto. En cuanto su línea en la lista de versiones permitidas cambia en el main de control-plane, la compuerta de aprobación hace fallar cualquier pipeline nuevo que siga fijado a ella, en el trabajo gate:integrity, con un mensaje de esta forma:

release <id> is revoked: <reason>; run `airframe pin --release <upgrade>` and merge it (ADR-0031)

El ejecutor rechaza la misma versión en las ejecuciones de un merge request, antes de tener cualquier credencial (aplicado). Haz lo que dice el mensaje: los pasos 3.1 a 3.6 con la versión que nombra. El propio pipeline del merge request se juzga en su propio commit, que ya nombra la versión nueva, así que se ejecuta.

Un commit que ninguna versión nombra, o el nombre de una rama en una inclusión, pasa hoy con una advertencia en el veredicto. Está previsto que la próxima versión lo rechace (diseñado), así que fija una versión permitida antes.

6. Crea una versión (quienes mantienen la plataforma)

Dónde: los cuatro repositorios de las cinco partes (los módulos viven en golden-path), y después control-plane. Quién aprueba: el equipo de plataforma en cada uno, y la compuerta de aprobación en cada uno menos security-policies, que la compuerta no juzga. Como en el paso 3, hoy quienes aprueban por la plataforma son las propias cuentas del mantenedor.

Fija las partes entre sí, un merge request por repositorio: la plantilla de golden-path y la plantilla de producto de las políticas de seguridad incluyen control-plane en el commit nuevo, el copier.yml de golden-path nombra el commit de los módulos, y platform-skills prueba contra los commits nuevos de control-plane y de golden-path. airframe pin <commit> escribe el commit de control-plane; acepta solo un commit completo de 40 caracteres, nunca una rama ni un commit abreviado.
En control-plane, agrega releases/<YYYY.MM.DD-N>.yaml con el identificador, la fecha, los cinco commits con merge (control_plane, golden_path, modules, security_policies, platform_skills) y una nota, y agrega <id>: {state: permitted} a releases/permitted.yaml, en un solo merge request.
Ejecuta primero airframe release check --remote: trae cada commit y falla cuando una parte fija otro commit que el que nombra la versión.
Dos trabajos tienen que pasar antes de que el merge request pueda hacer el merge (aplicado): release:check, que también falla cuando cambió un manifiesto anterior, y los trabajos release:verify, que ejecutan las verificaciones propias de cada parte en los commits de la versión.
Distribuye la versión con el paso 3 en cada repositorio.

7. Revoca una versión (quienes mantienen la plataforma)

Dónde: control-plane, releases/permitted.yaml, en un merge request que aprueban el equipo de plataforma y la compuerta de aprobación; como en el paso 3, hoy quienes aprueban por la plataforma son las propias cuentas del mantenedor.

Mueve primero cada repositorio que esté en esa versión a su sucesora, como hizo la plataforma en sus propias revocaciones, para que ningún pipeline actual se detenga.
Cambia la línea de la versión a {state: revoked, reason: <why>, upgrade_to: <a permitted release>}. release:check rechaza una revocación sin motivo o con una actualización que no está permitida.
Deja el manifiesto donde está: un manifiesto con merge nunca cambia, así que el registro de lo que se ejecutó se conserva.

La compuerta de aprobación lee la lista de versiones permitidas del main de control-plane y la guarda cinco minutos, así que una revocación llega a cada pipeline nuevo pocos minutos después del merge.

Dónde está

En el repositorio control-plane: