Pipeline CI pour collection Ansible : matrice ansible-core × Python, GitHub Actions et GitLab CI

Une collection en production se teste sur plusieurs versions d’ansible-core et de Python pour garantir la compatibilité descendante. Le pattern 2026 : GitHub Actions avec une matrice ansible-core × python, exécutant ansible-test sanity --docker + ansible-test units + ansible-lint --strict dans un Docker conforme. Avec SHA pinning des actions, permissions: {} au global, persist-credentials: false sur checkout.

Cette page fournit les deux pipelines équivalents (GitHub Actions + GitLab CI), durcis selon les pratiques 2026 (zizmor compliant), prêts à copier-coller dans votre repo de collection.

name: CI Collection
on: [push, pull_request]

permissions: {}                  # GLOBAL : aucune permission par défaut

jobs:
  test:
    runs-on: ubuntu-24.04
    permissions:
      contents: read              # MINIMAL : juste lire le code
    strategy:
      fail-fast: false
      matrix:
        ansible-core: [stable-2.18, stable-2.19, devel]
        python: ['3.11', '3.12']
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
        with:
          persist-credentials: false      # n'écrit PAS le token GitHub dans .git/

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: ${{ matrix.python }}

      - name: Install ansible-core
        run: pip install https://github.com/ansible/ansible/archive/${{ matrix.ansible-core }}.tar.gz

      - name: ansible-test sanity
        run: ansible-test sanity --docker default

      - name: ansible-test units
        run: ansible-test units --docker default

      - name: ansible-lint --strict
        run: ansible-lint --strict

Sécurité non négociable — pipeline durci 2026 :

permissions: {} au global + permissions minimales par job — principe du moindre privilège. Sans ça, un step compromis (action malveillante) a accès à TOUT (créer des release, push sur main, etc.).
Actions pinnées par SHA, pas par tag (@v4) — un attaquant qui compromet une action peut publier un nouveau v4 qui exfiltre vos secrets. Le SHA est immuable. Format actions/checkout@<SHA40> # v4.2.2.
persist-credentials: false sur actions/checkout — sinon le token GitHub atterrit dans .git/config du runner, accessible aux steps suivants.
Matrice ansible-core × python — au minimum 2 versions de chaque pour valider la compat. devel permet de détecter les breaking changes upstream avant qu’ils n’arrivent.
ansible-test sanity --docker — l’isolation Docker garantit la reproductibilité (pas de pollution depuis le runner).
Validation zizmor ou poutine du workflow YAML avant push — détecte les patterns dangereux en GitHub Actions.

Ce que vous allez apprendre

Workflow GitHub Actions complet pour collection Ansible.
Matrice ansible-core stable-2.18 × stable-2.19 × devel × Python 3.11 × 3.12.
ansible-test sanity --docker dans la CI.
ansible-test units --docker sur les modules Python.
ansible-lint --strict --profile production.
SHA pinning des actions (zizmor compliant).
Équivalent GitLab CI avec parallel:matrix.

Prérequis

Avoir une collection custom (cf Créer une collection).
Compte GitHub ou GitLab.

Workflow GitHub Actions complet

name: Ansible test
on:
  push:
    branches: [main]
  pull_request:

permissions: {}                              # ← global = aucune

jobs:
  sanity:
    name: sanity (${{ matrix.ansible }} / py${{ matrix.python }})
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    strategy:
      fail-fast: false                       # ← continue même si une combo échoue
      matrix:
        ansible:
          - stable-2.18
          - stable-2.19
          - devel
        python:
          - "3.11"
          - "3.12"
    steps:
      - name: Checkout
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.2.2
        with:
          path: ansible_collections/student/webapp
          persist-credentials: false         # ← bloque token Git

      - name: Setup Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: "${{ matrix.python }}"

      - name: Install ansible-core ${{ matrix.ansible }}
        run: |
          pip install "https://github.com/ansible/ansible/archive/${{ matrix.ansible }}.tar.gz"

      - name: ansible-test sanity --docker
        working-directory: ansible_collections/student/webapp
        run: |
          ansible-test sanity --docker default -v --color

  units:
    name: units (${{ matrix.ansible }} / py${{ matrix.python }})
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    strategy:
      fail-fast: false
      matrix:
        ansible: [stable-2.18, devel]
        python: ["3.11", "3.12"]
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.2.2
        with:
          path: ansible_collections/student/webapp
          persist-credentials: false

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: "${{ matrix.python }}"

      - run: |
          pip install "https://github.com/ansible/ansible/archive/${{ matrix.ansible }}.tar.gz"

      - name: ansible-test units --docker
        working-directory: ansible_collections/student/webapp
        run: |
          ansible-test units --docker default -v --color --python ${{ matrix.python }}

  lint:
    name: ansible-lint
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
        with:
          path: ansible_collections/student/webapp
          persist-credentials: false

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
        with: { python-version: "3.12" }

      - run: pip install ansible-lint==25.5.0 ansible-core==2.18.1

      - name: ansible-lint --strict --profile production
        working-directory: ansible_collections/student/webapp
        run: ansible-lint --strict --profile production

Bonnes pratiques 2026 visibles

Pattern	Pourquoi
`permissions: {}` au workflow	Aucune permission par défaut sur le `GITHUB_TOKEN`. Élargies par job au strict nécessaire.
`persist-credentials: false`	Bloque l’usage du token Git après checkout (évite l’exfiltration via une étape compromise).
`uses: <owner>/<repo>@<SHA40>`	Protège contre tag mutation attacks (un attaquant qui repush `v4.2.2`).
`fail-fast: false`	Continue même si une combo échoue → on voit lesquelles passent.
`path: ansible_collections/student/webapp`	Ansible-test exige cette arborescence pour fonctionner.

Pipeline GitLab CI équivalent

stages:
  - lint
  - sanity
  - units

variables:
  ANSIBLE_VERSIONS: "stable-2.18 stable-2.19 devel"
  PYTHON_VERSIONS: "3.11 3.12"

.collection_setup: &collection_setup
  before_script:
    - pip install "https://github.com/ansible/ansible/archive/${ANSIBLE_VERSION}.tar.gz"
    - mkdir -p ansible_collections/student/webapp
    - shopt -s extglob && cp -r !(ansible_collections) ansible_collections/student/webapp/
    - cd ansible_collections/student/webapp

ansible-lint:
  stage: lint
  image: python:3.12
  script:
    - pip install ansible-lint==25.5.0 ansible-core==2.18.1
    - ansible-lint --strict --profile production

sanity:
  stage: sanity
  image: python:${PYTHON_VERSION}
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.11", "3.12"]
        ANSIBLE_VERSION: ["stable-2.18", "stable-2.19", "devel"]
  <<: *collection_setup
  script:
    - ansible-test sanity --docker default -v --color

units:
  stage: units
  image: python:${PYTHON_VERSION}
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.11", "3.12"]
        ANSIBLE_VERSION: ["stable-2.18", "devel"]
  <<: *collection_setup
  script:
    - ansible-test units --docker default -v --color --python ${PYTHON_VERSION}

🔍 Observation : parallel:matrix GitLab CI donne le même effet que la matrice GitHub Actions. <<: *collection_setup factorise le before_script partagé. Résultat fonctionnellement équivalent.

Linter le workflow avec `zizmor`

zizmor .github/workflows/ansible-test.yml

Détecte automatiquement :

Actions non pinnées par SHA.
permissions: trop larges.
Variables d’env exposées sans escape.
Absence de persist-credentials: false.
Templates ${{ ... }} injectables.

🔍 Observation : zizmor est l’outil de référence 2026 pour auditer les workflows GitHub. À ajouter en pre-commit hook pour bloquer les régressions de sécurité supply-chain.

Pour aller plus loin — coverage

- name: ansible-test units --coverage
  run: |
    ansible-test units --docker default --coverage
    ansible-test coverage html
    ansible-test coverage --requirements xml

Combiner avec coverage --coverage-check pour bloquer la CI si la couverture chute sous un seuil :

ansible-test coverage check --requirements xml || exit 1

Lab pratique

Le lab collections/ci-tests (labs/collections/ci-tests/) fournit le workflow GitHub Actions et le .gitlab-ci.yml complets avec 10 tests pytest structurels (SHA pinning, permissions, persist-credentials, matrice ≥2 versions).

À retenir

Matrice ansible-core × Python = 4-6 combinaisons typiques en CI.
SHA pinning des actions GitHub (40 caractères hex), zizmor compliant.
permissions: {} au global, persist-credentials: false sur checkout.
ansible-test sanity --docker default = validation FQCN + doc + types.
ansible-test units --docker = pytest sur les modules Python.
ansible-lint --strict --profile production = qualité maximale.
Zizmor lint des workflows en pre-commit hook.

Prochaines étapes

Migration rôle → collection meta/runtime.yml plugin_routing.redirect pour rétrocompatibilité.

Vue d'ensemble Collections Retour au pivot pour relier tous les sujets de la section.

Lab 96 sur GitHub Workflow GitHub Actions + GitLab CI complets avec 10 tests pytest.