Bloqueo de dependencias de acciones en los flujos de trabajo de un repositorio

Genere un archivo lockfile que fije todas las acciones que usan los flujos de trabajo a un commit verificado y manténgalo actualizado a medida que cambian las dependencias.

¿Quién puede utilizar esta característica?

People with write access to a repository

GitHub Enterprise Cloud

En este artículo

Bloquear las dependencias de los flujos de trabajo garantiza que las acciones a las que hace referencia contengan el mismo código que se revisó originalmente. Para obtener más información, vea Archivos de bloqueo de dependencias del flujo de trabajo.

1. Compruebe las referencias a acciones

Al crear un archivo de bloqueo, se anclan las dependencias en commits en función de la referencia de etiqueta o rama actual. Asegúrese de que estas son las versiones que desea fijar.

Compruebe que cada referencia uses en sus flujos de trabajo apunte a una versión actual admitida de la acción. Para conocer los procedimientos recomendados, consulte Referencia de uso seguro.

Si alguno de los flujos de trabajo llama a un flujo de trabajo reutilizable en otro repositorio, compruebe también esas referencias. Las dependencias de un flujo de trabajo reutilizable están cubiertas por el archivo de bloqueo del repositorio donde está definido, no por tu archivo de bloqueo. Ese repositorio de origen necesita su propio archivo lockfile para una cobertura completa. Si su organización mantiene flujos de trabajo compartidos, incorpore primero esos repositorios. Consulte Reutilización de configuraciones de flujo de trabajo.

Recomendamos dejar que Dependabot gestione tus GitHub Actions dependencias. Si aún no está habilitado, habilite antes de crear el archivo de bloqueo. Consulte Mantener tus acciones actualizadas con el Dependabot.

2. Instalar la actions-lock extensión

  1. Instale GitHub CLI.

  2. Instale la extensión.

    Bash
    gh extension install github/gh-actions-lock

Sugerencia

Para actualizar la extensión más adelante, ejecute gh extension upgrade gh-actions-lock.

3. Generar el archivo de bloqueo

Desde la raíz del repositorio, invoque la extensión sin argumentos. Examinará cada flujo de trabajo en .github/workflows/, anclará cada acción resolvible a un SHA de confirmación y escribirá el archivo de bloqueo.

Bash
gh actions-lock

Para incorporar un único flujo de trabajo en lugar de todo el directorio, pase su ruta de acceso.

Bash
gh actions-lock .github/workflows/ci.yml

La extensión nunca sigue o fija una acción de ruta de acceso local (uses: ./…). Una ruta de acceso ./ ejecuta lo que se ha extraído en el área de trabajo del ejecutor, por lo que la extensión no puede fijarla ni ver lo que usa. Una $/ ruta ejecuta la propia acción del repositorio en el commit del flujo de trabajo, por lo que está anclada y las acciones que usa se pueden bloquear. Para obtener una comparación de los dos, consulte Sintaxis del flujo de trabajo para Acciones de GitHub.

Si una acción local de tu checkout usa otras acciones, la extensión muestra un error local-action y no escribe nada, ya que esas acciones generarían un error en tiempo de ejecución sin entradas de archivo de bloqueo. Para bloquear la acción local como referencia del mismo repositorio, ejecute:

Bash
gh actions-lock --migrate-local-actions

Para mantener la ./ referencia e informarla como advertencia, pase --ignore-local-actions. Consulte Mantener una acción de ruta de acceso local.

Para obtener el conjunto completo de opciones, ejecute gh actions-lock --help. Para obtener ayuda con un error o una advertencia específicos, consulte la guía de solución de problemas gh-actions-lock.

Mantener una acción de ruta de acceso local

Si pasa --ignore-local-actions, lo que sucede en tiempo de ejecución depende de las acciones que usa la acción local:

  • No usa ninguna otra acción, por ejemplo, solo pasos run:: el flujo de trabajo se ejecuta normalmente.
  • Usa acciones que tienen entradas de archivo de bloqueo para el mismo flujo de trabajo: el flujo de trabajo se ejecuta normalmente.
  • Usa una acción que no tiene ninguna entrada de archivo de bloqueo para ese flujo de trabajo: el trabajo produce un error cuando llega al paso de la acción local, con un error como lockfile missing pin for octo-org/setup-tool@v2.0.0. Ya se han ejecutado los pasos anteriores.

Se recomienda --migrate-local-actions en su lugar, por lo que la acción se ejecuta como una referencia fijada $/. Si necesita mantener la ./ referencia, proporcione las entradas del archivo de bloqueo de flujo de trabajo para las acciones que usa la acción local. Agregue una acción compuesta que use las mismas acciones, con las mismas referencias y llámela desde el flujo de trabajo en un paso que nunca se ejecute. A continuación, ejecute gh actions-lock --ignore-local-actions.

# .github/actions/lock-local-deps/action.yml
name: Lock local action dependencies
description: Never runs. Lists the actions that ./.github/actions/build uses.
runs:
  using: composite
  steps:
    - uses: octo-org/setup-tool@v2.0.0

# In the workflow
steps:
  - uses: actions/checkout@v6
  - if: false
    uses: $/.github/actions/lock-local-deps
  - uses: ./.github/actions/build

Las entradas deben registrarse para el mismo flujo de trabajo. Una entrada registrada solo para un flujo de trabajo diferente no cuenta. Cuando cambien las dependencias de la acción local, actualice la acción compuesta y vuelva a ejecutar gh actions-lock --ignore-local-actions.

4. Revisar los cambios y hacer commit

La extensión cambia más que el lockfile, por lo que revise la diferencia completa antes de hacer commit. También vuelve a escribir las referencias de flujo de trabajo uses a la versión específica que resolvió, por lo que una referencia como octo-org/deploy-action@v3 puede convertirse en octo-org/deploy-action@v3.1.0. Esto hace que la referencia sea más específica sin cambiar el commit al que se resuelve.

Importante

Si el repositorio, la organización o la empresa solo permiten acciones especificadas, compruebe la lista de acciones permitidas antes de hacer commit. Después de incorporar un flujo de trabajo, la lista de autorizados se comprueba con SHA de commit bloqueados en lugar de etiquetas, ya que una etiqueta se puede mover a código diferente, pero un SHA bloqueado no puede hacerlo. Las entradas ancladas a una etiqueta, como actions/checkout@v6, ya no se asocian una vez que se incorpora un flujo de trabajo. En su lugar, use un carácter comodín o el SHA completo del commit. Consulte Administración de la configuración de Acciones de GitHub para un repositorio.

Si ha especificado --migrate-local-actions, la extensión también reescribe las referencias a las acciones de su propio repositorio, de uses: ./… a uses: $/…, en los flujos de trabajo y los archivos action.yml de su repositorio. Esto solo se hace cuando se pasa la opción, ya que las dos formas se comportan de forma diferente. Una ./ ruta de acceso se resuelve con respecto a lo que haya en el área de trabajo del ejecutor, mientras que una $/… referencia siempre se ejecuta en el propio commit del flujo de trabajo, por lo que no necesita ninguna entrada de archivo de bloqueo. Revise cada línea reescrita.

5. Mantener el lockfile actualizado

Mantenga el archivo de bloqueo actualizado con los archivos de flujo de trabajo y las actualizaciones de seguridad del repositorio.

  1. Vuelva a ejecutar la acción de la extensión al cambiar las dependencias. Vuelva a ejecutar gh actions-lock cada vez que agregue un flujo de trabajo que tenga dependencias de uses, o agregue o quite dependencias de uses en un flujo de trabajo existente.

  2. Deje que Dependabot gestione los incrementos de versión. Cuando Dependabot abre una actualización de versión para una acción en un flujo de trabajo que has incorporado, también vuelve a generar la entrada de archivo de bloqueo coincidente en la misma solicitud de incorporación de cambios. El archivo de flujo de trabajo y el archivo de bloqueo no pueden desfasarse.

Dependabot solo actualiza las entradas del lockfile para los flujos de trabajo que ya están habilitados. Si actualiza una acción en un flujo de trabajo que no está en el archivo de bloqueo, actualiza el archivo de flujo de trabajo como de costumbre y deja el archivo de bloqueo sin cambios.

  1. Vuelva a resolver las referencias que se han movido. La forma en que la extensión controla una referencia movida depende de la referencia:

    • Una rama o versión parcial, como main o v3, mantiene su commit bloqueado y la extensión notifica una advertencia de ref-moved. Para avanzar, compruebe el historial de upstream y, a continuación, ejecute gh actions-lock --relock.
    • Una etiqueta de versión completa, como v3.1.0, debe apuntar a su commit bloqueado. Si la etiqueta se ha movido, la extensión notifica un error hasta que se ejecuta gh actions-lock --relock o se cambia la línea uses:.
    • Un historial reescrito, donde el commit bloqueado ya no está en el historial de la referencia, por ejemplo, después de un push forzado, es un error que --relock no corrige. Después de revisar el historial upstream, ejecute gh actions-lock --accept-moved. No utilice --accept-moved en la automatización.

Revisar los cambios del lockfile

Revise los cambios en el archivo de bloqueo como cualquier otro cambio de dependencia:

  • Un elemento modificado commit es el código que ejecutarán los flujos de trabajo. Trátalo como tratarías cualquier otra actualización de versión de una dependencia.
  • Algo modificado owner_id o repo_id debe ser poco frecuente. Significa que el repositorio detrás de ese nombre no es el que bloqueaste originalmente, por lo que investiga antes de combinar.

Si un archivo de bloqueo parece incorrecto, corrija los archivos de flujo de trabajo y vuelva a generarlo. Nunca edite el lockfile manualmente.

Pasos siguientes

Una vez que haya generado un archivo de bloqueo para un repositorio, asegúrese de que se aplica y está actualizado sin necesidad de que los desarrolladores recuerden ejecutar comandos. Consulte Exigir el uso de archivos de bloqueo para las dependencias de action.