Pinning y seguridad en GitHub Actions

Como medida contra los ataques a la cadena de suministro en los paquetes, explica cómo fijar (pinning) las dependencias de GitHub Actions con hashes SHA en lugar de versiones, incluyendo la estrategia de actualización automática con Dependabot.

Para responder al riesgo de ataques o manipulación de las acciones de GitHub, incluso los proyectos oficiales de Laravel adoptan una medida de seguridad: el pinning de GitHub Actions. Esta página explica de forma práctica las medidas de seguridad que debe implementar un desarrollador de paquetes.

Esta página es hermana de Fundamentos del desarrollo de paquetes. Da por sabido el uso básico de GitHub Actions.

​

Riesgos de seguridad en GitHub Actions

​

Peligros de las referencias por tag

Habitualmente, las GitHub Actions se referencian con tags:

- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2

Problemas de este enfoque:

• Los tags se pueden mover — pueden borrarse y recrearse conservando el mismo nombre.
• Riesgo de manipulación — el secuestro de la cuenta del propietario del repositorio permite inyectar código malicioso.
• Ataque a la cadena de suministro — si atacan una acción de la que dependes, tu workflow queda comprometido.

​

Respuesta en los proyectos oficiales de Laravel

laravel/laravel y laravel/framework fijan todas sus acciones a un hash de commit (SHA).

# Forma de referencia segura
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

​

Estrategia de implementación del pinning

​

Paso 1: crear el archivo de configuración de Dependabot

En el repositorio del paquete, crea .github/dependabot.yml. Puedes copiar el archivo de Laravel tal cual.

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 5
    groups:
      github-actions:
        patterns:
          - "*"

Este archivo cumple las siguientes funciones:

• Escaneo automático — busca nuevas versiones de las GitHub Actions.
• Creación automática de PRs — cuando hay actualizaciones, abre una PR de forma automática.
• Control del método de actualización — las acciones no fijadas se actualizan por versión; las fijadas, por SHA.

​

Paso 2: fijar las acciones existentes con SHA

Cambia todas las referencias a acciones en tus workflows por hashes SHA. Puedes automatizarlo con herramientas como pinact.

​

Automatización con la herramienta pinact

# Fija en SHA las acciones de los workflows
pinact run

​

Cambio manual

Si no puedes usar pinact, consulta en la página “Lookup latest version” de GitHub el SHA de commit de cada acción y sustitúyelo a mano.

# Antes
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}

# Después
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
- uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
  with:
    php-version: ${{ matrix.php }}

​

Paso 3: activar la configuración de Dependabot

Al hacer commit y push de .github/dependabot.yml al repositorio, Dependabot comenzará el escaneo automáticamente.

​

Mecanismo de actualización automática de Dependabot

Dependabot aplica estrategias distintas según la configuración de dependabot.yml.

​

Acciones no fijadas

# Antes del pinning
- uses: actions/checkout@v4

Actualización de Dependabot: actualiza el rango de versión a una nueva versión.

# PR que crea Dependabot
- uses: actions/checkout@v5

Este enfoque prioriza la comodidad y se adapta al movimiento de tags, pero conserva el riesgo de seguridad.

​

Acciones fijadas

# Después del pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

Actualización de Dependabot: actualiza al hash de commit de la nueva versión.

# PR que crea Dependabot
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4

Este enfoque es el más seguro. Incluso al pasar a una versión nueva, sigue siendo una referencia a un commit, resistente a manipulaciones.

​

Ejemplo de implementación de un workflow

Ejemplo completo de uso de acciones en varios workflows.

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
        with:
          fetch-depth: 0

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, intl, sqlite3
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: "8.4"
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Run static analysis
        run: vendor/bin/phpstan

​

Cómo tratar las PRs de actualización de Dependabot

Trata así las PRs que crea Dependabot.

​

PR de actualización de una sola acción

Bump shivammathur/setup-php from v1 to v2

Actualizaciones simples como esta se gestionan del siguiente modo:

1. Revisa los resultados del workflow.
2. Comprueba que no hay cambios rompedores.
3. Haz merge y listo.

​

PR de actualización de seguridad

[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab

Las actualizaciones relacionadas con parches de seguridad se mergean de forma prioritaria.

​

Actualización en grupo de varias acciones

Si has configurado groups en dependabot.yml, varias acciones se actualizan en una sola PR.

groups:
  github-actions:
    patterns:
      - "*"

Al agrupar todas las actualizaciones en una única PR, reduces el número de merges.

​

Ventajas y desventajas del pinning

​

Ventajas

Ventaja	Descripción
Defensa frente a ataques a la cadena de suministro	Al referenciar un hash de commit concreto, resistes las manipulaciones de la acción.
Auditabilidad	Puedes seguir cuándo se actualizó cada acción y desde qué versión.
Actualizaciones explícitas	Al proponerse mediante Dependabot, siempre pasan por una revisión humana.
Reproducibilidad	Al ejecutar con el mismo hash de commit, se reproduce exactamente el mismo entorno.

​

Desventajas

Desventaja	Cómo se mitiga
Configuración inicial manual	Se automatiza con pinact.
Más carga de gestión de actualizaciones	Dependabot crea automáticamente los PRs, así que el coste de implementación es mínimo.
Menor legibilidad	Añade un comentario con la versión al lado para conservar la legibilidad.

​

Checklist de auditoría de seguridad

Checklist para arrancar un nuevo proyecto de paquete.

Configuración inicial

• Crear .github/dependabot.yml.
• Fijar en SHA todas las acciones existentes.
• Verificar con pinact o de forma manual.
• Comprobar que los workflows se ejecutan correctamente.

Mantenimiento periódico

• Revisar las PRs de Dependabot al menos una vez por semana.
• Mergear las actualizaciones de seguridad con prioridad.
• Al añadir nuevas acciones, referenciarlas siempre por SHA.
• Revisar el estado de todos los workflows una vez al mes.

Auditoría

• Verificar que todas las referencias de acción están en SHA.
• Verificar que Dependabot está activo.
• Confirmar que las PRs de Dependabot de los últimos 6 meses están todas mergeadas.

​

Páginas relacionadas

Fundamentos del desarrollo de paquetes

Cómo desarrollar paquetes Laravel centrados en los service providers.

Gestión de la compatibilidad de versiones de paquetes

Estrategias de mantenimiento de paquetes ante grandes actualizaciones de Laravel.