O primeiro produto

Esta página é o guia prático para o primeiro produto de uma equipe no Airframe. Ela nomeia o arquivo que você escreve em cada passo, quem precisa aprová-lo, e o que acompanhar enquanto a plataforma constrói o resto. Ela segue o mesmo caminho que a vida de um produto, um nível mais perto do teclado, e supõe que o domínio e o contexto do produto já existem.

O exemplo é um produto novo da equipe da loja da organização de demonstração, giftcards, no contexto shop/store/ordering.

1. Escreva a entrada

Onde: o repositório do catálogo, um arquivo novo com o nome do caminho do produto, products/shop.store.ordering.giftcards.yaml.

product: giftcards
journey: shop
domain: store
context: ordering
team: store-core
criticality: 3
data_classification: internal
rto: 4h
rpo: 1h
monthly_budget: 10
template: fullstack
stack: node
slo: { availability: 99.0, latency_p95_ms: 400 }
sandbox: true
lifecycle: { status: active }

O que o arquivo de um produto contém explica cada campo. Três deles escolhem o que você recebe: template: fullstack pede um repositório gerado a partir do template do golden path, stack escolhe a aplicação (node, python-fastapi ou java-spring), e sandbox: true adiciona um ambiente permanente para os consumidores do produto.

Antes de abrir o merge request, confira o que o lint do catálogo vai verificar:

a equipe existe e vive neste contexto, e pelo menos uma pessoa que pode fazer merge no produto tem uma conta no GitLab;
a equipe de um produto de criticidade 1 ou 2 tem dois membros com um papel de plantão;
o nome tem de 2 a 10 caracteres, não é usado no domínio, e nunca foi usado por um produto removido;
os orçamentos de todos os produtos e espaços de teste ainda cabem no orçamento mensal da organização no catalog.yaml.

Rode npm run lint em um clone do catálogo para ver as mesmas mensagens no seu notebook.

2. Abra o merge request e consiga as aprovações

Quem aprova: uma pessoa da equipe do produto, dos líderes do contexto ou dos líderes do domínio, que não seja nem o autor nem alguém que fez um commit, e um líder do domínio, porque o orçamento de uma entrada nova conta como um aumento a partir de zero. A aprovação de um líder do domínio cobre as duas coisas. O controle de aprovação verifica essas aprovações contra o modelo de responsáveis do catálogo e adiciona a sua, que a política de aprovação do security-policies exige antes que o catálogo possa integrar a mudança (aplicado).

Alguns campos trazem outros aprovadores:

um monthly_budget acima de zero, que toda entrada nova tem, e qualquer aumento posterior precisam de um líder do domínio;
uma assinatura em consumes precisa de um responsável pelo produto que publica, a menos que o tópico esteja marcado como inner source;
um destino em calls precisa de um responsável pelo produto chamado;
um serviço em services precisa de um líder do domínio.

3. Acompanhe a nota de progresso

Depois do merge, o pipeline do catálogo inicia a cadeia de reconciliadores e um job, progress:track, que escreve uma nota no merge request integrado e a mantém atualizada. A nota mostra cada passada da cadeia com o horário e o link, depois o repositório novo, o primeiro pipeline dele e o momento em que o nome de host responde. Se algo falha, a nota nomeia o job que falhou e o próximo passo. O job para quando o produto está no ar ou falhou, ou depois de três horas, e diz qual das duas coisas aconteceu.

No ensaio da plataforma de 2026-09-20, a cadeia levou cerca de trinta minutos do merge até o repositório.

4. Fature o produto

Onde: landing-zone, a fábrica de projetos do domínio: adicione o nome do produto a billed_products em roots/project-factory/shop-store/variables.tf. Quem aprova: a equipe da plataforma.

Os dois projetos do produto existem sem faturamento, com suas identidades e permissões. Enquanto não forem faturados, o pipeline dele planeja de verdade e o apply para no primeiro serviço que precisa de faturamento. O faturamento fica separado porque a conta de faturamento só consegue vincular um número limitado de projetos, então ocupar mais dois é uma decisão própria.

Este passo pode vir primeiro. No ensaio, o merge request de faturamento foi integrado três minutos antes da entrada do catálogo, então o primeiro pipeline do produto aplicou na hora. Se você faturar depois, siga Custo e faturamento, passos 3 a 5. O pipeline do próprio merge de faturamento aplica só a raiz da fábrica; a raiz de rede conecta os projetos à rede compartilhada só em um pipeline posterior do landing-zone, que alguém autorizado a rodar pipelines na main do landing-zone inicia sob demanda. Inicie um pipeline novo na main do produto só depois que esse tiver aplicado: as pessoas que podem fazer merge no produto podem fazer isso.

5. A primeira implantação

Ninguém aprova este passo separadamente: o primeiro commit do repositório é gerado pela plataforma a partir da entrada, e o merge request do catálogo é a aprovação dele. O controle de aprovação o admite como o primeiro commit de um repositório de produto gerado a partir do catálogo.

O pipeline desse commit roda na main como todos os seguintes. O build:request faz o construtor confiável gerar as imagens, e o pipeline planeja cada raiz com plan:<root>, verifica cada plano com policy:<root> e o aplica com apply:<root>: primeiro não produção, depois o sandbox, depois produção com a imagem promovida. Em seguida, grafana:reconcile e edge:reconcile pedem ao controle de aprovação que rode os pipelines do operations e do landing-zone, que colocam os painéis do produto e o nome de host dele na borda compartilhada.

O produto responde em giftcards.store.shop.projectairframe.dev, atrás do login único para o seu grupo de usuários. No ensaio, isso aconteceu cerca de oitenta e cinco minutos depois que a entrada do catálogo foi integrada; criar os bancos de dados levou a maior parte desse tempo.

6. A primeira mudança

Onde: o repositório do próprio produto, projectairframe/shop/store/ordering/giftcards.

Clone-o, crie uma branch, mude algo em apps/ ou uma raiz em infra/, e rode airframe validate.
Abra um merge request. O pipeline dele roda no runner não confiável, sem nenhuma credencial da nuvem.
Quem aprova: uma pessoa que o modelo de responsáveis nomeia para o que mudou, que não seja o autor: a equipe para infra/; a equipe ou a equipe da plataforma para o arquivo do pipeline e .airframe/.
Leia os planos e o custo que o executor publica, e teste a prévia no nome de host próprio do merge request.
Faça o merge. O pipeline da main aplica.

O caminho de uma mudança acompanha esses passos em detalhe.

Até que mais dois merge requests sejam integrados, a aprovação do controle ainda não é obrigatória no repositório novo: só a de uma pessoa nomeada que não escreveu a mudança. Onde: o gate/infra/terraform.tfvars do control-plane, que adiciona o repositório a ownership_enforced, e depois o .gitlab/security-policies/policy.yml do security-policies, que o adiciona ao escopo da política required ownership gate. Quem aprova: a equipe da plataforma no control-plane; um mantenedor que não a escreveu no security-policies. Hoje a segunda pessoa em cada caso é a segunda conta do mantenedor: o mecanismo é aplicado, mas a separação entre duas pessoas ainda não é real.

Onde fica

No repositório landing-zone:

No repositório catalog:

No repositório control-plane: