El lockfile de GitHub Actions fija el código ejecutado, pero no todo el CI

¿Se puede confiar en GitHub Actions si un workflow hace referencia a una action mediante una etiqueta como @v3? El lockfile especifica qué commit de la action se ejecutará, incluso si la etiqueta se mueve más adelante. El equipo puede revisar las actualizaciones de dependencias en el diff y mantener una lista verificable de las actions utilizadas por CI. Límite práctico: el lockfile cubre las actions invocadas en los pasos, mientras que los workflows reutilizables invocados en el nivel del job deben fijarse por separado. El mecanismo descrito está disponible en GitHub Enterprise Cloud.

¿Qué fija exactamente el lockfile?

Las referencias a ramas y etiquetas son prácticas, pero la versión a la que apuntan puede cambiar. Una entrada como uses: octo-org/deploy-action@v3 indica el nombre de una etiqueta; GitHub resuelve esa referencia a un commit al ejecutar el workflow. Si el propietario del proyecto mueve la etiqueta, la siguiente ejecución podría obtener código distinto si la dependencia no está fijada.

Según la documentación de GitHub sobre lockfiles, el archivo .github/workflows/actions.lock almacena referencias a dependencias y los SHA de los commits correspondientes, incluidas las dependencias transitivas: las actions que utilizan otras actions. El archivo lo crea la extensión de GitHub CLI gh actions-lock; no se edita manualmente.

El generador también puede concretar las referencias uses en los archivos de workflow: por ejemplo, convertir una referencia a una etiqueta flotante en una más específica, conservando el commit al que apuntaba cuando se creó el lockfile. Por eso, al implementarlo, hay que revisar el diff completo —los cambios en el workflow y en el lockfile— y comprobar que la versión fijada sea la que el equipo pretende ejecutar.

Después, las actualizaciones de dependencias pasan a ser cambios visibles en el repositorio: el equipo puede revisar el cambio de commit, debatirlo y aprobarlo mediante el proceso habitual de revisión. El lockfile ayuda a auditar el código de las actions y a mantener la coherencia de las dependencias; por sí solo, no confirma que el código seleccionado sea seguro.

¿Dónde termina el alcance de la fijación?

El lockfile del repositorio que invoca un workflow no fija un workflow reutilizable llamado mediante jobs.<job_id>.uses. Las dependencias de ese workflow reutilizable pertenecen al repositorio donde está definido. Para fijar la propia llamada, hay que especificar el SHA completo del commit; para fijar las actions que utiliza, el repositorio de origen necesita su propio lockfile.

El lockfile controla el código de las actions, pero no otras entradas de compilación, como los parámetros pasados a una action, los secretos o la imagen del runner. Responde a una pregunta concreta: ¿qué commit del código de la action se ejecutará? Estos otros elementos requieren sus propias reglas de gestión.

También hay un caso especial: una action local invocada mediante una ruta como uses: ./. Según las instrucciones de GitHub, la extensión gh actions-lock no fija ni analiza la ruta de una action local. Si esa action utiliza otras actions, sus dependencias deben gestionarse por separado; la documentación describe una opción para migrar las referencias a actions locales al formato $/.

Por tanto, una entrada del lockfile puede formar parte de una cadena, pero no sustituye el control de todos sus eslabones. En el caso de un workflow reutilizable externo, comprueba que la llamada esté fijada y revisa el estado del repositorio de origen; para las actions locales, comprueba cómo se tienen en cuenta sus dependencias.

¿Cómo implantar controles sin detener CI por sorpresa?

GitHub recomienda empezar con un piloto en repositorios y workflows seleccionados. La política Require lockfile bloquea la ejecución de los workflows incluidos en el alcance si no tienen un lockfile válido, incluso si no contienen dependencias uses:. El modo Evaluate para las políticas solo está disponible en GitHub Enterprise Cloud. Por eso, primero prepara el alcance y las actualizaciones automáticas; después, activa la regla obligatoria.

1. Revisa las referencias originales. Antes de crear el lockfile, comprueba que las actions apunten a las versiones que el equipo realmente quiere fijar. El generador fija el commit que resuelve la referencia actual.
2. Crea y revisa el lockfile. Instala la extensión gh-actions-lock, ejecuta gh actions-lock desde la raíz del repositorio y revisa el diff completo, incluidas las referencias uses reescritas.
3. Configura la actualización y la verificación. Dependabot puede actualizar las entradas correspondientes de los workflows ya incorporados. En CI, puedes configurar una tarea de verificación para las solicitudes de cambios con gh actions-lock --verify, a fin de detectar lockfiles obsoletos antes de la compilación principal.
4. Asigna revisores. Añade .github/workflows/actions.lock a CODEOWNERS y exige que las personas responsables de la seguridad de la compilación revisen los cambios.
5. Haz un piloto de la política. Empieza con los repositorios y workflows incorporados. Analiza los resultados en Evaluate; antes de pasar al modo Active, comprueba que todos los workflows incluidos estén preparados y que sus lockfiles sigan actualizados.

Require lockfile y la política independiente Require actions to be pinned to a full-length commit SHA son reglas distintas; GitHub indica que se pueden mantener activas al mismo tiempo. La verificación en CI y la política obligatoria también cumplen funciones diferentes: la primera detecta un archivo obsoleto mientras se trabaja en una solicitud de cambios; la segunda bloquea la ejecución de un workflow que no cumple el requisito.

Ejemplo: actualizar una action de despliegue

Supongamos que un workflow publica una aplicación mediante octo-org/deploy-action@v3. Primero, el equipo comprueba qué versión resuelve esa referencia; luego ejecuta gh actions-lock y revisa el diff del workflow junto con la entrada del commit en el lockfile. Al actualizar la action, quien revisa puede ver los cambios en las referencias y en el commit fijado; así puede evaluar una actualización concreta, en lugar de confiar en que una etiqueta móvil siempre apunte al mismo código.

Si el despliegue se realiza mediante un workflow reutilizable de otro repositorio, el lockfile local no cubre sus dependencias. Fija la referencia al workflow reutilizable con el SHA completo y comprueba que el repositorio de origen gestione sus propias dependencias de actions. En las grandes organizaciones, esto convierte las reglas dispersas en un proceso verificable, sin dejar de controlar por separado los parámetros, los secretos y el runner.

El lockfile es una capa útil para controlar el código de las actions: hace visibles las versiones y sus actualizaciones, incluidas las dependencias transitivas. Para lograr una cobertura fiable, revisa también los workflows reutilizables y las actions locales, automatiza las actualizaciones y aplica la política obligatoria solo después de un piloto.