Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português
Aviso: desenvolvemos o Carbon Forge, e o AEGIS ao lado dele, na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública, principalmente o passo 8 de Working in lanes, Source control settings, MCP tools catalog: Lanes, continued e Source control: how it is built and why, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. A tabela, as chamadas e a recusa são as da própria documentação, e as citações ficam em inglês com a tradução ao lado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.
Por que guardar a regra no registro
A documentação dá o motivo em duas frases: "Landing rules are the code-owners rule kept in the record. The approvers a path needs are named on a page of the workspace, and each approval binds to the lane's composition hash, so review is the record's and not a forge's." (As regras de integração são a regra de code owners guardada no registro. Os aprovadores de que um caminho precisa são nomeados numa página do workspace, e cada aprovação se liga ao hash de composição da lane, então a revisão é do registro e não de uma forja.) Sem isso, "a landing can carry code no approver saw." (uma integração pode levar código que nenhum aprovador viu). Um limite logo de cara: "Carbon runs no review itself." (O Carbon não faz revisão nenhuma sozinho.) Ele registra quem aprovou o quê; a revisão é feita por pessoas e pelos workflows que você nomeia.
Passo 1. Proteja o trunk
As regras só são lidas num trunk protegido. Um administrador do workspace marca Protect the trunk em Settings, Workspace, Source control, e opcionalmente Protect pages and atoms too. Um agente confere a configuração com:
workspaces.get_settings {}
→ { "workspaceId": "…", "trunkProtected": true, "trunkProtectedEntities": false }A partir daí "the trunk moves only by a lane's landing" (o trunk só anda pela integração de uma lane), e uma gravação direta é recusada com workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.
Passo 2. Escreva a página .landing-rules
Crie uma página no caminho reservado .landing-rules cuja primeira tabela Markdown tenha o cabeçalho glob | approvers | gate. O exemplo da documentação:
| glob | approvers | gate |
| --- | --- | --- |
| app/src/billing/** | <user id>, <user id> | |
| docs/** | <user id> | docs-review |glob: uma regra na sintaxe de regras de exclusão da importação, sem começar com!.approvers: ids de usuário separados por vírgula, cada um membro do workspace. Pode ficar vazio numa linha que nomeia um portão.gate: opcional, o nome de um workflow do AEGIS, no máximo 128 caracteres. "Carbon never runs it." (O Carbon nunca o executa.)
Só um administrador do workspace grava esta página, no trunk ou numa lane; qualquer outra pessoa recebe a recusa The landing rules page .landing-rules is reserved: only a workspace admin writes it.
Passo 3. Confira se o servidor a lê como válida
A seção Landing rules do diálogo de configurações informa <n> rules, valid., ou aponta uma linha malformada com Every landing is refused until it is fixed. Uma linha que nomeia alguém que não é membro, ou que não nomeia nem aprovador nem portão, está malformada. Uma página quebrada para todas as integrações, então confira isso antes de contar com ela.
Passo 4. Faça o trabalho numa lane
Abra uma lane e grave nela como mostra Working in lanes. Na integração, cada caminho que a lane toca é comparado com cada linha: uma página pelo caminho, uma página movida pelos dois caminhos, um arquivo de árvore como <tree path>/<entry path>.
Passo 5. Leia o que a lane ainda precisa
lanes.create { "label": "agent/7/fix-login" }
lanes.get { "label": "agent/7/fix-login" }
lanes.export { "lane": "agent/7/fix-login" } // header line: # composition: <hash>
lanes.approve { "lane": "agent/7/fix-login" }lanes.get lista quem aprovou, quem falta e se cada portão está pending ou satisfied. No aplicativo, o Overview de uma lane mostra o mesmo: as regras que ela casa, aprovadas n de m, e uma aprovação de portão marcada "via gate <workflow>".
Passo 6. Aprove a mudança exata
Um revisor lê lanes.export, um único diff unificado encabeçado por # composition: <hash>, e então chama lanes.approve. A aprovação se liga a esse hash, então "a reviewer who reads the export and approves at its # composition: value has approved exactly that change." (um revisor que lê a exportação e aprova no valor # composition: dela aprovou exatamente essa mudança). Qualquer patch, resolução ou movimento do trunk posterior que mude o que seria integrado muda o hash, e as aprovações anteriores deixam de contar. Aprove depois da última mudança, não antes.
Passo 7. Deixe o workflow do AEGIS aprovar como portão
Um portão só é satisfeito pelo próprio workflow. O token da execução é emitido com tokens.mint_execution e o argumento opcional workflow com o nome do portão, de 1 a 128 caracteres; a execução então chama lanes.approve com esse token. A correspondência é exata, "case included" (incluindo maiúsculas e minúsculas). "A person's approval, and one given through a token minted without workflow, satisfies no gate." (A aprovação de uma pessoa, e uma dada com um token emitido sem workflow, não satisfazem portão nenhum.) O token de execução é filho do token do chamador, limitado a um workspace, um caminho de árvore, uma lane, uma lista de ferramentas e no máximo um dia. Com o AEGIS by 100monkeys.ai, in beta, o portão é um workflow seu: a linha o nomeia, e o Carbon Forge só confere que uma execução dele aprovou.
Passo 8. Integre
lanes.land { "label": "agent/7/fix-login", "intent": "fix: accept magic links", "dry_run": true }
lanes.land { "label": "agent/7/fix-login", "intent": "fix: accept magic links" }Uma integração sem as aprovações necessárias é recusada inteira, dizendo o que falta:
Lane <label> touches <path> under landing rule <glob> (line <n>), which needs approval from <user ids> and gate <name> at the lane's current composition. Approve with lanes.approve; nothing was written.Quando ela integra, as aprovações que consumiu, a do portão incluída, "follow its intent as Approved-by: lines" (seguem a intenção como linhas Approved-by:), e o changeset é selado como qualquer outro. Atenção: uma integração com dry_run não confere as regras; para isso, leia lanes.get.
O que a documentação deixa sem resposta
- O lado do AEGIS. A documentação diz que "the execution service" (o serviço de execução) emite o token da execução com
workflow, mas não mostra um workflow do AEGIS que tenha esse token e chamelanes.approve. - Aprovadores são só ids de usuário. Não há grupos nem times, e o design diz "No per-directory permissions" (sem permissões por diretório).
- Se uma aprovação dada com um token de execução também conta para o usuário do token quando esse usuário é um aprovador da lista.