actionlint : valider vos workflows GitHub Actions

Vous avez passé une heure à écrire un workflow GitHub Actions. Vous le poussez, et… échec immédiat. Une erreur de syntaxe. Un nom d’action mal orthographié. Une référence à un secret qui n’existe pas. Ces erreurs auraient pu être détectées avant le push.

actionlint est un linter statique qui analyse vos fichiers de workflow et détecte les erreurs avant qu’elles ne se produisent sur GitHub.

Qu’est-ce que actionlint ?

actionlint est un outil en ligne de commande qui analyse statiquement vos workflows GitHub Actions. Il vérifie la syntaxe YAML, les références aux actions, les expressions, les permissions, et bien plus — le tout sans exécuter le workflow.

Concrètement, actionlint détecte :

• Les erreurs de syntaxe YAML (indentation, structure)
• Les propriétés inconnues ou mal orthographiées
• Les références invalides à des contexts (${{ github.sha }})
• Les actions inexistantes ou mal référencées
• Les permissions incorrectes
• Les problèmes de type dans les expressions
• Les patterns glob invalides
• Et plus de 50 autres types d’erreurs

Analogie

actionlint, c’est comme un correcteur orthographique pour vos workflows. Avant d’envoyer un document important, vous le passez au correcteur pour éviter les fautes embarrassantes. Ici, vous validez vos workflows avant de les pousser pour éviter les échecs évitables.

Pourquoi utiliser actionlint ?

Sans actionlint	Avec actionlint
Erreur découverte après le push	Erreur détectée avant le commit
Attente du runner (30s à plusieurs min)	Validation instantanée (< 1s)
Historique pollué de runs échoués	Runs plus propres
Debug par essai-erreur	Messages d’erreur clairs et précis

Installation

macOS

Avec Homebrew :

brew install actionlint

Linux

Avec Homebrew :

brew install actionlint

Depuis les releases GitHub :

# Télécharger la dernière version
curl -sSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash

# Le binaire est téléchargé dans le répertoire courant
sudo mv actionlint /usr/local/bin/

Avec Go :

go install github.com/rhysd/actionlint/cmd/actionlint@latest

Windows

Avec Chocolatey :

choco install actionlint

Avec Scoop :

scoop install actionlint

Vérification de l’installation :

actionlint --version

La commande doit afficher la version installée (ex: 1.7.7).

Utilisation de base

Valider tous les workflows

À la racine de votre projet :

actionlint

actionlint trouve automatiquement les fichiers dans .github/workflows/ et les analyse tous.

Exemple de sortie :

.github/workflows/ci.yml:15:9: property "node-verion" is not defined in object type {cache: string; ...} [expression]
   |
15 |           node-verion: 20
   |           ^~~~~~~~~~~~
.github/workflows/ci.yml:23:7: "actions/checkout@v4" is not pinned by a SHA [security]
   |
23 |       - uses: actions/checkout@v4
   |         ^~~~~~~~~~~~~~~~~~~~~~~~~

Valider un workflow spécifique

actionlint .github/workflows/ci.yml

Valider depuis stdin

Utile pour les scripts ou les pipelines :

cat .github/workflows/ci.yml | actionlint -

Comprendre les messages d’erreur

actionlint fournit des messages précis avec le numéro de ligne, la colonne, et une explication. Voici les catégories principales :

Erreurs de syntaxe

.github/workflows/ci.yml:10:3: "on" section is missing [syntax]

Le workflow n’a pas de section on: qui définit quand il se déclenche.

Erreurs de propriété

.github/workflows/ci.yml:15:9: property "node-verion" is not defined [expression]

Faute de frappe : node-verion au lieu de node-version.

Erreurs de type

.github/workflows/ci.yml:8:5: "runs-on" expects string or array, but got number [syntax]

La valeur de runs-on doit être une chaîne, pas un nombre.

Erreurs de sécurité

.github/workflows/ci.yml:12:7: "actions/checkout@v4" is not pinned by a SHA [security]

L’action utilise un tag mutable au lieu d’un SHA. Voir Épinglage SHA.

Erreurs d’expression

.github/workflows/ci.yml:20:15: undefined variable "github.secret" [expression]

Le context github.secret n’existe pas (c’est secrets.X qu’il faut utiliser).

Options utiles

Format de sortie

# Format par défaut (lisible)
actionlint

# Format JSON (pour intégration CI)
actionlint -format json

# Format SARIF (pour GitHub Code Scanning)
actionlint -format sarif > results.sarif

# Format compatible avec les problèmes GitHub Actions
actionlint -format '{{range $err := .}}::error file={{$err.Filepath}},line={{$err.Line}},col={{$err.Column}}::{{$err.Message}}{{end}}'

Ignorer certaines règles

# Ignorer les erreurs de sécurité (épinglage SHA)
actionlint -ignore 'SC2086'

# Ignorer plusieurs règles
actionlint -ignore 'SC2086' -ignore 'SC2129'

Vous pouvez aussi ignorer des erreurs dans le fichier lui-même :

# actionlint: ignore=expression
- name: Step with ignored warning
  run: echo "${{ github.secret }}"

Mode verbeux

actionlint -verbose

Affiche les fichiers analysés et le temps d’exécution.

Vérification des actions du Marketplace

Par défaut, actionlint vérifie que les actions référencées existent. Pour désactiver (en cas de problème réseau) :

actionlint -no-color -oneline

Intégration dans VS Code

actionlint s’intègre avec les éditeurs pour afficher les erreurs en temps réel.

Extension VS Code

1. Installez l’extension GitHub Actions de GitHub
2. Elle utilise automatiquement actionlint s’il est installé

Ou utilisez l’extension dédiée actionlint :

1. Ouvrez VS Code
2. Extensions → Recherchez “actionlint”
3. Installez l’extension

Les erreurs apparaissent directement dans l’éditeur avec des soulignements.

Configuration VS Code

Dans .vscode/settings.json :

{
  "actionlint.executable": "/usr/local/bin/actionlint",
  "yaml.schemas": {
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

Intégration dans la CI

Workflow de validation

Créez un workflow qui valide vos autres workflows :

name: Lint Workflows

on:
  push:
    paths:
      - '.github/workflows/**'
  pull_request:
    paths:
      - '.github/workflows/**'

permissions:
  contents: read

jobs:
  actionlint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Install actionlint
        run: |
          curl -sSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash
          sudo mv actionlint /usr/local/bin/

      - name: Validate workflows
        run: actionlint -color

Avec l’action officielle

name: Lint Workflows

on:
  pull_request:
    paths:
      - '.github/workflows/**'

permissions:
  contents: read

jobs:
  actionlint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - uses: reviewdog/action-actionlint@a5524e1c19e62881d79c1f6e6c4278c02d74c3f0 # v1.64.0
        with:
          reporter: github-pr-review

Cette action utilise reviewdog pour commenter directement les PRs avec les erreurs détectées.

Hook pre-commit

Validez avant chaque commit avec pre-commit ↗ :

.pre-commit-config.yaml

repos:
  - repo: https://github.com/rhysd/actionlint
    rev: v1.7.7
    hooks:
      - id: actionlint

Puis :

pip install pre-commit
pre-commit install

Règles de validation

actionlint vérifie de nombreuses règles. Voici les principales catégories :

Syntaxe et structure

Règle	Description
syntax	Erreurs YAML de base
expression	Expressions ${{ }} invalides
deprecated-commands	Commandes obsolètes (set-output, etc.)

Sécurité

Règle	Description
permissions	Permissions manquantes ou trop larges
credentials	Secrets exposés en clair
shell-injection	Injection possible via ${{ }} dans run:

Actions et références

Règle	Description
action	Actions inexistantes ou mal référencées
events	Événements invalides
job-needs	Dépendances needs: incorrectes

Types et valeurs

Règle	Description
runner-label	Labels de runner invalides
glob	Patterns glob invalides dans paths:
matrix	Erreurs dans la définition de matrice

Combinaison avec act

Pour une validation complète de vos workflows :

1. actionlint : validation statique (syntaxe, types, références)
2. act : exécution locale (logique, scripts, comportement)

# Script de validation complet
#!/bin/bash

echo "🔍 Validation statique avec actionlint..."
actionlint
if [ $? -ne 0 ]; then
    echo "❌ Erreurs de lint détectées"
    exit 1
fi

echo "🚀 Test d'exécution avec act..."
act -n
if [ $? -ne 0 ]; then
    echo "❌ Erreurs d'exécution détectées"
    exit 1
fi

echo "✅ Workflows valides !"

Voir le guide act pour les tests d’exécution locale.

Configuration avancée

Fichier de configuration

Créez un fichier .github/actionlint.yaml :

# Configuration actionlint
self-hosted-runner:
  labels:
    - my-runner
    - gpu-runner

config-variables:
  - MY_ORG_VAR
  - DEPLOYMENT_ENV

paths:
  ignore:
    - '.github/workflows/deprecated-*.yml'

Variables d’organisation

Si vous utilisez des variables au niveau organisation (${{ vars.ORG_VAR }}), déclarez-les pour éviter les faux positifs :

.github/actionlint.yaml

config-variables:
  - ORG_CONFIG
  - COMPANY_NAME

Dépannage

”command not found: actionlint”

Symptôme : le terminal ne trouve pas la commande.

Solutions :

# Vérifier l'installation
which actionlint

# Si installé via Go, ajouter au PATH
export PATH="$PATH:$(go env GOPATH)/bin"

Faux positifs sur des actions personnalisées

Symptôme : actionlint signale des actions locales comme inexistantes.

Solution : les actions locales (./actions/my-action) sont validées si elles existent dans le repo. Vérifiez le chemin.

Erreurs réseau lors de la validation

Symptôme : actionlint échoue à vérifier les actions du Marketplace.

Solution : utiliser le mode hors ligne :

actionlint -no-color

À retenir

Validation instantanée

Détectez les erreurs en moins d’une seconde, avant le push.

50+ règles

Syntaxe, sécurité, types, références — tout est vérifié.

Intégration IDE

Erreurs affichées directement dans VS Code pendant l’écriture.

CI/CD ready

Formats JSON, SARIF, et intégration reviewdog pour les PRs.

Points clés :

1. Installez actionlint et utilisez-le avant chaque push
2. Intégrez-le dans VS Code pour une validation en temps réel
3. Ajoutez un workflow de lint pour valider les PRs automatiquement
4. Combinez avec act pour une validation complète
5. Configurez les règles et variables spécifiques à votre organisation

Liens utiles

• Repository actionlint sur GitHub ↗ — Documentation et règles
• Playground en ligne ↗ — Testez actionlint dans le navigateur
• act — Exécuter les workflows localement
• Épinglage SHA — Sécuriser les références d’actions
• Debug des workflows — Techniques de dépannage

×

📖 Voir la documentation →