Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano
Trasparenza: Carbon Forge, e AEGIS accanto a esso, sono sviluppati da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi li costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica, soprattutto il passo 8 di Working in lanes, Source control settings, MCP tools catalog: Lanes, continued e Source control: how it is built and why, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. La tabella, le chiamate e il rifiuto sono quelli della documentazione stessa, e le citazioni restano in inglese con la traduzione accanto. Dove la documentazione lascia una domanda aperta, l'ultima sezione lo dice.
Perché tenere la regola nel registro
La documentazione dà il motivo in due frasi: "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." (Le regole di landing sono la regola dei code owner tenuta nel registro. Gli approvatori di cui un percorso ha bisogno sono nominati su una pagina del workspace, e ogni approvazione si lega all'hash di composizione della lane, così la revisione appartiene al registro e non a una forge.) Senza questo, "a landing can carry code no approver saw." (un landing può portare codice che nessun approvatore ha visto). Un limite da sapere subito: "Carbon runs no review itself." (Carbon non esegue alcuna revisione da sé.) Registra chi ha approvato cosa; la revisione la fanno le persone e i workflow che nominate.
Passo 1. Proteggete il trunk
Le regole vengono lette solo su un trunk protetto. Un amministratore del workspace spunta Protect the trunk in Settings, Workspace, Source control, e se vuole Protect pages and atoms too. Un agente controlla l'impostazione con:
workspaces.get_settings {}
→ { "workspaceId": "…", "trunkProtected": true, "trunkProtectedEntities": false }Da quel momento "the trunk moves only by a lane's landing" (il trunk si muove solo con il landing di una lane), e una scrittura diretta viene rifiutata con workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.
Passo 2. Scrivete la pagina .landing-rules
Create una pagina al percorso riservato .landing-rules la cui prima tabella Markdown abbia l'intestazione glob | approvers | gate. L'esempio della documentazione:
| glob | approvers | gate |
| --- | --- | --- |
| app/src/billing/** | <user id>, <user id> | |
| docs/** | <user id> | docs-review |glob: una regola con la sintassi delle regole di esclusione dell'importazione, che non inizi con!.approvers: id utente separati da virgole, ciascuno membro del workspace. Può essere vuoto in una riga che nomina un gate.gate: facoltativo, il nome di un workflow AEGIS, al massimo 128 caratteri. "Carbon never runs it." (Carbon non lo esegue mai.)
Solo un amministratore del workspace scrive questa pagina, sul trunk o su una lane; chiunque altro riceve il rifiuto The landing rules page .landing-rules is reserved: only a workspace admin writes it.
Passo 3. Verificate che il server la legga come valida
La sezione Landing rules della finestra delle impostazioni riporta <n> rules, valid., oppure nomina una riga malformata con Every landing is refused until it is fixed. Una riga che nomina un non membro, o che non nomina né un approvatore né un gate, è malformata. Una pagina rotta ferma ogni landing, quindi controllate prima di farci affidamento.
Passo 4. Fate il lavoro su una lane
Aprite una lane e scriveteci come mostra Working in lanes. Al landing, ogni percorso che la lane tocca viene confrontato con ogni riga: una pagina per il suo percorso, una pagina spostata per entrambi i percorsi, un file di albero come <tree path>/<entry path>.
Passo 5. Leggete cosa serve ancora alla lane
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 elenca chi ha approvato, chi manca e se ogni gate è pending o satisfied. Nell'app, la Overview di una lane mostra lo stesso: le regole che corrispondono, approvate n di m, e un'approvazione da gate segnata "via gate <workflow>".
Passo 6. Approvate la modifica esatta
Un revisore legge lanes.export, un unico diff unificato con in testa # composition: <hash>, e poi chiama lanes.approve. L'approvazione si lega a quell'hash, quindi "a reviewer who reads the export and approves at its # composition: value has approved exactly that change." (un revisore che legge l'export e approva al suo valore # composition: ha approvato esattamente quella modifica). Qualsiasi patch, risoluzione o spostamento del trunk successivo che cambi ciò che verrebbe integrato cambia l'hash, e le approvazioni precedenti smettono di contare. Approvate dopo l'ultima modifica, non prima.
Passo 7. Lasciate che il workflow AEGIS approvi come gate
Un gate è soddisfatto solo dal workflow stesso. Il token dell'esecuzione viene emesso con tokens.mint_execution e l'argomento facoltativo workflow con il nome del gate, da 1 a 128 caratteri; l'esecuzione chiama poi lanes.approve con quel token. La corrispondenza è esatta, "case included" (maiuscole e minuscole comprese). "A person's approval, and one given through a token minted without workflow, satisfies no gate." (L'approvazione di una persona, e una data con un token emesso senza workflow, non soddisfano alcun gate.) Il token di esecuzione è figlio del token del chiamante, limitato a un workspace, un percorso di albero, una lane, un elenco di strumenti e al massimo un giorno. Con AEGIS by 100monkeys.ai, in beta, il gate è un vostro workflow: la riga lo nomina, e Carbon Forge controlla solo che una sua esecuzione abbia approvato.
Passo 8. Integrate
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" }Un landing a cui mancano approvazioni viene rifiutato per intero, indicando cosa manca:
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 il landing avviene, le approvazioni che ha consumato, compresa quella del gate, "follow its intent as Approved-by: lines" (seguono la sua intenzione come righe Approved-by:), e il changeset viene sigillato come qualsiasi altro. Attenzione: un landing con dry_run non controlla le regole; per quello, leggete lanes.get.
Cosa la documentazione lascia senza risposta
- Il lato AEGIS. La documentazione dice che "the execution service" (il servizio di esecuzione) emette il token dell'esecuzione con
workflow, ma non mostra un workflow AEGIS che abbia quel token e chiamilanes.approve. - Gli approvatori sono solo id utente. Non ci sono gruppi né team, e il progetto dice "No per-directory permissions" (nessun permesso per directory).
- Se un'approvazione data con un token di esecuzione conta anche per l'utente del token quando quell'utente è un approvatore elencato.