El kadu.yaml

Lo que es de toda la organización, y no de una tarea, vive en un kadu.yaml opcional en la raíz del repositorio: entornos, webhooks y el metadata de workspaces y actividades. Lo que es de una tarea (programación, endpoint, ejecutor) queda en el bloque task:.

Las reglas que valen para todas las secciones

• Propiedad. La sincronización crea y actualiza lo declarado y solo borra lo que ella misma creó. Lo que se creó en la consola y aparece en el archivo se actualiza, nunca se borra.
• Una sección ausente no toca nada. Una lista vacía ([]) quita solo lo que creó el repositorio.
• El archivo se valida completo. YAML roto, campo con tipo incorrecto, clave desconocida (colour:, bearer_token:), evento de webhook fuera de la lista o elemento repetido hacen que la sincronización no aplique nada del archivo, con un aviso. Una sección desconocida en el nivel superior es solo un aviso, y el resto vale.

El todo o nada es a propósito: aplicar la mitad buena borraría el elemento con error de tipeo.

Entornos

environments:
  - label: Produção
    color: "#16a34a"          # #rrggbb; ausente = gris (#6b7280) al crear
    branch: main              # ausente = main al crear
    secrets:                  # solo las CLAVES — el valor nunca entra al repositorio
      - KOBANA_ACCESS_TOKEN
      - key: FINTERA_TOKEN
        notes: token da entidade 34684
  - label: Sandbox
    color: "#f59e0b"

Situación	Qué hace la sincronización
Entorno declarado que no existe	lo crea, marcado como del repositorio
Entorno declarado que ya existe (mismo nombre)	actualiza color y branch, si están declarados. El creado en la consola se adopta para actualización, nunca se marca como del repositorio
Clave en secrets sin valor en el entorno	aviso: la sincronización nunca crea un secret
Clave en secrets con notes	sobrescribe la nota del secret
Entorno del repositorio que salió de la lista	lo borra, salvo que aún tenga un secret o una programación (queda, con un aviso)
Entorno de la consola que salió de la lista	no lo toca

El nombre es la clave: renombrar un entorno en el archivo es crear otro. Las programaciones que apuntan a él deben cambiar en el frontmatter en el mismo commit. Para renombrar un entorno que ya tiene secrets, renómbralo en la consola y después en el archivo.

Webhooks

webhooks:
  - label: Falhas para o PagerDuty   # la clave: emparejado por el nombre
    url: https://events.exemplo.com/kadu
    events: [execution.failed, organization.cost_limit_reached]
    workspace: finance        # plugin del alcance; null = toda la organización; ausente = no toca
    auth: header              # basic | bearer | header; ausente = bearer al crear
    header_key: X-Api-Key     # la parte no secreta (en basic: basic_user)
    enabled: true             # ausente = no toca (al crear: activo)
    emails: [ops@exemplo.com] # avisados cuando el webhook se desactiva por fallas
    metadata: { dono: sre }

Eventos aceptados: execution.created, execution.queued, execution.started, execution.completed, execution.failed, execution.cancelled, todo.created, todo.resolved, organization.cost_limit_reached, organization.entitlement_required y los <recurso>.db.created|updated|deleted de task, activity, workspace, execution y memory.

La credencial nunca entra al archivo. bearer_token, la contraseña del basic o el valor del header en el YAML son claves desconocidas e invalidan todo el archivo.

Situación	Qué hace la sincronización
Webhook declarado que no existe	lo crea, marcado como del repositorio, sin credencial y con un signing secret que nadie vio, y avisa
Webhook existente (mismo nombre, cualquier origen)	actualiza url, events, emails (el orden no cuenta), alcance, basic_user/header_key y metadata
auth distinto del guardado	no lo cambia (borraría la credencial) y avisa; cámbialo en la consola
enabled: true en un webhook desactivado por fallas	lo reactiva y reinicia el contador de fallas, en cada sincronización, mientras esté declarado
URL rechazada (IP privada, http), workspace inexistente, dos webhooks con el mismo nombre	omite ese webhook, con un aviso, sin borrarlo
Webhook del repositorio fuera de la lista	lo borra
Webhook de la consola fuera de la lista	no lo toca

Después de crearlo, faltan dos pasos fuera del repositorio: registrar la credencial en Configuración → Webhooks y generar el signing secret con POST /v1/webhooks/{id}/rotate-secret, configurando el nuevo valor en el receptor. Hasta entonces, la entrega sale sin autenticación y con una firma que el receptor no puede verificar.

Workspaces y actividades

workspaces:
  - plugin: finance                    # el plugin = el workspace
    metadata: { centro_de_custo: "42" }
    activities:
      - label: Baixa de Recebimentos   # nombre exacto dentro del workspace
        metadata: { sla_horas: 4 }

Solo el metadata, que aparece en la API v1 y en el payload de los webhooks, reemplazado por completo cuando está declarado. El archivo no crea workspaces ni actividades (nacen de las tareas), así que un plugin o nombre que no existe se convierte en un aviso.

Orden de aplicación

Tareas → entornos → programaciones → metadatos de workspaces y actividades → webhooks → eliminación de entornos del repositorio. Ver Sincronización.