Trocar de versão

Cada repositório do Airframe roda uma combinação fixa e testada das ferramentas da plataforma, chamada versão da plataforma, e passa para uma mais nova de propósito, com um merge request pequeno. Esta página é o guia prático para essa troca, para voltar atrás, para o dia em que um pipeline diz que a sua versão foi revogada e, para quem mantém a plataforma, para criar uma versão nova. Versões da plataforma explica o que é uma versão e por que ela existe.

Uma versão tem um identificador com data na forma YYYY.MM.DD-N, como 2026.09.30-2. A lista de versões que podem rodar é o releases/permitted.yaml do control-plane na main, e nada mais: uma versão está permitted ou revoked.

1. Veja qual versão você roda

Neste site: o rodapé de cada página nomeia a versão que o site descreve. Ela é lida, quando o site é construído, do próprio arquivo de pipeline do repositório do site.
Em um repositório: o .gitlab-ci.yml dele inclui os componentes da plataforma como gitlab.com/projectairframe/control-plane/<component>@<commit>. O manifesto de uma versão, releases/<id>.yaml no control-plane, nomeia o commit do control-plane que pertence a ela.
Em um pipeline: abra o job gate:integrity. Ele imprime o veredito do controle de aprovação, que nomeia a versão que o pipeline roda: um identificador, unknown para um commit que nenhuma versão nomeia ou uma referência que se move, ou none para um pipeline sem componentes da plataforma.

2. Instale o comando uma vez

O comando airframe fica no diretório cli/ do control-plane. Instale-o a partir de um clone do control-plane com um link no seu caminho:

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

O comando lê as versões desse clone, então atualize a main dele antes de mover um repositório; um clone desatualizado não conhece a versão mais nova.

3. Mova um repositório para uma versão

Onde: o repositório que você vai mover, em um branch.

Rode o comando com a versão que você quer:
Janela do terminal
```
airframe pin --release <id>
```
Ele reescreve cada referência que os arquivos de pipeline do repositório levam para os commits dessa versão: as inclusões de componentes, os commits do template e do golden-path, a inclusão das políticas de segurança, e o identificador da versão onde um arquivo o nomeia. Ele imprime cada arquivo que mudou. Ele recusa uma versão revogada ou que não está na lista.
Leia o diff. Ele muda só arquivos de pipeline, nunca o código da aplicação nem a infraestrutura.
Rode airframe pin --check para listar qualquer inclusão que ainda esteja em uma referência que se move.
Abra um merge request com essa mudança e mais nada.
Quem aprova: para um produto, alguém da equipe do produto ou da equipe de plataforma que não seja o autor, e depois o controle de aprovação, porque o arquivo de pipeline pertence às duas; para um repositório da plataforma, a equipe de plataforma e depois o controle. Uma aprovação da plataforma basta enquanto uma só pessoa a mantém; a arquitetura pede duas. Hoje quem aprova são as próprias contas do mantenedor: o mecanismo está aplicado, mas a separação entre duas pessoas ainda não é real.
Faça o merge. O próximo pipeline roda a versão nova.

4. Volte atrás

Voltar é o mesmo comando com a versão anterior, e o mesmo tipo de merge request. Você só pode voltar para uma versão que continue permitted: o comando recusa uma revogada, e o controle de aprovação também recusaria.

5. Quando um pipeline diz que a versão foi revogada

Uma versão revogada é uma em que uma revisão encontrou um defeito. Assim que a linha dela na lista de versões permitidas muda na main do control-plane, o controle de aprovação faz falhar qualquer pipeline novo que ainda esteja fixado nela, no job gate:integrity, com uma mensagem desta forma:

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

O executor recusa a mesma versão nas execuções de um merge request, antes de ter qualquer credencial (aplicado). Faça o que a mensagem diz: os passos 3.1 a 3.6 com a versão que ela nomeia. O próprio pipeline do merge request é julgado no seu próprio commit, que já nomeia a versão nova, então ele roda.

Um commit que nenhuma versão nomeia, ou o nome de um branch em uma inclusão, passa hoje com um aviso no veredito. Está previsto que a próxima versão o recuse (projetado), então fixe uma versão permitida antes disso.

6. Crie uma versão (quem mantém a plataforma)

Onde: os quatro repositórios das cinco partes (os módulos ficam no golden-path), e depois o control-plane. Quem aprova: a equipe de plataforma em cada um, e o controle de aprovação em cada um menos o security-policies, que o controle não julga. Como no passo 3, hoje quem aprova pela plataforma são as próprias contas do mantenedor.

Fixe as partes umas nas outras, um merge request por repositório: o template do golden-path e o template de produto das políticas de segurança incluem o control-plane no commit novo, o copier.yml do golden-path nomeia o commit dos módulos, e o platform-skills testa contra os commits novos do control-plane e do golden-path. airframe pin <commit> escreve o commit do control-plane; ele aceita só um commit completo de 40 caracteres, nunca um branch nem um commit abreviado.
No control-plane, adicione releases/<YYYY.MM.DD-N>.yaml com o identificador, a data, os cinco commits que já tiveram merge (control_plane, golden_path, modules, security_policies, platform_skills) e uma nota, e adicione <id>: {state: permitted} ao releases/permitted.yaml, em um só merge request.
Rode antes airframe release check --remote: ele busca cada commit e falha quando uma parte fixa outro commit que não o que a versão nomeia.
Dois jobs precisam passar antes que o merge request possa fazer o merge (aplicado): release:check, que também falha quando um manifesto anterior mudou, e os jobs release:verify, que rodam as verificações próprias de cada parte nos commits da versão.
Distribua a versão com o passo 3 em cada repositório.

7. Revogue uma versão (quem mantém a plataforma)

Onde: control-plane, releases/permitted.yaml, em um merge request que a equipe de plataforma e o controle de aprovação aprovam; como no passo 3, hoje quem aprova pela plataforma são as próprias contas do mantenedor.

Mova antes cada repositório que esteja nessa versão para a sucessora, como a plataforma fez nas suas próprias revogações, para que nenhum pipeline atual pare.
Mude a linha da versão para {state: revoked, reason: <why>, upgrade_to: <a permitted release>}. O release:check recusa uma revogação sem motivo ou com uma atualização que não está permitida.
Deixe o manifesto onde está: um manifesto que já teve merge nunca muda, então o registro do que rodou fica.

O controle de aprovação lê a lista de versões permitidas da main do control-plane e a guarda por cinco minutos, então uma revogação chega a cada pipeline novo poucos minutos depois do merge.

Onde fica

No repositório control-plane: