Para fijar las dependencias de GitHub Actions sin sustituir etiquetas legibles por SHA en cada workflow, instala la extensión gh actions-lock, revisa las referencias actuales y genera .github/workflows/actions.lock. Después incorpora los workflows uno a uno, revisa el commit que queda fijado y añade una comprobación de vigencia. La función está disponible de forma general para GitHub Free, Team, Enterprise Cloud y Enterprise Cloud con residencia de datos.
Un lockfile consigue que una acción se ejecute desde el commit revisado aunque la etiqueta o rama se mueva. También incluye dependencias transitivas. No certifica que el código sea seguro, no fija la imagen del runner, los parámetros ni los secretos y no cubre automáticamente los workflows reutilizables llamados desde otro repositorio.
Requisitos y disponibilidad
- Acceso de escritura al repositorio y GitHub Actions activado.
- GitHub CLI autenticado y posibilidad de instalar la extensión
gh actions-lock. - Referencias
uses:actuales y revisadas antes de congelarlas. - Un plan compatible: Free, Team o Enterprise Cloud. GitHub no documenta un cargo separado por crear el archivo; siguen aplicando las condiciones normales de Actions y del plan.
La disponibilidad general se anunció el 28 de octubre de 2026. Si trabajas en GitHub Enterprise Server, la nota de lanzamiento no lo incluye: comprueba la versión y la documentación de tu instancia en lugar de asumir compatibilidad.
Cómo crear y revisar actions.lock
- Revisa cada referencia. Confirma que
uses: propietario/accion@v3o la rama elegida sigue siendo la versión que quieres ejecutar. El lockfile congela la decisión; no la toma por ti. - Instala la extensión. Sigue el repositorio enlazado por GitHub Docs y consulta
gh actions-lock --help. La documentación vigente remite a esta extensión para generar y mantener el archivo. - Genera el lockfile. La extensión crea
.github/workflows/actions.locky puede incorporar todos los workflows o una selección gradual. No edites el JSON a mano: regenera el archivo desde las referencias revisadas. - Examina el cambio antes de hacer commit. El campo
commites el código que se ejecutará. Un cambio deowner_idorepo_ides raro y puede indicar que el nombre del repositorio ahora apunta a otro origen. - Confirma el resultado sin modificarlo. Añade la comprobación de lockfile obsoleto a CI. GitHub documenta un modo de verificación que falla si el archivo ya no corresponde a los workflows.
- Activa la política cuando el piloto pase. Administradores de repositorio, organización o empresa pueden exigir lockfile. Hazlo después de incorporar los workflows necesarios para no romper todos a la vez.
Qué ocurre cuando cambia una dependencia
Dependabot puede actualizar la referencia y regenerar la entrada correspondiente en la misma pull request. La revisión debe mirar las dos cosas: la versión declarada y el commit final. Si una etiqueta se ha movido, --relock obliga a revisar ese movimiento; para una historia reescrita, la documentación reserva --accept-moved y desaconseja usarlo automáticamente.
El resultado esperado es un repositorio con workflows todavía comprensibles, un archivo versionado que inventaría los commits ejecutables y una comprobación que detecta divergencias. Antes de exigirlo a toda una organización, prueba un workflow representativo y conserva la pull request como evidencia de la revisión.
Los casos que requieren una decisión aparte
| Caso | Tratamiento documentado | Límite |
|---|---|---|
| Acción transitiva | Queda incluida en el lockfile | Revisar también su cambio de commit |
| Workflow reutilizable externo | Fijar la llamada por SHA | Sus acciones dependen del lockfile de su repositorio |
| Acción local | Migrarla o declarar sus dependencias | Ignorarla puede hacer fallar el job cuando falte un pin |
| Etiqueta movida | Revisar upstream y regenerar | No aceptar el movimiento a ciegas |
El lockfile reduce una clase concreta de riesgo de cadena de suministro: que una referencia móvil ejecute otro commit. No sustituye la revisión del proveedor, la limitación de permisos, la protección de secretos ni las protecciones de ejecución de workflows. Tampoco vuelve fiable una acción maliciosa que ya estaba fijada.
Transparencia: guía elaborada con asistencia de IA a partir de GitHub Docs y el anuncio de disponibilidad general. Los comandos se reproducen de la documentación; Texploto no instaló la extensión ni modificó un repositorio para esta pieza.
