CI: reglas de confianza¶

Una regla de confianza 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 el token, busca la regla de confianza del repositorio y, si coincide, responde una sola vez con la credencial del bot y su kubeconfig. Qué se verifica exactamente está en Modelo de seguridad.

Ese token es de GitHub Actions y no tiene nada que ver con el login con OIDC, con el que las personas entran por el proveedor de identidad de tu empresa: las reglas de confianza funcionan igual con cualquiera de los dos logins, o sin ninguno.

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; su fila dice «token de CI · run 1234 · alice». 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 regla de confianza¶

1. En «CI», pulsa «Nueva regla de confianza». El formulario se abre en un panel a la derecha (desde la ficha de un bot, la tarjeta «Reglas de CI» tiene el mismo botón con el bot ya elegido); rellénalo:

   Campo	Qué poner
   «Repositorio»	propietario/repositorio, por ejemplo acme/app. Con la GitHub App (Login con GitHub), kubelatch pide a GitHub los ids numéricos del repositorio y de su propietario y guarda el nombre actual del repositorio. Para un repositorio que la App no ve, da tú los ids (más abajo).
   «Condición»	Qué tiene que ser la ref del workflow: «Rama…» (escribe main: la regla guarda refs/heads/main), «Tag…» (v1.0 es refs/tags/v1.0), «Cualquier workflow» (sin ref) u «Otra ref…» (una ref completa, como refs/heads/main).
   «Entorno (opcional)»	El entorno de GitHub, por ejemplo prod.
   «Bot»	El bot cuya credencial recibirá el workflow. Solo salen los habilitados, cada uno con lo que tiene; bajo el campo, «El workflow obtiene:» lo repite, por ejemplo viewer en kind-local.
   «Nombre»	Un nombre para reconocerla, por ejemplo deploy de la app.

2. Lee los avisos bajo el campo al que se refieren: la ref que falta bajo «Cualquier workflow», pull_request_target bajo una rama, y el entorno sin protección bajo «Entorno (opcional)». Pulsa «Crear regla».

3. El panel pasa a «Conecta el workflow» (El lado del workflow). Pulsa «Hecho» cuando hayas copiado el fragmento.

Sin la GitHub App, kubelatch no puede preguntar a GitHub, así que le das tú los ids. Con la App también puedes darlos, para un repositorio que no ve (uno privado fuera de su instalación, o de una organización donde no está instalada). 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'

y pulsa «Ya tengo los ids», bajo «Repositorio»: «ID del propietario» es el primer número (repository_owner_id) y «ID del repositorio» el segundo (repository_id). El formulario enseña ese comando gh en «Comando que da los ids», ya relleno con el repositorio que escribiste. Sin la App, ese nombre es opcional y solo da título a la regla. Con la App, «Repositorio» pasa a ser opcional también y el nombre solo rellena el comando: kubelatch no pregunta a GitHub, confía en el repositorio solo por esos ids, y la regla se lista por ellos, como owner_id / repo_id, sin nombre.

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 entorno. Si GitHub no conoce el repositorio, o la App no lo ve (en uno privado, la instalación de la App debe incluirlo), o cambió de nombre o de dueño, el panel lo dice y conserva lo que escribiste.

Cómo se elige la regla¶

«Cualquier workflow» deja la ref vacía, y un «Entorno (opcional)» vacío deja vacío el entorno: la regla vale entonces para cualquier ref, o cualquier entorno, del repositorio. Con ellos puestos, solo para esa ref exacta y ese entorno. Si varias coinciden, gana la más específica: una con entorno 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 entorno solo protege si ese entorno 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¶

Tras «Crear regla», el panel pasa a «Conecta el workflow»: un «Fragmento del workflow» relleno para esa regla, con tu URL, el disparador de su rama o tag y su entorno, listo para pegar en el repositorio. «Workflow de ejemplo», en la cabecera de «CI» (y en la lista vacía), tiene el genérico. El ejemplo completo es examples/github-actions/kubelatch.yml, en el repositorio. Lo esencial:

• permissions: id-token: write.
• El paso uses: picaportelabs/kubelatch-action@v1 con url igual a KUBELATCH_BASE_URL: es la audiencia del token.
• Si la regla fija un entorno, el job declara environment: "<nombre>". El fragmento escribe el nombre entre comillas, así que ni unos dos puntos ni un # en él pueden cambiar el entorno que designa.

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, como «token de CI · run … · actor».
4. En «CI», el «Último canje» de la regla deja de decir «Nunca canjeada», el chip «canjeadas hoy» cuenta la regla y la frase de arriba cuenta la credencial.
5. 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.

Leer la lista¶

«CI» lee cada regla como una frase: el repositorio, la condición, el entorno y el bot que entrega, por ejemplo acme/app · refs/heads/main · entorno prod → deploy-bot. Una regla sin ref dice «cualquier workflow» en una etiqueta ámbar. El nombre de la regla va debajo, y «Último canje» dice cuándo canjeó un workflow por última vez un token con ella («Nunca canjeada» hasta que lo hace). Pasa el ratón por el repositorio para leer sus ids numéricos; una regla escrita solo con ids los muestra como 65 / 74. Una frase arriba cuenta las reglas y los bots que entregan, y los tokens de CI emitidos desde medianoche («4 reglas para 2 bots. 12 credenciales canjeadas hoy.»). Dos chips cuentan reglas y filtran la lista: «1 sin ref» (las reglas que aceptan cualquier workflow) y «3 canjeadas hoy» (las reglas con las que un workflow ha canjeado un token desde medianoche); pulsa uno para verlas, pulsa los dos para combinarlos y comparte la dirección de la página, que los conserva. Un chip sin nada que contar no se dibuja. «Filtrar» busca el repositorio o sus ids, la ref, el entorno, el bot y el nombre. El menú de la fila tiene «Peticiones» (las peticiones del bot en «Auditoría»), «Credenciales» (sus tokens de CI) y «Eliminar».

Eliminar una regla¶

En «CI», abre el menú de acciones al final de la fila de la regla, elige «Eliminar» y confirma. 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: «Credenciales», en el menú de la fila de la regla, abre los tokens de CI de ese bot. 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.