actionlint : valider vos workflows GitHub Actions

Mise à jour : 23/12/2025

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

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

Avec Homebrew :

brew install actionlint

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

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

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

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

Ouvrez VS Code
Extensions → Recherchez “actionlint”
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-latest
    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-latest
    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 ↗ :

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 :

actionlint : validation statique (syntaxe, types, références)
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 :

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 :

Installez actionlint et utilisez-le avant chaque push
Intégrez-le dans VS Code pour une validation en temps réel
Ajoutez un workflow de lint pour valider les PRs automatiquement
Combinez avec act pour une validation complète
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