Versões da plataforma

Cada repositório do Airframe roda no seu pipeline as ferramentas da própria plataforma: os componentes de pipeline, o pacote de políticas e as políticas de segurança injetadas; e cada produto parte do template de produto da plataforma. Uma versão da plataforma fixa exatamente qual versão de cada uma dessas partes vai junto, com um nome datado como 2026.09.30-2. Os repositórios passam de uma versão para a seguinte de propósito, e uma versão com falha pode ser revogada, o que para todo pipeline novo que ainda a use.

Por que as versões existem

As ferramentas da plataforma mudam com frequência, e um pipeline que pegasse em silêncio a versão mais nova de cada parte quebraria de jeitos que ninguém conseguiria rastrear. Além disso, as partes dependem umas das outras: o template inclui os componentes de pipeline, e as skills são testadas contra o pacote de políticas. Uma mudança em uma precisa ser verificada contra as outras antes que alguém a rode.

Uma versão resolve os dois problemas. Ela nomeia uma combinação testada, e cada repositório diz qual combinação roda.

O que é uma versão

Uma versão é um pequeno arquivo no repositório control-plane, releases/<id>.yaml, chamado manifesto. Ele nomeia o commit exato de cada uma de cinco partes:

control-plane: os componentes de pipeline, o pacote de políticas e as imagens da plataforma;
golden-path: o template de produto;
os módulos: os módulos de Terraform que o template usa;
security-policies: os jobs injetados em cada pipeline de produto;
platform-skills: as skills que um agente de código carrega.

Um segundo arquivo, releases/permitted.yaml, lista cada versão e se ela pode rodar: permitted, ou revoked com um motivo e a versão para a qual mudar. Um manifesto nunca é apagado, então o registro do que rodou fica.

Como uma versão é feita

Cortar uma versão é uma sequência curta de merge requests:

Cada parte é fixada nas outras nos commits novos, com um merge request por repositório. O comando airframe pin <commit> reescreve os includes do arquivo de pipeline.
Um merge request em control-plane adiciona o manifesto e sua linha permitted. Dois jobs precisam passar antes que ele possa ser integrado: release:check busca cada commit nomeado e falha se uma parte fixa um commit diferente do que a versão nomeia, e a família de jobs release:verify roda as verificações de cada parte nesses commits, como os testes do pacote de políticas, as três pilhas do template, os testes dos módulos e os testes das skills.

Só uma versão que passou nas duas coisas chega a ser permitida.

Como um repositório usa uma versão

Um repositório muda para uma versão com airframe pin --release <id>, que reescreve os includes do seu arquivo de pipeline para os commits da versão, e um merge request sem mais nada. Voltar é o mesmo comando com a versão anterior. Como só muda o arquivo de pipeline, é fácil de revisar e fácil de desfazer.

Revogar uma versão

Quando uma revisão encontra uma falha em uma versão, a correção é um merge request que muda sua linha em releases/permitted.yaml para revoked, com um motivo e um upgrade_to.

A partir daí, duas coisas a recusam:

o controle de aprovação, em cada pipeline novo: seu job de integridade lê o arquivo de pipeline no commit, compara com a lista de permitidas na branch main de control-plane, e faz falhar um pipeline fixado em uma versão revogada, nomeando a versão para a qual mudar;
o executor, em cada execução de merge request e de versão, antes de ter qualquer credencial.

Isso já aconteceu. As versões 2026.09.28-1, 2026.09.28-2 e 2026.09.29-1 foram revogadas depois que as revisões de 2026-09-29 encontraram falhas nos seus jobs de pipeline, e a lista de permitidas nomeia 2026.09.30-1 como a versão para a qual mudar.

O que uma equipe faz quando sua versão é revogada

O pipeline que falha diz o que fazer: rodar airframe pin --release com a versão que ele nomeia, e abrir um merge request só com essa mudança. Depois que ele é integrado, os pipelines do repositório voltam a rodar. Um commit que nenhuma versão nomeia, ou uma referência que se move, como uma branch, hoje é um alerta e está previsto para virar uma recusa na próxima versão.

Onde fica

No repositório control-plane: