CI: trust rules¶

Una trust rule deja que los workflows de GitHub Actions de un repositorio obtengan una credencial de un bot, sin guardar ningún secreto en GitHub. Aquí ves cómo crearla en «CI» y cómo acotarla bien.

Cómo funciona¶

El workflow pide a GitHub un token OIDC con audiencia KUBELATCH_BASE_URL y lo canjea en POST /v1/ci/github-actions/token. kubelatch verifica la firma contra las claves públicas de GitHub, comprueba que el token no se ha canjeado antes y busca la trust rule del repositorio. Si coincide, responde una sola vez con una credencial del bot y su kubeconfig. Los detalles de la verificación (caché de claves, margen de reloj, sub) están en Modelo de seguridad.

sequenceDiagram
  participant W as Workflow
  participant G as GitHub
  participant K as kubelatch
  W->>G: pide token OIDC (audiencia = KUBELATCH_BASE_URL)
  G-->>W: id_token firmado
  W->>K: POST /v1/ci/github-actions/token
  K->>K: verifica firma, aud, jti y trust rule
  K-->>W: credencial del bot + kubeconfig

La credencial dura KUBELATCH_CI_TOKEN_TTL (1 hora por defecto; no puede superar KUBELATCH_MAX_TTL_BOT). Aparece en «Credenciales» con el nombre github-actions y una nota con el repositorio, la ref, el run y el actor. Cada kubectl del workflow queda en la auditoría como bot:<nombre>.

Antes de empezar¶

• Un bot con permisos: créalo en «Usuarios» y concédele un nivel en «Permisos» (Usuarios y bots).
• Los runners llegan a kubelatch por https con un certificado en el que confían. Un kubelatch en un portátil o en una red privada no sirve. Con una CA privada, usa KUBELATCH_KUBECONFIG_CA (Instalar).

Crear una trust rule¶

1. Busca los ids numéricos del repositorio y de su propietario:

   gh api repos/<owner>/<repo> --jq '[.owner.id, .id]'
   # o sin gh:
   curl -s https://api.github.com/repos/<owner>/<repo> | jq '.owner.id, .id'
   

2. En «CI», rellena el formulario:

   Campo	Qué poner
   «Nombre»	Un nombre para reconocerla, por ejemplo deploy de la app.
   «Bot»	El bot cuya credencial recibirá el workflow. Solo salen los habilitados.
   «ID del propietario»	El primer número (repository_owner_id).
   «ID del repositorio»	El segundo número (repository_id).
   «Ref (opcional)»	Una ref completa: refs/heads/main, refs/tags/v1.0.
   «Environment (opcional)»	El environment de GitHub, por ejemplo prod.

3. Pulsa «Crear regla».

kubelatch compara por ids numéricos, no por nombres: los repositorios y las organizaciones se renombran y sus nombres se reciclan. Solo puede haber una regla por repositorio, ref y environment.

Cómo se elige la regla¶

Sin «Ref» ni «Environment», la regla vale para cualquier workflow del repositorio. Con ellos, solo para esa ref exacta y ese environment. Si varias coinciden, gana la más específica: una con environment gana a una con ref, y ambas a la genérica.

Dos límites más:

• No combines una regla con workflows pull_request_target que hagan checkout del código de la PR. Se ejecutan con la ref de la rama base, no con la del código que ejecutan.
• Una regla con environment solo protege si ese environment existe en GitHub con reglas de protección (revisores, política de ramas). Si no existe, GitHub lo crea la primera vez, sin protección.

El lado del workflow¶

«CI» muestra un «Fragmento del workflow» con tu URL, listo para copiar. El ejemplo completo está en examples/github-actions/kubelatch.yml. Lo esencial:

• permissions: id-token: write.
• KUBELATCH_URL igual, letra por letra, a KUBELATCH_BASE_URL: es la audiencia del token.
• Si la regla fija un environment, el job declara environment: <nombre>.

La guía para quien escribe el workflow está en Credenciales para GitHub Actions.

Comprueba que funciona¶

1. Lanza el workflow (workflow_dispatch o un push a la ref de la regla).
2. El job imprime bot:<nombre> en kubectl auth whoami y la lista de pods.
3. En «Credenciales» aparece una credencial github-actions con la nota del run.
4. En «Auditoría», las peticiones tienen como sujeto el bot. En «Plano de control» hay un credential.issue con via: github-actions.

Cada run obtiene un token nuevo: relanzar el job funciona. Si falla, mira Solución de problemas.

Borrar una regla¶

Pulsa «Borrar» en la tabla «Reglas». Los workflows de ese repositorio dejan de obtener credenciales, pero las ya emitidas siguen valiendo hasta caducar (menos de KUBELATCH_CI_TOKEN_TTL). Revócalas en «Credenciales» si hace falta. Deshabilitar el bot sí revoca todas sus credenciales al instante.

GitHub Enterprise Server¶

Apunta KUBELATCH_GITHUB_ACTIONS_ISSUER a https://<servidor>/_services/token. El resto no cambia. Ver Configuración.