Versionner et publier un rôle Ansible : Git semver, Galaxy, Automation Hub

Une fois votre rôle stable et testé, l'étape finale est la publication : tag Git semver, CHANGELOG mis à jour, push sur Ansible Galaxy (public) ou Automation Hub (privé). Cette page couvre le workflow complet, de l'écriture du CHANGELOG à la release automatique via CI/CD.

# 1. Mettre à jour CHANGELOG.md avec les changements (Keep a Changelog)
cat >> CHANGELOG.md <<'EOF'
## [1.2.0] - 2026-04-27
### Added
- Support du paramètre `webserver_extra_modules`
### Fixed
- Idempotence cassée sur restart sans changement de conf
### Changed
- Module systemd → systemd_service (FQCN)
EOF

# 2. Tag Git semver
git tag -a v1.2.0 -m "Release v1.2.0 — extra_modules + idempotence fix"
git push origin v1.2.0

# 3. Galaxy : import automatique via webhook OU import CLI
ansible-galaxy role import stephrobert webserver --role-name webserver

# 4. CI/CD release automatique (.github/workflows/release.yml)
# - Sur push de tag v*, lance: ansible-galaxy role import

Versionnage semver :

MAJOR (1.x → 2.0) : breaking change (variable supprimée, comportement par défaut modifié, OS supporté retiré).
MINOR (1.1 → 1.2) : nouvelle feature, sans breaking.
PATCH (1.1.0 → 1.1.1) : bugfix, pas de feature.

Sécurité non négociable :

CHANGELOG.md mandatory, un rôle sans changelog = utilisateur ne sait pas ce qui change = rôle non adopté.
Tags signés (git tag -s avec clé GPG), prouve l'identité du release. À l'ère du supply chain, c'est une mesure de défense importante pour les rôles publiés.
Pas de release sans tests verts en CI, molecule test + ansible-lint --profile production doivent passer avant le tag.
JAMAIS publier le vault_* ou un .env dans le tarball Galaxy, vérifier .gitignore ET build_ignore (pour les collections) avant tag.
min_ansible_version dans meta/main.yml explicite, sinon les utilisateurs sur ansible-core 2.14 installent un rôle qui requiert 2.18 et plante au runtime.

Ce que vous allez apprendre

Workflow Git semver : MAJOR.MINOR.PATCH.
Format CHANGELOG.md Keep a Changelog.
Publication sur Ansible Galaxy (méthodes webhook GitHub et CLI).
Automation Hub privé pour entreprise.
Release automatique via CI/CD (GitHub Actions ou GitLab CI).

Convention semver pour rôles Ansible

MAJOR.MINOR.PATCH
│     │     └─ bugfix rétrocompatible (1.0.0 → 1.0.1)
│     └─────── nouvelle feature rétrocompatible (1.0.0 → 1.1.0)
└───────────── breaking change (1.0.0 → 2.0.0)

Règles :

MAJOR : variable renommée, structure cassée, suppression d'option.
MINOR : nouvelle variable optionnelle, nouvelle plateforme supportée.
PATCH : bugfix, typo, optimisation interne.

Le fichier `CHANGELOG.md`

Format Keep a Changelog (keepachangelog.com) :

# Changelog — rôle webserver

## [1.2.0] - 2026-04-26

### Added
- Support multi-distribution (RHEL, AlmaLinux, Debian via vars/<os_family>.yml)
- Variable `webserver_worker_processes` configurable
- Validation argument_specs.yml

### Changed
- Module `package` (agnostique) au lieu de `dnf` direct
- Templates Jinja réorganisés pour lisibilité

### Fixed
- Idempotence handlers (Reload nginx déclenché 2× résolu)

## [1.1.0] - 2026-03-15

### Added
- Handlers Restart nginx et Reload nginx
- Validate sur le template nginx.conf

## [1.0.0] - 2026-02-01

### Added
- Premier release stable
- Installation nginx, démarrage, ouverture firewall HTTP

Sections standard : Added, Changed, Deprecated, Removed, Fixed, Security. Toutes optionnelles selon le contenu du release.

Workflow Git semver

# 1. Mettre à jour CHANGELOG.md
vim CHANGELOG.md
# Ajouter section ## [1.2.0] - 2026-04-26

# 2. Tester (Molecule + ansible-lint)
molecule test
ansible-lint --profile=production roles/webserver/

# 3. Commit
git add CHANGELOG.md
git commit -m "release: v1.2.0"

# 4. Tag semver
git tag -a v1.2.0 -m "Release v1.2.0 - Multi-distro support"

# 5. Push
git push origin main --tags

Note : tag avec préfixe v (v1.2.0, pas 1.2.0). Convention quasi-universelle.

Publication sur Ansible Galaxy

Prérequis

Compte sur galaxy.ansible.com lié à GitHub.
Token API depuis votre profil → API Token.
meta/main.yml complet avec galaxy_info.

Méthode 1, Via GitHub Webhook (rôles)

Sur Galaxy, My Content → Add Content → Import Role from GitHub.
Sélectionner le repo stephrobert/ansible-role-webserver.
Galaxy importe automatiquement à chaque nouveau tag Git semver.

Pas besoin de CLI, workflow GitOps natif.

Méthode 2, CLI (collections)

# Build la collection (génère .tar.gz)
cd path/to/collection/
ansible-galaxy collection build

# Publier sur Galaxy
ansible-galaxy collection publish \
  stephrobert-networking-1.0.0.tar.gz \
  --api-key=$GALAXY_TOKEN

Token disponible dans variables d'env CI/CD (ANSIBLE_GALAXY_TOKEN).

Automation Hub privé (entreprise)

Pour les entreprises qui ne veulent pas exposer leurs rôles publiquement :

# ansible.cfg
[galaxy]
server_list = corporate_hub

[galaxy_server.corporate_hub]
url = https://hub.corp.example.com/api/automation-hub/
token = <token>

Avantages Automation Hub :

Privé : code interne non exposé sur Galaxy public.
Certifié Red Hat : collections supportées commercialement.
Allow-list : votre équipe sécurité valide chaque collection avant publication.
Mirror : réplique Galaxy public pour usage offline.

Release automatique via CI/CD

GitHub Actions

name: Release to Galaxy

on:
  push:
    tags: ['v*.*.*']

jobs:
  release:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@<SHA>
        with:
          persist-credentials: false

      - name: Build and publish collection
        run: |
          ansible-galaxy collection build
          ansible-galaxy collection publish *.tar.gz \
            --api-key=${{ secrets.GALAXY_TOKEN }}

Token GitHub Secrets = GALAXY_TOKEN configuré dans Settings → Secrets.

GitLab CI

# .gitlab-ci.yml (extrait)
release:
  stage: release
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  script:
    - ansible-galaxy collection build
    - ansible-galaxy collection publish *.tar.gz --api-key=$GALAXY_TOKEN

Token GitLab Variables = GALAXY_TOKEN (Masked + Protected).

Communication post-release

`README.md` à jour

Variables nouvelles, exemples mis à jour. Pas de drift entre code et doc.

Release notes GitHub

Sur GitHub, Releases → Create a new release depuis le tag. Reprendre le contenu du CHANGELOG section correspondante.

Migration guide pour breaking change

Si MAJOR bump : ajouter un fichier MIGRATION.md qui détaille les changements et le pattern de migration pour les utilisateurs.

# Migration guide

## v1.x → v2.0

### Variable renommée

`webserver_port` → `webserver_listen_port`

Fix automatique :

```bash
sed -i 's/webserver_port/webserver_listen_port/g' playbooks/*.yml

## Pratiquer dans le lab

Cette page a un **lab d'accompagnement** : **`labs/galaxy/versionner-publier/`** dans
[stephrobert/ansible-training](https://github.com/stephrobert/ansible-training).

Le lab fournit `CHANGELOG.md` (3 versions semver) + `PUBLISH.md` (workflow complet). **7 tests structure** validés.

```bash
cd ~/Projets/ansible-training/labs/galaxy/versionner-publier/

cat CHANGELOG.md
cat PUBLISH.md
pytest -v challenge/tests/             # 7 tests

Pièges courants

Symptôme	Cause	Fix
Tag pushé mais Galaxy n'importe pas	Webhook GitHub désactivé	Galaxy → Imports → re-trigger manuel
`ansible-galaxy collection publish` échoue	Token expiré	Régénérer sur galaxy.ansible.com
Breaking change non signalé	Pas de bump MAJOR	Toujours bump MAJOR + MIGRATION.md
Versions incohérentes entre code et tag	Pas de single source of truth	Mettre la version dans `meta/main.yml` ET tag Git
Release sur Galaxy privée mais code sur GitHub public	Configuration mixte	Cohérent : code privé → Hub privé, code public → Galaxy public

À retenir

Semver MAJOR.MINOR.PATCH = breaking, feature, bugfix.
Tag Git v1.2.0 + CHANGELOG.md Keep a Changelog.
Publication Galaxy : webhook GitHub (rôles) ou CLI (collections).
Automation Hub privé pour entreprise (privé, certifié Red Hat).
Release automatique via CI/CD (GitHub Actions / GitLab CI) sur tag.
MIGRATION.md mandatory sur tout breaking change.

Prochaines étapes

Pivot Roles Retour à la vue d'ensemble, vous avez fini la section !

Auditer un rôle existant Pour les utilisateurs qui adoptent VOS rôles publiés

Vault Ansible Section suivante, gérer les secrets dans vos rôles publiés

Intégration CI GitHub Actions Automatiser la release avec GitHub Actions