Archivos de bloqueo de GitHub Actions: tu primera PR

Adopta un archivo de bloqueo de GitHub Actions mediante un cambio en un solo flujo de trabajo que tu equipo pueda explicar y revisar. Comprueba qué commits de las acciones registra, aplica controles propios a las entradas que quedan fuera y asigna a alguien la revisión de futuras actualizaciones. El primer resultado útil es una PR que delimite la cobertura e incluya una ejecución correcta de la revisión examinada.

Puede parecer un objetivo modesto frente a una mejora de seguridad para todo el repositorio. Pero es una tarea que un equipo pequeño puede terminar. Un archivo generado resulta útil cuando quienes lo revisan entienden qué código ejecutable han aprobado y qué puede seguir cambiando a su alrededor.

GitHub declaró los archivos de bloqueo de flujos de trabajo disponibles con carácter general el 28 de octubre para los planes Free, Team y Enterprise Cloud que enumera, incluido Enterprise Cloud con residencia de datos. La guía del 11 de noviembre de Hugo van Kemenade renovó el interés por adoptarlos. Para tu equipo, la cuestión es cómo incorporar ese control sin perder de vista el resto del flujo de trabajo.

Qué apruebas al bloquear las dependencias de un flujo de trabajo

Un archivo de bloqueo registra los commits de las acciones que debe ejecutar un flujo de trabajo ya incorporado, incluidas sus dependencias transitivas de otras acciones. Según la referencia conceptual de GitHub, el ejecutor aplica esa resolución, comprueba la identidad del repositorio de origen y rechaza un commit registrado al que no se pueda llegar desde la referencia de origen registrada.

Así tienes un conjunto concreto de dependencias que aprobar. La referencia visible de una acción puede ser fácil de leer, pero su ejecución puede recurrir a otras acciones. Al incluir esas dependencias en el registro, quienes revisan el cambio pueden ver mejor qué código entrará en la ejecución.

Aprobarlo sigue exigiendo criterio. El commit registrado podría contener código que lea más archivos, contacte con un servicio nuevo o use privilegios que tu flujo de trabajo nunca debería haber concedido. Un archivo de bloqueo puede conservar fielmente esa elección. Por eso sigue siendo pertinente la guía de uso seguro de GitHub: revisa el código de las acciones, limita los permisos de los tokens y trata con cuidado el contenido no fiable de las PR.

Mantén dos preguntas en la revisión: «¿Usará esta ejecución el código de las acciones registrado?» y «¿Deberíamos permitir que ese código se ejecute aquí?» El bloqueo ayuda a responder a la primera. La segunda depende del código, del evento que inicia la ejecución, del ejecutor y de los permisos a su disposición.

Acota la primera PR para que se pueda entender

Imagina una startup de cuatro personas con un flujo de pruebas, otro de despliegue, un flujo reutilizable compartido y un paso de Docker. Es un ejemplo hipotético de adopción. Empieza por el flujo cuyo propósito, entradas y resultados esperados pueda explicar su responsable. Para este equipo, supongamos que es el flujo de pruebas.

Antes de generar nada, describe en la PR su secuencia de ejecución actual. Indica qué evento lo inicia, de dónde procede el código obtenido, qué puede hacer el token, qué secretos están disponibles y qué ejecutor lo procesa. Si colaboradores externos pueden iniciarlo, ten en cuenta su código como entrada. Incluso un trabajo de pruebas aparentemente rutinario puede atravesar un límite de confianza delicado.

La guía de incorporación de GitHub permite limitar la generación a un solo flujo de trabajo. Aprovecha esa opción para que el primer cambio se pueda revisar. Sigue la guía vigente para instalar y generar el archivo; después, examina tanto las modificaciones del flujo como actions.lock.

Presta especial atención a las acciones locales. Una referencia ./ usa el contenido del espacio de trabajo obtenido del repositorio. Migrarla a $/ hace que la referencia apunte al commit del propio flujo de trabajo. Esto puede cambiar el comportamiento si la revisión del flujo y la revisión obtenida son distintas. Comprueba expresamente qué origen se pretende usar antes de aceptar la modificación; una dependencia local sin resolver merece investigarse.

Tu primera PR debe incluir pruebas suficientes para que un compañero pueda decidir:

1. Alcance: el flujo que se incorpora y los que quedan para más adelante.
2. Resolución: los cambios de dependencias generados, incluidas las acciones transitivas.
3. Comportamiento: cualquier migración de referencias locales u otra modificación del flujo.
4. Validación: el método de verificación y una ejecución correcta del flujo en la revisión examinada.
5. Excepciones: las entradas ejecutables que el archivo de bloqueo deja fuera, con un responsable y una decisión para cada una.

Una ejecución de pruebas en verde indica que la ejecución observada terminó correctamente. Lee también la salida de los trabajos pertinentes: ¿se ejecutaron las pruebas previstas, aparecieron los archivos de salida esperados y algún paso empezó a seguir una ruta distinta? Guarda el enlace a esa ejecución junto al diff para que quien revise pueda examinar ambos.

Revisa las entradas que quedan fuera del archivo de bloqueo

Los límites del archivo de bloqueo cobran especial importancia cuando tu flujo llama a otro componente. El README oficial de la CLI documenta limitaciones como las llamadas a flujos reutilizables externos y las imágenes de contenedores. Tu primera PR necesita un breve registro de cómo se controlan esas entradas.

Los flujos reutilizables requieren especial cuidado. La referencia conceptual de GitHub explica que el archivo de bloqueo del flujo que llama no fija las llamadas de jobs.<job_id>.uses a un commit. Para fijar una llamada a un flujo reutilizable, indica el SHA completo del commit. Las dependencias de acciones dentro del flujo llamado pertenecen al archivo de bloqueo de ese repositorio. Examinar solo el archivo generado del repositorio que hace la llamada no permite determinar la cobertura dentro del repositorio llamado.

La startup del ejemplo puede usar esta tabla en la PR del flujo de pruebas. Sustituye las responsabilidades del ejemplo por nombres reales antes de la revisión.

La fila de la herramienta descargada se deduce de leer lo que ejecuta la consola. Un comando puede obtener código ejecutable más allá de las referencias de acciones registradas en el archivo de bloqueo. Examina esa ruta y decide cómo identificará y revisará tu equipo el archivo obtenido. Trata cualquier entrada sin resolver como una excepción explícita que exige una decisión.

Revisa también por separado los permisos de ejecución. Las imágenes de los ejecutores, las entradas y las credenciales siguen siendo elementos distintos de la resolución de acciones registrada. Nuestra lista de comprobación de acceso para entornos aislados de agentes desarrolla esa pregunta más amplia: ¿qué puede leer o modificar una ejecución y con qué puede comunicarse? Plantéala también en la integración continua, sin dar por hecho que un archivo de dependencias la resuelve.

Asigna un responsable a la próxima actualización de dependencias

La siguiente actualización convierte la decisión de adoptar el bloqueo en una práctica de mantenimiento. Deja por escrito quién revisa los cambios del archivo de bloqueo, qué pruebas necesita y cómo se incorpora un nuevo flujo de trabajo.

La guía de aplicación de políticas de GitHub recomienda una prueba piloto antes de exigir el bloqueo de forma más amplia. Dependabot mantiene las entradas de los flujos ya incorporados; no incorpora automáticamente los nuevos. Incluye ese paso en la lista de revisión de un flujo nuevo, en lugar de suponer que el bot de actualizaciones lo detectará y completará.

Elige la verificación según lo que quieras comprobar. La referencia de la CLI distingue la comprobación de cobertura sin conexión con --verify-local de las comprobaciones de procedencia en línea con --verify. Registra cuál se ha ejecutado e investiga los fallos antes de ampliar la cobertura. Una comprobación local de cobertura correcta y una comprobación de procedencia en línea aportan pruebas distintas.

La CLI también documenta una limitación que conviene recordar al revisar: no se detecta que una referencia móvil retroceda dentro de su historial. Examina el cambio real de la dependencia aunque la verificación termine correctamente. Pregunta qué código ha cambiado, si ha cambiado su comportamiento o los permisos necesarios y si la revisión elegida es la que quieres aprobar.

Si tu organización usa modos de aplicación gradual de políticas, comprueba su disponibilidad antes de prometer un proceso concreto. GitHub sitúa el modo Evaluate en Enterprise Cloud. Un equipo sin ese modo puede empezar igualmente con un flujo revisado y una comprobación de verificación obligatoria.

Amplía la adopción cuando el responsable pueda explicar la cobertura, las excepciones y el proceso de actualización de la prueba piloto. Decide por separado cómo incorporar el flujo de despliegue, porque tiene consecuencias distintas y puede recibir otras credenciales.

Guarda las pruebas de verificación junto al informe de un problema de CI

La adopción rutinaria de archivos de bloqueo corresponde a una PR de ingeniería. Si el trabajo parte de un informe de vulnerabilidad, vincula el hallazgo con esa PR y sus pruebas de verificación. Registra qué quedó expuesto, qué cambió, qué revisión se comprobó y qué sigue sin resolverse.

Es una tarea distinta de reconstruir un incidente. Nuestra guía sobre repositorios comprometidos y límites de publicación explica cómo determinar si el código sospechoso llegó a una versión publicada o a sus usuarios. Consúltala cuando surjan esas preguntas; completar esta tabla de adopción no permite determinar la exposición pasada.

El flujo de Seguridad de Kit permite reunir la asignación de un informe, las pruebas de ingeniería enlazadas y la decisión humana de verificación. Su ciclo de vida distingue la resolución de la verificación de la corrección, y quien verifica puede añadir una nota. Tu equipo de ingeniería sigue siendo quien genera el archivo de bloqueo, examina el flujo y decide si la corrección funciona. Kit no realiza esa evaluación ni exige pruebas documentales en cada verificación.

Para tu primera PR, elige un flujo, revisa los cambios ejecutables, identifica las entradas que quedan fuera y asigna la siguiente actualización. Si el trabajo lo ha motivado un informe de seguridad, añade las referencias de la PR y de la ejecución junto a él. Deja a quien revise después pruebas suficientes para entender exactamente qué aprobó el equipo.