Saltar al contenido principal
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

VentajaDescripción
Defensa frente a ataques a la cadena de suministroAl referenciar un hash de commit concreto, resistes las manipulaciones de la acción.
AuditabilidadPuedes seguir cuándo se actualizó cada acción y desde qué versión.
Actualizaciones explícitasAl proponerse mediante Dependabot, siempre pasan por una revisión humana.
ReproducibilidadAl ejecutar con el mismo hash de commit, se reproduce exactamente el mismo entorno.

Desventajas

DesventajaCómo se mitiga
Configuración inicial manualSe automatiza con pinact.
Más carga de gestión de actualizacionesDependabot crea automáticamente los PRs, así que el coste de implementación es mínimo.
Menor legibilidadAñ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.
  • 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.
  • 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.
  • 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.
Última modificación el 13 de julio de 2026