Pinning et sécurité de GitHub Actions

Pour se prémunir contre les attaques de la chaîne d’approvisionnement des packages, découvrez comment épingler les dépendances GitHub Actions à un hash SHA plutôt qu’à une version, y compris la stratégie de mise à jour automatique avec Dependabot.

Pour répondre au risque d’attaques et d’altérations visant les GitHub Actions, une mesure de sécurité adoptée jusque par les projets Laravel officiels consiste à épingler (pinning) les actions. Cette page présente concrètement les mesures de sécurité que vous devriez mettre en œuvre en tant que développeur de packages.

Cette page est la sœur de Les bases du développement de packages. Une connaissance de base de l’utilisation de GitHub Actions est supposée.

​

Risques de sécurité liés à GitHub Actions

​

Le danger des références par tag

En temps normal, on référence les GitHub Actions par tag, comme ceci :

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

Les problèmes de cette approche :

• Les tags sont mobiles — un tag peut être supprimé puis recréé sous le même nom.
• Risque d’altération — la prise de contrôle du compte du propriétaire du dépôt permet d’injecter du code malveillant.
• Attaque de la chaîne d’approvisionnement — si une action dont vous dépendez est attaquée, votre workflow est compromis.

​

Ce que font les projets Laravel officiels

Dans laravel/laravel et laravel/framework, toutes les actions sont épinglées à un hash de commit (SHA).

# Référence sécurisée
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

​

Stratégie de mise en œuvre du pinning

​

Étape 1 : créer le fichier de configuration Dependabot

Créez .github/dependabot.yml à la racine du dépôt de votre package. Vous pouvez copier tel quel le fichier de Laravel.

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

Ce fichier joue les rôles suivants :

• Analyse automatique — scanne les nouvelles versions des GitHub Actions.
• Création automatique de PR — crée automatiquement des PR de mise à jour lorsqu’une mise à jour est disponible.
• Contrôle de la stratégie de mise à jour — les actions non épinglées sont mises à jour par version, les actions épinglées le sont par SHA.

​

Étape 2 : épingler les actions existantes au SHA

Remplacez toutes les références d’actions dans vos workflows existants par un hash SHA. Cette opération peut être automatisée avec des outils tels que pinact.

​

Automatisation avec pinact

# Épingle les actions du workflow au SHA
pinact run

​

Modification manuelle

Si pinact n’est pas disponible, consultez la page Lookup latest version de GitHub pour trouver le SHA de commit de chaque action, puis remplacez manuellement.

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

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

​

Étape 3 : activer la configuration Dependabot

Commitez et poussez .github/dependabot.yml dans le dépôt : Dependabot lance automatiquement son analyse.

​

Mécanisme de mise à jour automatique de Dependabot

Dependabot applique différentes stratégies de mise à jour en fonction de la configuration dans dependabot.yml.

​

Actions non épinglées

# Avant pinning
- uses: actions/checkout@v4

Mise à jour Dependabot : met à jour la plage de versions vers la nouvelle version

# PR créée par Dependabot
- uses: actions/checkout@v5

Cette approche privilégie la commodité et gère le déplacement de tags, mais les risques de sécurité subsistent.

​

Actions épinglées

# Après pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

Mise à jour Dependabot : met à jour vers le hash de commit de la nouvelle version

# PR créée par Dependabot
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4

Cette approche est la plus sûre. Même sur une nouvelle version, la référence par hash de commit résiste à l’altération.

​

Exemple d’implémentation de workflow

Voici un exemple complet lorsque des actions sont utilisées dans plusieurs 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

​

Gérer les PR de mise à jour Dependabot

Voici comment traiter les PR de mise à jour créées par Dependabot.

​

PR de mise à jour d’une action isolée

Bump shivammathur/setup-php from v1 to v2

Pour ce type de mise à jour simple, procédez ainsi :

1. Vérifiez le résultat d’exécution du workflow.
2. Vérifiez l’absence de changements cassants.
3. Fusionnez.

​

PR de mise à jour de sécurité

[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab

Fusionnez en priorité les mises à jour liées à des correctifs de sécurité.

​

Mise à jour groupée de plusieurs actions

Lorsque groups est configuré dans dependabot.yml, plusieurs actions sont mises à jour dans une seule PR.

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

Regrouper toutes les mises à jour d’actions dans une PR unique réduit le nombre de fusions à effectuer.

​

Avantages et inconvénients du pinning

​

Avantages

Avantage	Description
Protection contre les attaques de chaîne d’approvisionnement	Référencer un hash de commit précis permet de résister à l’altération des actions.
Auditabilité	Vous pouvez suivre quand et à partir de quelle version chaque action a été mise à jour.
Mise à jour explicite	Comme Dependabot propose les mises à jour, chacune passe obligatoirement par une revue humaine.
Reproductibilité	Exécuter avec le même hash de commit reproduit exactement le même environnement.

​

Inconvénients

Inconvénient	Solution
Configuration initiale manuelle	Automatiser avec l’outil pinact.
Charge de gestion des mises à jour	Les PR automatiques via Dependabot minimisent le coût de mise en œuvre.
Manque de lisibilité	Assurer la lisibilité en indiquant la version en commentaire.

​

Checklist d’audit de sécurité

Voici une checklist pour démarrer un nouveau projet de package.

Configuration initiale

• Créer .github/dependabot.yml
• Épingler toutes les actions existantes au SHA
• Vérification effectuée avec pinact ou manuellement
• Vérifier que les workflows s’exécutent correctement

Maintenance régulière

• Revoir les PR Dependabot au moins une fois par semaine
• Fusionner en priorité les mises à jour de sécurité
• Toujours référencer par SHA à l’ajout d’une nouvelle action
• Vérifier l’état de tous les workflows une fois par mois

Audit

• Vérifier que toutes les références d’actions utilisent bien un SHA
• Vérifier que Dependabot est bien activé
• Vérifier que toutes les PR Dependabot des 6 derniers mois ont été fusionnées

​

Pages associées

Les bases du développement de packages

Découvrez comment développer un package Laravel autour d’un service provider.

Gestion de la compatibilité de versions de package

Découvrez la stratégie d’adaptation d’un package aux montées de version majeures de Laravel.