---
title: "Ponle candado a tus GitHub Actions: así funcionan los lockfiles de workflows"
url: https://hernandez.systems/es/articulos/ponle-candado-tus-github-actions-asi-funcionan-los-lockfiles-de
lang: es
type: NewsArticle
section: Infraestructura
published: "2026-11-15T16:04:01+00:00"
modified: "2026-11-16T15:01:45+00:00"
publisher: Osky Networks
image: https://oskydj.sfo3.cdn.digitaloceanspaces.com/calamardo/news_item/2026-11-15/e146-portada-562e5073.jpg
alternate_en: https://hernandez.systems/en/articles/lock-down-your-github-actions-how-workflow-lockfiles-work
---

# Ponle candado a tus GitHub Actions: así funcionan los lockfiles de workflows

> Cada vez que tu workflow dice uses: alguien/accion@v3, le estás firmando un cheque en blanco a quien controle ese tag. Los tags de Git se pueden mover, y si a un mantenedor le roban la cuenta, el v3 que revisaste hace seis meses puede apuntar mañana a código malicioso que corre con tus secretos dentro. Para eso existen ahora los lockfiles de workflows: GitHub los declaró en disponibilidad general el 28 de octubre de 2026 para los planes Free, Team y Enterprise Cloud. El tema volvió a la conversación esta semana gracias a una guía práctica de Hugo van Kemenade que llegó a más de 300 puntos en Hacker News. Aquí va qué es, cómo se adopta y qué no resuelve. Aviso de entrada: no lo probé; esto sale de la documentación oficial de GitHub, del repositorio de la herramienta y del post de van Kemenade.

Cada vez que tu workflow dice `uses: alguien/accion@v3`, le estás firmando un cheque en blanco a quien controle ese tag. Los tags de Git se pueden mover, y si a un mantenedor le roban la cuenta, el `v3` que revisaste hace seis meses puede apuntar mañana a código malicioso que corre con tus secretos dentro. Para eso existen ahora los **lockfiles de workflows**: GitHub los declaró en [disponibilidad general el 28 de octubre de 2026](https://github.blog/changelog/2026-10-28-github-actions-workflow-lockfiles-are-generally-available/) para los planes Free, Team y Enterprise Cloud. El tema volvió a la conversación esta semana gracias a una [guía práctica de Hugo van Kemenade](https://hugovk.dev/blog/2026/lock-github-actions/) que llegó a más de 300 puntos en [Hacker News](https://news.ycombinator.com/item?id=50459485). Aquí va qué es, cómo se adopta y qué no resuelve. Aviso de entrada: no lo probé; esto sale de la documentación oficial de GitHub, del repositorio de la herramienta y del post de van Kemenade.

## El problema: un tag no es una promesa

Según la [documentación de GitHub](https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles), cuando un workflow referencia una action por tag o rama (`@v3`, `@main`), GitHub Actions resuelve esa referencia **en el momento de correr**, al commit al que apunte en ese instante. Si el tag se mueve, el código que corre ya no es el que alguien revisó. No es teoría: el ataque a `tj-actions/changed-files` [funcionó justo así](https://www.legitsecurity.com/blog/github-actions-tj-actions-changed-files-attack), reapuntando tags que antes eran seguros.

Hasta ahora la recomendación era fijar cada action a un SHA completo de 40 caracteres, con la versión en un comentario. Funciona, pero tiene tres problemas: el workflow se vuelve ilegible, nadie revisa con gusto un diff de hashes y, sobre todo, **no cubre las dependencias transitivas**: si tu action fijada usa por dentro otra action con `@v1`, esa sigue flotando.

## Qué es `actions.lock`

El lockfile vive en `.github/workflows/actions.lock`, lo genera la extensión [`gh-actions-lock`](https://github.com/github/gh-actions-lock) del CLI de GitHub y, según GitHub, **nunca se edita a mano**. Tiene dos secciones:

- `workflows`: qué dependencias usa cada workflow que ya adoptaste.
- `dependencies`: a qué commit se resolvió cada una, con su `ref` (el tag o rama original), su `commit` exacto y el `owner_id` y `repo_id` numéricos del repositorio de origen.

Ese último detalle es lo más fino del diseño. Con esos IDs, GitHub confirma al correr que el repo detrás del nombre sigue siendo el mismo que fijaste. Si alguien borra un repo y otro registra el mismo nombre, GitHub lo detecta al correr, y si regeneras el lockfile el cambio de IDs aparece en el diff. Además, el commit fijado tiene que ser alcanzable desde la rama o el tag registrado en el repo de la action; un commit que solo existe en un fork se rechaza.

Una vez que un workflow entra al lockfile, **todas** sus dependencias tienen que estar ahí y el runner ejecuta el commit registrado aunque el tag se haya movido. GitHub dice en su [página de conceptos](https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles) que, para los repos que adoptan el lockfile, fijar SHAs dentro del workflow "ya no es necesario". El lockfile también cumple la política de fijar actions por SHA completo.

![Comparativa de tres formas de referenciar una action en GitHub Actions: tag suelto, SHA en el workflow y tag con actions.lock, más el flujo de adopción con gh actions-lock](https://oskydj.sfo3.cdn.digitaloceanspaces.com/calamardo/news_item/2026-11-15/e146-diagrama-1af789f6.png)

## Cómo se adopta, paso a paso

Esto es lo que indican la [guía de GitHub](https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies) y el [post de van Kemenade](https://hugovk.dev/blog/2026/lock-github-actions/), que aplicó el cambio en repos como Pillow y CPython:

1. **Revisa tus referencias.** Antes de fijar nada, confirma que cada `uses:` apunte a una versión vigente: el lockfile congela lo que haya hoy, bueno o malo. GitHub recomienda activar Dependabot para actions **antes** de generar el lockfile.
2. **Instala la extensión:** `gh extension install github/gh-actions-lock`. Requiere `gh` autenticado y funciona con github.com y Enterprise Cloud con residencia de datos (`*.ghe.com`); **GitHub Enterprise Server no está soportado**.
3. **Genera el lockfile** desde la raíz del repo con `gh actions-lock`. Puedes adoptar un solo workflow pasando su ruta, por ejemplo `gh actions-lock .github/workflows/ci.yml`.
4. **Revisa el diff completo.** La herramienta no solo crea `actions.lock`: también reescribe tus `uses:`. Una referencia como `@v3` se vuelve `@v3.1.0`, y los SHAs que tenías fijados regresan a tags legibles. En el ejemplo de van Kemenade, `actions/checkout@3d3c42e…  # v7.0.1` quedó como `actions/checkout@v7.0.1`.
5. **Haz commit** de los workflows modificados y del lockfile.

Un detalle que puede romperte el CI: si tu organización solo permite una lista de actions, **después de adoptar el lockfile la lista se compara contra los SHAs fijados, no contra los tags**. Una entrada como `actions/checkout@v6` deja de coincidir; GitHub pide usar comodines o el SHA completo.

## Mantenerlo vivo

Un lockfile que nadie actualiza se vuelve un estorbo en dos semanas. Las piezas que ofrece el ecosistema:

- **Dependabot:** cuando sube la versión de una action en un workflow adoptado, regenera la entrada del lockfile en el mismo pull request, sin configuración extra. Ojo: [no adopta workflows nuevos](https://docs.github.com/en/actions/how-tos/administer/enforce-workflow-lockfiles); solo mantiene lo que ya está dentro.
- **Renovate:** también [soporta `actions.lock`](https://docs.renovatebot.com/modules/manager/github-actions/#github-actions-lockfile-actionslock).
- **Verificación en CI:** `gh actions-lock --verify` no escribe nada y truena si el lockfile está desactualizado o si un commit fijado ya no se verifica contra su origen. GitHub publica un [`verify-lockfile.yml`](https://github.com/github/gh-actions-lock/blob/main/.github/workflows/verify-lockfile.yml) listo para copiar. Van Kemenade lo metió como un job aparte dentro de su workflow de lint, en el runner ligero `ubuntu-slim`, fijando la extensión con `--pin v0.4.1`.
- **Modo previo al commit:** `--verify-local` revisa sin red que cada `uses:` tenga entrada, pero el [README](https://github.com/github/gh-actions-lock) aclara que solo mide cobertura, no procedencia.
- **Cuando un tag se mueve:** con ramas o versiones parciales (`main`, `v3`) la herramienta conserva el commit fijado y avisa con `ref-moved`; con un tag completo (`v3.1.0`) que se movió marca error. En ambos casos se avanza con `--relock`, después de revisar qué cambió río arriba. Si la historia se reescribió, existe `--accept-moved`, que GitHub pide **nunca** usar en automatización.

Y la parte humana, que GitHub dice sin rodeos en su [guía para administradores](https://docs.github.com/en/actions/how-tos/administer/enforce-workflow-lockfiles): un lockfile "solo es un control de seguridad si alguien lee el diff". Recomienda poner `actions.lock` en `CODEOWNERS`, exigir aprobación del dueño del código y tratar cada `commit` cambiado como una subida de versión de cualquier dependencia. Un `owner_id` o `repo_id` distinto debería ser rarísimo y amerita investigar antes del merge.

## Para organizaciones: la política "Require lockfile"

Los administradores de empresa, organización o repositorio pueden activar la política **Require lockfile**, que bloquea los workflows que no estén en el lockfile de su repo, incluso los que no usan ninguna action. GitHub recomienda empezar en modo **Evaluate** y revisar **Policy insights** antes de pasar a **Active**, aunque ese modo de evaluación solo existe en Enterprise Cloud. Si tus workflows llaman workflows reutilizables de otro repo, ese repo también tiene que estar adoptado, o la política bloquea la ejecución.

## Lo que el lockfile no hace

GitHub es honesto con los límites, y vale la pena tenerlos claros:

- **No decide si una dependencia es segura.** El [changelog](https://github.blog/changelog/2026-10-28-github-actions-workflow-lockfiles-are-generally-available/) lo dice tal cual: revisa las dependencias antes de fijarlas. Si fijas una action comprometida, fijaste el problema.
- **No fija workflows reutilizables** llamados con `jobs.<id>.uses` desde otro repo. Para esos, el SHA completo sigue siendo la vía.
- **No fija imágenes de contenedor**; la herramienta advierte si no traen digest `@sha256:`.
- **No sigue actions locales** (`./…`) que a su vez usen actions remotas, salvo que las migres con `--migrate-local-actions` a la nueva sintaxis `$/…`.
- **No cubre secretos, parámetros ni la imagen del runner**: solo el código de las actions.
- Según el [README](https://github.com/github/gh-actions-lock), si alguien regresa una referencia flotante (`v4`, `main`) a un commit más viejo de su propia historia, **no se detecta**. Fija tags completos y lee los diffs.

## Las herramientas alrededor

[zizmor](https://github.com/zizmorcore/zizmor/releases/tag/v1.32.0), el linter de seguridad para GitHub Actions que van Kemenade recomienda "fuertemente", agregó en su versión 1.32.0 (2 de noviembre) soporte **experimental** para lockfiles. Las versiones anteriores te van a seguir pidiendo fijar SHAs, así que actualízalo junto con todo lo demás.

Y si de paso estás revisando tu seguridad en Actions, hay otro cambio con fecha: desde el **2 de diciembre de 2026**, GitHub [bloqueará por defecto](https://github.blog/changelog/2026-11-02-pull_request_target-blocked-by-default-december-2/) el disparador `pull_request_target` en todos los repos públicos, salvo que una política lo permita explícitamente. Lo hace porque ese evento corre con acceso a los secretos del repo base y puede ejecutar código de forks. GitHub programó dos apagones de prueba, el 9 y el 16 de noviembre de 16:00 a 18:00 UTC. Los repos privados e internos no se ven afectados.

## Mi lectura

Esto es el `package-lock.json` que GitHub Actions debió tener desde el primer día. Lo valioso no es fijar commits, que ya se podía, sino hacerlo sin sacrificar legibilidad y alcanzando las dependencias transitivas, que era el hueco que nadie tapaba a mano. Si mantienes cualquier repo con CI que toque secretos (deploys a tu VPS, publicación de paquetes, llaves de nube), adoptarlo es poco trabajo: instalar la extensión, correrla, revisar el diff, sumar el job de verificación y dejar que Dependabot haga el resto. Lo que no te va a dar es criterio: el lockfile congela lo que elegiste, para bien y para mal. El candado es tan bueno como lo que encerraste.

## Fuentes

- [GitHub Changelog: GitHub Actions workflow lockfiles are generally available](https://github.blog/changelog/2026-10-28-github-actions-workflow-lockfiles-are-generally-available/)
- [GitHub Docs: Workflow dependency lockfiles](https://docs.github.com/en/actions/concepts/security/workflow-dependency-lockfiles)
- [GitHub Docs: Locking action dependencies in a repository's workflows](https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies)
- [GitHub Docs: Enforcing lockfiles for action dependencies](https://docs.github.com/en/actions/how-tos/administer/enforce-workflow-lockfiles)
- [Repositorio github/gh-actions-lock](https://github.com/github/gh-actions-lock)
- [verify-lockfile.yml de gh-actions-lock](https://github.com/github/gh-actions-lock/blob/main/.github/workflows/verify-lockfile.yml)
- [GitHub Changelog: pull_request_target blocked by default December 2](https://github.blog/changelog/2026-11-02-pull_request_target-blocked-by-default-december-2/)
- [zizmor v1.32.0](https://github.com/zizmorcore/zizmor/releases/tag/v1.32.0)
- [Renovate: soporte de actions.lock](https://docs.renovatebot.com/modules/manager/github-actions/#github-actions-lockfile-actionslock)
- [Hugo van Kemenade: Lock your GitHub Actions](https://hugovk.dev/blog/2026/lock-github-actions/)
- [Legit Security: el ataque a tj-actions/changed-files](https://www.legitsecurity.com/blog/github-actions-tj-actions-changed-files-attack)
- [Discusión en Hacker News](https://news.ycombinator.com/item?id=50459485)
