También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: construimos Carbon Forge, y AEGIS a su lado, en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo el paso 8 de Working in lanes, Source control settings, MCP tools catalog: Lanes, continued y Source control: how it is built and why, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. La tabla, las llamadas y el rechazo son los de la propia documentación, y las citas van en inglés con la traducción al lado. Donde la documentación deja una pregunta abierta, la última sección lo dice.

Por qué guardar la regla en el registro

La documentación da el motivo en dos 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." (Las reglas de integración son la regla de code owners guardada en el registro. Los aprobadores que necesita una ruta se nombran en una página del espacio de trabajo, y cada aprobación se liga al hash de composición de la lane, así que la revisión es del registro y no de una forja.) Sin eso, "a landing can carry code no approver saw." (una integración puede llevar código que ningún aprobador vio). Un límite de entrada: "Carbon runs no review itself." (Carbon no hace ninguna revisión por sí mismo.) Registra quién aprobó qué; la revisión la hacen las personas y los workflows que nombras.

Paso 1. Protege el trunk

Las reglas solo se leen en un trunk protegido. Un administrador del espacio de trabajo marca Protect the trunk en Settings, Workspace, Source control, y si quiere Protect pages and atoms too. Un agente comprueba el ajuste con:

workspaces.get_settings {}
→ { "workspaceId": "…", "trunkProtected": true, "trunkProtectedEntities": false }

A partir de ahí "the trunk moves only by a lane's landing" (el trunk solo se mueve por la integración de una lane), y una escritura directa se rechaza con workspace <slug> protects its trunk: the trunk lands by lanes.land only; write on a lane.

Paso 2. Escribe la página .landing-rules

Crea una página en la ruta reservada .landing-rules cuya primera tabla Markdown tenga la cabecera glob | approvers | gate. El ejemplo de la documentación:

| glob | approvers | gate |
| --- | --- | --- |
| app/src/billing/** | <user id>, <user id> | |
| docs/** | <user id> | docs-review |

glob: una regla con la sintaxis de reglas de exclusión de importación, que no empiece por !.
approvers: ids de usuario separados por comas, cada uno miembro del espacio de trabajo. Puede estar vacío en una fila que nombre una puerta.
gate: opcional, el nombre de un workflow de AEGIS, como mucho 128 caracteres. "Carbon never runs it." (Carbon nunca lo ejecuta.)

Solo un administrador del espacio de trabajo escribe esta página, en el trunk o en una lane; cualquier otra persona recibe el rechazo The landing rules page .landing-rules is reserved: only a workspace admin writes it.

Paso 3. Comprueba que el servidor la lee como válida

La sección Landing rules del diálogo de ajustes informa <n> rules, valid., o nombra una fila mal formada con Every landing is refused until it is fixed. Una fila que nombra a alguien que no es miembro, o que no nombra ni un aprobador ni una puerta, está mal formada. Una página rota detiene toda integración, así que compruébalo antes de confiar en ella.

Paso 4. Haz el trabajo en una lane

Abre una lane y escribe en ella como muestra Working in lanes. Al integrar, cada ruta que toca la lane se compara con cada fila: una página por su ruta, una página movida por las dos rutas, un archivo de árbol como <tree path>/<entry path>.

Paso 5. Lee lo que aún necesita la 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 lista quién ha aprobado, quién falta y si cada puerta está pending o satisfied. En la aplicación, el Overview de una lane muestra lo mismo: las reglas con las que coincide, aprobadas n de m, y una aprobación de una puerta marcada "via gate <workflow>".

Paso 6. Aprueba el cambio exacto

Un revisor lee lanes.export, un único diff unificado encabezado por # composition: <hash>, y luego llama a lanes.approve. La aprobación se liga a ese hash, así que "a reviewer who reads the export and approves at its # composition: value has approved exactly that change." (un revisor que lee la exportación y aprueba en su valor # composition: ha aprobado exactamente ese cambio). Cualquier parche, resolución o movimiento del trunk posterior que cambie lo que se integraría cambia el hash, y las aprobaciones anteriores dejan de contar. Aprueba después del último cambio, no antes.

Paso 7. Deja que el workflow de AEGIS apruebe como puerta

Una puerta solo la satisface el propio workflow. El token de la ejecución se emite con tokens.mint_execution y el argumento opcional workflow con el nombre de la puerta, de 1 a 128 caracteres; la ejecución llama entonces a lanes.approve con ese token. La coincidencia es exacta, "case included" (incluidas mayúsculas y minúsculas). "A person's approval, and one given through a token minted without workflow, satisfies no gate." (La aprobación de una persona, y una dada con un token emitido sin workflow, no satisfacen ninguna puerta.) El token de ejecución es hijo del token del llamante, limitado a un espacio de trabajo, una ruta de árbol, una lane, una lista de herramientas y como mucho un día. Con AEGIS by 100monkeys.ai, in beta, la puerta es un workflow tuyo: la fila lo nombra, y Carbon Forge solo comprueba que una ejecución suya aprobó.

Paso 8. Integra

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" }

Una integración a la que le faltan aprobaciones se rechaza entera, nombrando lo 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.

Cuando se integra, las aprobaciones que consumió, incluida la de la puerta, "follow its intent as Approved-by: lines" (siguen a su intención como líneas Approved-by:), y el changeset se sella como cualquier otro. Ojo: una integración con dry_run no comprueba las reglas; para eso, lee lanes.get.

Lo que la documentación deja sin responder

El lado de AEGIS. La documentación dice que "the execution service" (el servicio de ejecución) emite el token de la ejecución con workflow, pero no muestra un workflow de AEGIS que tenga ese token y llame a lanes.approve.
Los aprobadores son solo ids de usuario. No hay grupos ni equipos, y el diseño dice "No per-directory permissions" (sin permisos por directorio).
Si una aprobación dada con un token de ejecución cuenta también para el usuario del token cuando ese usuario es un aprobador de la lista.

Reglas de integración: los code owners guardados en el registro, con un workflow de AEGIS como puerta