Archivos de bloqueo de dependencias del flujo de trabajo

¿Por qué bloquear las dependencias de flujo de trabajo?

Los flujos de trabajo suelen hacer referencia a una acción por una etiqueta o rama, como uses: octo-org/deploy-action@v3 o uses: octo-org/deploy-action@main. GitHub Actions resuelve esa referencia al commit al que apunten la etiqueta o la rama en tiempo de ejecución.

Las etiquetas y las ramas se pueden mover. Como resultado, no se garantiza que el código que se ejecuta sea el código que el autor del flujo de trabajo revisó originalmente. Si la cuenta del mantenedor upstream ha sido comprometida y se vuelve a apuntar una etiqueta, los repositorios podrían ejecutar código malintencionado.

Un archivo de bloqueo de dependencia de flujo de trabajo ancla un SHA de confirmación a cada acción de la que dependen los flujos de trabajo, incluidas las dependencias transitivas. No ancla llamadas a flujos de trabajo reutilizables (jobs.<job_id>.uses). Para anclar un flujo de trabajo reutilizable, haga referencia a él mediante su SHA completo de confirmación. Un archivo lockfile controla qué código de acción se ejecuta en el runner. No controla otras entradas de compilación, como parámetros de entrada, secretos o la imagen del ejecutor. Un lockfile proporciona lo siguiente para el código de acción que cubre:

• Resolución reproducible de dependencias de acción
• Cambios de dependencia revisables y Dependabot actualizaciones de versiones
• Un inventario auditable de las dependencias de acción de tus sistemas de CI/CD

¿Cómo funciona el lockfile?

El archivo de bloqueo se define en un repositorio en .github/workflows/actions.lock. Se genera mediante gh actions-lock, una GitHub CLI extensión y nunca se debe editar manualmente.

Puede incorporar los flujos de trabajo de un repositorio al flujo de trabajo de lockfile de uno en uno o todos a la vez. Después de que se haya integrado un flujo de trabajo:

• Cada dependencia de acción que usa el flujo de trabajo debe estar presente en el archivo de bloqueo.
• El commit bloqueado es lo que se ejecuta cuando se ejecuta el flujo de trabajo y lo que comprueban las directivas de acciones permitidas.
• Este commit debe ser alcanzable desde la rama o etiqueta registrada para él en el archivo de bloqueo, en el repositorio propio de la acción. Un commit que solo existe en una bifurcación o que ya no es accesible desde esa rama o etiqueta se rechaza cuando se ejecuta el flujo de trabajo.

Un archivo de bloqueo cubre los flujos de trabajo de su propio repositorio, incluidas las dependencias transitivas (acciones que usan las dependencias de tu acción), excepto las dependencias de las llamadas de flujo de trabajo reutilizables. Los flujos de trabajo reutilizables también pueden tener sus propios archivos de bloqueo. Las dependencias de un flujo de trabajo reutilizable están cubiertas por el archivo de bloqueo del repositorio donde está definido, no por el archivo de bloqueo del repositorio que lo llama.

¿Qué registra el archivo lockfile?

El archivo de bloqueo tiene dos secciones. workflows registra las dependencias que usa cada flujo de trabajo incorporado y dependencies registra a qué commit se resuelve cada una de esas referencias.

# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
    '.github/workflows/ci.yml':
        - 'octo-org/deploy-action@v3.1.0'
dependencies:
    'octo-org/deploy-action@v3.1.0':
        ref: 'v3.1.0'
        commit: 'sha1-...'
        owner_id: 44036562
        repo_id: 197814629

Cada dependencia registra:

• ref: etiqueta o rama desde la que se resolvió el commit.
• commit: El commit exacto al que se resolvió la referencia. Este es el código que se ejecutará.
• owner_id y repo_id: la identidad numérica del repositorio de origen. GitHub Actions los usa para confirmar en tiempo de ejecución que el repositorio detrás del nombre sigue siendo el que ha bloqueado.

Este formato estructurado proporciona herramientas como Dependabot un registro legible por máquina que pueden usar para administrar las actualizaciones de dependencias, sin depender de los comentarios de YAML como anotaciones de versión.

¿Cómo se comparan los lockfiles con la fijación por SHA?

GitHub ha recomendado históricamente anclar acciones de terceros a un SHA de confirmación de longitud completa en los archivos de flujo de trabajo. En el caso de los repositorios que adoptan un archivo de bloqueo, el anclaje sha dentro de los archivos de flujo de trabajo ya no es necesario. El archivo de bloqueo es la mejor opción porque:

• Admite dependencias transitivas
• Facilita la lectura de archivos de flujo de trabajo
• Registra la identidad del repositorio de origen.

Un archivo de bloqueo también satisface la directiva independiente Exigir que las acciones se fijen a un SHA de confirmación completo para los flujos de trabajo que se incorporan a ella. Consulte Gobernanza de la ejecución de flujos de GitHub Actions trabajo.

Pasos siguientes

Para crear un archivo de bloqueo para un repositorio, consulte Bloqueo de dependencias de acciones en los flujos de trabajo de un repositorio.