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.

Pressé ? Le workflow de release semver

# 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

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

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

1. Sur Galaxy, My Content → Add Content → Import Role from GitHub.
2. Sélectionner le repo stephrobert/ansible-role-webserver.
3. 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

.github/workflows/release.yml

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

Glissez pour voir

À 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

×

📖 Voir la documentation →