Automatizaciones.

Una automatización es un run de agente que configuras una vez y lanzas tantas veces como necesites: el workspace, el agente, las instrucciones, la carpeta, los secretos que recibe y qué puede lanzarla. Cada vez que arranca, crea un run en tu workspace con esos ajustes.

Qué puede lanzar una automatización:

• Tú, con Run now en el portal, nan automations run en la terminal o una llamada a la API.
• Un webhook: GitHub, Stripe o cualquier sistema que pueda firmar una petición. Consulta Webhooks y programaciones.
• Una programación: cada día laborable a las 9:00, cada hora, el día 1 de cada mes. También en Webhooks y programaciones.

El agente de una automatización no hace push ni publica nada por su cuenta. Propone acciones (hacer push de una rama, abrir una pull request, comentar, revisar, añadir etiquetas) y NaN las aplica con un token que guardas aparte del agente. Tú decides qué tipos de acción esperan tu aprobación y cuáles se aplican solas: todas, ninguna o cualquier combinación.

Antes de empezar

• Un workspace encendido, con Pi o Hermes instalado, como para cualquier run.
• Un plan con inferencia. Los runs de una automatización usan la clave de inferencia de tu workspace y cuentan para el uso de tu plan como cualquier otro run.
• Una sesión en el navegador. Crear o cambiar automatizaciones, escribir secretos y aprobar acciones exige que hayas iniciado sesión en cloud.nan.builders desde tu navegador, con el enlace por correo. Una sesión de la CLI, una API key o un token pueden listar automatizaciones y lanzarlas, pero nunca cambiarlas. Consulta Por qué algunas acciones necesitan el navegador.
• Para las plantillas de GitHub, un token de GitHub guardado como secreto. Sin él la automatización no se puede guardar, así que créalo antes: consulta Un token de GitHub para las acciones.

Crea una automatización

Cada automatización tiene cuatro pestañas: Settings, Triggers, Runs (sus runs, del más reciente al más antiguo) y Deliveries (los webhooks que ha recibido). Run now y Delete están arriba.

Secretos

Los secretos son los tokens y claves que usan tus automatizaciones: un token de GitHub, una API key de algún servicio tuyo. Los guardas en tus ajustes y los asignas a las automatizaciones que los necesitan.

Añade un secreto

Abre tus ajustes en el portal, Secrets, debajo de Tokens, y pulsa Add secret:

• Name: el nombre de la variable que ven tus automatizaciones, en mayúsculas, dígitos y _, empezando por una letra. Por ejemplo GITHUB_TOKEN. Hasta 64 caracteres.
• Value: se guarda tal cual lo pegas, hasta 16 KiB. Los saltos de línea dentro del valor están bien (una clave PEM, por ejemplo), pero no al principio ni al final.
• Description, opcional.

Los secretos son de solo escritura: una vez guardados, nadie puede volver a leer el valor, ni siquiera tú. La lista muestra el nombre, los 4 últimos caracteres cuando el valor es lo bastante largo, la descripción y qué automatizaciones usan cada uno. Puedes:

• Replace value: el valor nuevo lo usan todos los runs que arranquen a partir de ese momento, incluidos los que ya están en cola. El anterior no se puede recuperar.
• Cambiar su Description.
• Delete. El borrado se rechaza mientras una automatización lo use: quítalo antes de esas automatizaciones.

Puedes guardar hasta 100 secretos. Mejor tokens de vida corta, limitados a lo que necesita la automatización.

Asigna secretos a una automatización

En la tarjeta Secrets de la automatización, Add a secret y elige, para cada uno:

• El secreto, por su nombre.
• El nombre de la variable con el que lo ve el run. Puede ser distinto del nombre del secreto, y no puede ser un nombre que fije el propio entorno de ejecución: OPENAI_API_KEY, OPENAI_BASE_URL, HOME, USER, PATH, LANG, CREDENTIALS_DIRECTORY ni nada que empiece por NAN_, PI_ o HERMES_.
• Quién lo recibe:

El mismo nombre de variable puede aparecer una vez por opción. La configuración habitual de GitHub le da al agente un token de solo lectura y a las acciones un token de escritura, los dos como GITHUB_TOKEN.

Una automatización admite hasta 20 secretos, y todos los secretos que recibe un run pueden sumar como mucho 48 KiB. Los secretos solo llegan a los runs de las automatizaciones a las que los asignas: un run que lanzas con nan run o desde la pestaña Runs de un workspace no recibe ninguno.

En los logs, resultados y propuestas de los runs, todos los valores de los secretos aparecen enmascarados. Un run solo arranca si todos los secretos que necesita están disponibles; si no, falla con secrets_unavailable y nada se ejecuta sin ellos.

Un token de GitHub para las acciones

Para actuar sobre un repositorio, una automatización necesita:

1. Su GitHub repository puesto a owner/name.
2. Un secreto asignado como GITHUB_TOKEN con Actions only (write access). Sin él, la automatización no se puede guardar.

Crea un fine-grained personal access token limitado a ese único repositorio, con los permisos que necesitan las acciones: Contents de lectura y escritura para hacer push, Pull requests de lectura y escritura para abrir, comentar y revisar pull requests, e Issues de lectura y escritura para comentar en issues y añadir etiquetas. Guárdalo en Secrets, por ejemplo como GITHUB_WRITE_TOKEN, y asígnalo a la automatización como GITHUB_TOKEN, Actions only.

Si un push puede cambiar archivos dentro de .github/workflows/ (la plantilla CI failure puede hacerlo), el token de escritura también necesita Workflows de lectura y escritura.

Si el agente también necesita leer el repositorio (uno privado, o para traer logs de CI), crea un segundo token solo con permisos de lectura (Contents, Pull requests, Issues, y Actions para los logs de CI) y asígnalo como GITHUB_TOKEN, Agent.

Acciones y aprobación

Cómo actúa una automatización

El agente de una automatización trabaja como en cualquier run: lee el código, ejecuta comandos y hace commits en su carpeta. Cuando quiere actuar sobre el repositorio, en lugar de actuar escribe una propuesta:

Hasta 10 acciones por propuesta, siempre sobre el GitHub repository de la automatización. Las plantillas ya le dicen al agente cómo escribir la propuesta; con From scratch, el agente lo aprende de esas mismas instrucciones, que el run añade por ti.

Después, un paso aparte, sin agente y sin ningún modelo de IA, aplica las acciones con tu token Actions only. El agente nunca ve ese token. Un run que no propone nada simplemente termina como succeeded.

Todo lo que hace NaN va marcado: los commits que sube llevan una línea Nan-Run: <run id>, los comentarios, reviews y pull requests terminan con una marca oculta, y las ramas aparte en las que trabajan los runs empiezan por nan-run/ (el push en sí va a la rama que indica la propuesta). El autor de un commit subido es NaN run <run@nan.builders>.

Un push nunca lleva la clave de inferencia de tu workspace: una propuesta cuyos cambios la contengan se rechaza (proposal_invalid), necesite aprobación o no. Tus propios secretos son cosa tuya: si un diff contiene el valor de un secreto que recibe ese run, el portal te avisa antes de aprobar.

Elige qué espera tu aprobación

La tarjeta Approval de una automatización tiene tres opciones:

• Approve everything: todas las acciones esperan tu aprobación. Las plantillas empiezan con esta.
• Fully automatic: las acciones se aplican sin preguntar, push y pull requests incluidos.
• Custom: marca qué tipos de acción necesitan aprobación. Las demás se aplican solas.

Cuando algo de fuera (un webhook o una programación) puede lanzar una automatización que aplica alguna acción sin preguntar, el editor muestra un aviso. Nunca te impide guardar: lo que pasa en tu repositorio es decisión tuya.

Proposals expire after (aparece cuando al menos un tipo de acción necesita aprobación): cuánto tiempo te espera una propuesta: 1 hour, 24 hours, 72 hours (por defecto) o 7 days.

La aprobación controla lo que NaN hace con tus secretos Actions only. El agente en sí se ejecuta en tu workspace y puede usar cualquier cosa que tengas ahí, como una clave SSH o una sesión de gh.

Aprueba o rechaza una propuesta

Cuando una propuesta te necesita, el run se para en awaiting approval (awaiting_approval) y la pestaña Needs approval de Automations la muestra, con un contador junto a Automations en la barra lateral.

Si nadie decide antes de que caduque, la propuesta se descarta y el run termina como cancelled.

Las acciones las aplica un run de aplicación aparte: aparece en la pestaña Runs del workspace, sin agente y sin gastar inferencia, y su log muestra cada acción cuando empieza y cuando termina. El run propio de la automatización termina en cuanto su propuesta queda resuelta, antes de que se apliquen las acciones:

Así que succeeded significa que la propuesta se aceptó, no que todas las acciones funcionaran: revisa el run de aplicación. Si una acción falla, el run de aplicación termina como failed (action_failed) y las acciones siguientes no se aplican.

La aprobación empieza en la primera acción que la necesita. Las acciones anteriores se aplican solas mientras la propuesta espera tu aprobación (si una de ellas falla, el run de la automatización falla con action_failed y no queda nada que aprobar), y en cuanto apruebas, el resto se aplica en orden, incluidas las acciones posteriores que por sí solas no necesitarían aprobación: una pull request necesita que antes se haya hecho push de su rama.

Cuando ya hay un run activo

When a run is active decide qué pasa si llega un evento nuevo sobre lo mismo mientras sigue en marcha un run para ello, incluido un run que espera tu aprobación:

• Skip the new event: se descarta. Las plantillas de GitHub usan esta opción, así que hacer push de tres commits seguidos a una pull request no lanza tres reviews.
• Queue it: se pone en cola un run nuevo, como siempre. La plantilla Generic webhook usa esta opción.

Qué cuenta como “lo mismo” depende de qué lanzó el run:

Los runs que lanzas tú nunca se descartan.

Lánzala ahora

Desde el portal

Run now, arriba en la automatización, abre una caja para el campo opcional Input (JSON object, optional): un objeto JSON (hasta 48 KiB) que el agente recibe como datos junto a tus instrucciones, nunca como instrucciones. Start run te lleva a la página del run.

Desde la terminal

Necesitas la CLI de NaN 0.1.26 o posterior.

nan automations ls                          # tus automatizaciones
nan automations show "PR review"            # ajustes, secretos (solo nombres) y triggers
nan automations run "PR review" --input '{"pr": 42}'
nan automations run nightly-triage --detach
gh api repos/acme/api/pulls/42 | nan automations run "PR review" --input -
nan automations deliveries "PR review"      # webhooks recibidos, últimos 30 días

--input acepta el propio JSON, @file.json o - para stdin. No pongas secretos en él: el agente lo lee. Una automatización se indica por su nombre o por su id; con un nombre, la CLI la busca primero, y eso exige el scope automations:read en un token.

Los comandos de aprobaciones y secretos:

nan approvals ls                  # propuestas pendientes de tu aprobación
nan runs proposal <run-id>        # las acciones propuestas, y dónde aprobarlas
nan runs proposal <run-id> --diff # con el diff completo, cuando se guarda
nan runs reject <run-id> --reason "not now"
nan secrets ls                    # nombres y metadatos, nunca valores

nan run, nan runs logs -f y nan automations run salen con código 10 cuando el run se para esperando aprobación, e imprimen los comandos para leer y rechazar la propuesta y el enlace para aprobarla.

No hay ningún comando para crear o cambiar automatizaciones, escribir secretos o aprobar: la CLI te dice dónde hacerlo en el portal. nan secrets ls necesita tu sesión de nan auth login; el resto de comandos también aceptan un token de plataforma, igual que nan run (Autenticación).

Desde la API

La API usa el id de la automatización: está en la dirección de su página (cloud.nan.builders/automations/<id>), en nan automations ls y en GET /v1/automations. Con un token de plataforma que tenga el scope automations:run, o con tu API key:

curl https://api.nan.builders/v1/automations/$AUTOMATION_ID/runs \
  -H "Authorization: Bearer $NAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"pr": 42}}'

La respuesta es el run, que sigues como cualquier otro (Crea un run y síguelo). La referencia completa está en Referencia de la API → Automations y Referencia de la API → Approvals.

Tokens para automatizaciones

Un token de plataforma lleva scopes: lo que puede hacer. Los eliges al crearlo, en Settings → Tokens:

Los tokens nuevos llevan runs y workspaces:read por defecto. Un token con automations:read o automations:run solo se puede crear desde una sesión en el navegador. Un token sin el scope que necesita un endpoint recibe 403 token_scope_denied.

Para CI, dale al token automations:run y runs (para seguir el run y conocer su resultado), y además automations:read si llamas a la automatización por su nombre. Por ejemplo: nan automations run <id> en un paso con NAN_TOKEN definido, como en Usa la CLI en CI o en un servidor.

Límites

Los runs de las automatizaciones comparten los límites de todos los runs: cuántos trabajan a la vez en cada workspace, como mucho 5 a la vez entre todos tus workspaces (8 con Premium), y la cola. Consulta Cuántos runs a la vez. Las automatizaciones necesitan un plan con inferencia: sin él, el portal te enseña las opciones para mejorarlo y los webhooks se responden sin lanzar ningún run.

Cambia o borra una automatización

Cambia cualquier ajuste en la pestaña Settings y pulsa Save changes. Un run conserva los ajustes con los que arrancó: editar una automatización nunca cambia un run que ya está en cola o trabajando.

Al borrarla con Delete, sus triggers se detienen al momento y se cancelan sus runs en cola. Los runs que ya están trabajando terminan, y las acciones que ya aprobaste, o que se aplican solas, se completan igualmente. Los runs pasados se quedan en el historial del workspace, y un run que ya espera tu aprobación todavía se puede aprobar o rechazar.

Por qué algunas acciones necesitan el navegador

Una automatización decide cuáles de tus secretos recibe un agente y qué puede hacer en tu repositorio sin preguntar. Si cualquier cosa capaz de leer una sesión de la CLI o un token pudiera cambiarla, también podría hacerlo un agente en un workspace o un job de CI. Por eso estas acciones te necesitan a ti, con sesión iniciada en el navegador:

• Crear, cambiar o borrar una automatización o sus triggers.
• Añadir, reemplazar o borrar secretos.
• Aprobar una propuesta.
• Crear un token con automations:read o automations:run.

Rechazar siempre es seguro, así que cualquier credencial que pueda leer tus runs puede rechazar. Si el portal te dice que tienes que volver a iniciar sesión, cierra sesión y entra con el enlace por correo desde el mismo navegador.

Preguntas frecuentes