Ansible-lint : valider et améliorer votre code Ansible

Ansible-lint analyse vos playbooks, rôles et collections pour détecter les erreurs avant l’exécution, appliquer les bonnes pratiques et corriger automatiquement de nombreux problèmes. C’est l’outil indispensable pour maintenir un code Ansible de qualité, utilisé notamment par Ansible Galaxy pour calculer les scores de qualité.

À qui sert cette page ?

Débutants : suivez Quickstart → profil basic → correction automatique. Intermédiaires : configurez .ansible-lint, intégrez dans votre CI/CD. Experts : créez vos propres règles, visez le profil production.

Quickstart en 2 minutes

pipx (recommandé)

pipx install ansible-lint
ansible-lint --version

Avantage : environnement isolé, indépendant de votre version d’Ansible.

pip

pip install "ansible-lint[yamllint]"
ansible-lint --version

Le paquet optionnel yamllint active les règles de formatage YAML.

uv (rapide)

uv tool install ansible-lint
ansible-lint --version

uv est le gestionnaire de paquets Python le plus rapide.

# Lancer sur un playbook
ansible-lint playbook.yml

# Lancer sur tout le projet (auto-détection)
ansible-lint

# Corriger automatiquement ce qui peut l'être
ansible-lint --fix

Code de sortie

• 0 : aucune erreur
• 2 : erreurs détectées
• 8 : erreurs corrigées avec succès (v26+)

Ce qu’Ansible-lint détecte (et ce qu’il ne fait pas)

Ansible-lint fait	Ansible-lint ne fait pas
Détecte les erreurs de syntaxe	N’exécute pas les playbooks
Applique les bonnes pratiques	Ne remplace pas les tests d’intégration
Corrige automatiquement (—fix)	Ne corrige pas les erreurs de logique
Valide les schémas (meta, galaxy.yml)	Ne vérifie pas les cibles distantes

Glissez pour voir

Modèle mental

Ansible-lint = votre relecteur automatique. Il vérifie que votre code respecte les conventions et les bonnes pratiques avant que vous ne l’exécutiez sur de vraies machines. C’est comme un correcteur orthographique pour le code.

Les 6 profils (de permissif à strict)

Les profils permettent une adoption progressive : commencez permissif, durcissez au fil du temps. Chaque profil inclut les règles du profil précédent.

Profil	Objectif	Quand l’utiliser
min	Ansible peut charger le fichier	Débogage, code legacy
basic	Style cohérent, erreurs courantes	Début de projet
moderate	Lisibilité (noms, casing)	Équipe établie
safety	Sécurité et idempotence	Pré-production
shared	Prêt pour Galaxy/publication	Rôles/collections publics
production	Certifié Ansible Automation Platform	Entreprise

Glissez pour voir

# Voir tous les profils et leurs règles
ansible-lint --list-profiles

# Appliquer un profil spécifique
ansible-lint --profile=basic playbook.yml

# Vérifier quel profil passe
ansible-lint playbook.yml
# Sortie : "Last profile that met the validation criteria was 'safety'"

Stratégie d'adoption

1. Commencez avec --profile=basic
2. Corrigez les erreurs (utilisez --fix pour automatiser)
3. Montez progressivement vers moderate puis safety
4. Visez production pour les projets critiques

Configuration avec .ansible-lint

Créez un fichier .ansible-lint à la racine de votre projet :

.ansible-lint

---
profile: moderate

# Exclure des chemins
exclude_paths:
  - .cache/
  - .git/
  - molecule/

# Ignorer certaines règles
skip_list:
  - no-changed-when  # Trop de faux positifs sur nos scripts

# Afficher en warning au lieu d'erreur
warn_list:
  - experimental
  - fqcn[deep]

# Activer des règles opt-in
enable_list:
  - yaml
  - no-log-password
  - empty-string-compare

# Mode hors ligne (pas de téléchargement de requirements.yml)
offline: false

# Pattern pour les noms de variables
var_naming_pattern: "^[a-z_][a-z0-9_]*$"

# Préfixe pour les variables de boucle dans les rôles
loop_var_prefix: "^(__|{role}_)"

Emplacement du fichier

Le fichier doit être à la racine du projet. Ansible-lint cherche aussi dans .config/ansible-lint.yml. Lancez toujours ansible-lint depuis la racine du projet.

Correction automatique avec —fix

L’option --fix corrige automatiquement de nombreuses erreurs. C’est la fonctionnalité la plus utile pour gagner du temps.

Règles auto-corrigibles

Règle	Ce qui est corrigé
fqcn	command: → ansible.builtin.command:
name	this task → This task (majuscule)
yaml	Formatage YAML (indentation, espaces)
no-free-form	Syntaxe libre → syntaxe structurée
key-order	Réordonne les clés selon la convention
jinja	{{var}} → {{ var }} (espaces)
no-jinja-when	when: "{{ }}" → when: sans Jinja
partial-become	Ajoute become: true manquant

Glissez pour voir

Exemples pratiques

# Corriger tout le projet
ansible-lint --fix

# Corriger uniquement les FQCN
ansible-lint --fix=fqcn

# Corriger plusieurs règles spécifiques
ansible-lint --fix=fqcn,name,yaml

# Ne rien corriger (désactiver les transforms)
ansible-lint --fix=none

Avant / Après

Avant correction :

---
- hosts: all
  gather_facts: no
  tasks:
    - name: install package
      apt:
        name: nginx
        state: present

Après ansible-lint --fix :

---
- hosts: all
  gather_facts: false
  tasks:
    - name: Install package
      ansible.builtin.apt:
        name: nginx
        state: present

Corrections appliquées :

• no → false (yaml[truthy])
• install → Install (name[casing])
• apt: → ansible.builtin.apt: (fqcn)

Ignorer des règles spécifiques

Méthode 1 : commentaire noqa (pour une tâche)

- name: Clone repository without using git module  # noqa: command-instead-of-module
  ansible.builtin.command: git clone https://example.com/repo
  changed_when: false

# Ignorer plusieurs règles
- name: Risky but necessary  # noqa: risky-shell-pipe no-changed-when
  ansible.builtin.shell: cat /etc/passwd | grep root

Méthode 2 : fichier .ansible-lint-ignore (pour un fichier)

# Générer automatiquement le fichier d'ignore
ansible-lint --generate-ignore

Contenu généré :

.ansible-lint-ignore

playbook-legacy.yml command-instead-of-module
playbook-legacy.yml fqcn[action-core]
playbook-legacy.yml no-changed-when

Adoption progressive

Utilisez --generate-ignore pour introduire ansible-lint sur un projet existant sans tout casser. Les violations connues sont ignorées, mais toute nouvelle violation est détectée.

Méthode 3 : tag skip_ansible_lint (legacy)

- name: Task à ignorer complètement
  ansible.builtin.git:
    repo: https://example.com/repo
    dest: /tmp/repo
  tags:
    - skip_ansible_lint

Préférez noqa

Le tag skip_ansible_lint ignore toutes les règles sur la tâche. Préférez # noqa: rule-id pour être explicite.

Intégration CI/CD

Pre-commit

.pre-commit-config.yaml

---
repos:
  - repo: https://github.com/ansible/ansible-lint
    rev: v26.1.1
    hooks:
      - id: ansible-lint
        # Si vous utilisez des collections externes :
        # additional_dependencies:
        #   - ansible

# Installer pre-commit
pip install pre-commit
pre-commit install

# Exécuter manuellement
pre-commit run ansible-lint --all-files

GitHub Actions

.github/workflows/lint.yml

name: Ansible Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Run ansible-lint
        uses: ansible/ansible-lint@main
        # with:
        #   args: "--profile=production"

Formats de sortie

Pour les CI/CD, utilisez le format SARIF pour une intégration riche :

ansible-lint --format=sarif --sarif-file=results.sarif

GitLab CI

.gitlab-ci.yml

ansible-lint:
  image: python:3.12-slim
  stage: lint
  before_script:
    - pip install ansible-lint
  script:
    - ansible-lint --profile=moderate
  rules:
    - changes:
        - "**/*.yml"
        - "**/*.yaml"

Créer vos propres règles

Pour des besoins spécifiques à votre organisation, créez des règles personnalisées :

rules/no_hardcoded_passwords.py

from ansiblelint.rules import AnsibleLintRule

class NoHardcodedPasswords(AnsibleLintRule):
    id = "custom-no-passwords"
    shortdesc = "Ne pas hardcoder de mots de passe"
    description = "Les mots de passe doivent venir de variables ou vault"
    tags = ["security", "custom"]

    def matchtask(self, task, file=None):
        for key in ["password", "passwd", "secret"]:
            if key in str(task.get("ansible.builtin.user", {})):
                value = task["ansible.builtin.user"].get(key, "")
                if not value.startswith("{{"):
                    return True
        return False

# Utiliser avec les règles par défaut
ansible-lint -R -r ./rules/

# Utiliser uniquement vos règles
ansible-lint -r ./rules/

Dépannage

Problème	Cause probable	Solution
No such file or directory	Chemin invalide	Lancer depuis la racine du projet
Syntax check failed	Erreur YAML	Corriger la syntaxe avec yamllint
Unable to resolve FQCN	Collection manquante	Installer avec ansible-galaxy collection install
Too many violations	Projet legacy	Utiliser --generate-ignore pour démarrer
Pre-commit échoue	Collections non trouvées	Ajouter additional_dependencies: [ansible]
Faux positifs sur no-changed-when	Commands idempotentes	Ajouter # noqa: no-changed-when avec commentaire

Glissez pour voir

Lister les règles et tags disponibles

# Toutes les règles
ansible-lint --list-rules

# Toutes les règles avec leurs tags
ansible-lint -T

# Uniquement certains tags
ansible-lint -t idempotency playbook.yml
ansible-lint -t security playbook.yml

# Exclure certains tags
ansible-lint -x formatting,metadata playbook.yml

À retenir

1. ansible-lint --fix corrige automatiquement FQCN, casing, YAML et autres problèmes — utilisez-le systématiquement
2. 6 profils de min à production — commencez avec basic, montez progressivement
3. .ansible-lint centralise la configuration — committez ce fichier
4. # noqa: rule-id ignore une règle sur une ligne — préférez cette syntaxe à skip_list
5. --generate-ignore génère un fichier d’ignore pour le code legacy — permet l’adoption progressive
6. Intégrez en CI/CD avec pre-commit ou GitHub Actions — détectez les erreurs avant le merge
7. Le code de sortie 8 (v26+) indique que des corrections ont été appliquées avec succès
8. Exécutez toujours depuis la racine du projet, sinon ansible-lint ne trouvera pas les fichiers

Prochaines étapes

Molecule Testez vos rôles dans des conteneurs

Collections Ansible Organisez et partagez vos rôles

Documentation ansible-lint Référence officielle complète

×

📖 Voir la documentation →