Semantic Release

Introduction au versionnement sémantique

Le versionnement sémantique (ou SemVer) est une convention de numérotation des versions qui permet de communiquer facilement la nature et l'impact des changements apportés à un projet. Selon cette convention, chaque version est composée de trois nombres : MAJOR.MINOR.PATCH.

• MAJOR : Version incrémentée pour des changements incompatibles avec les versions précédentes.
• MINOR : Version incrémentée pour l'ajout de fonctionnalités compatibles avec les versions précédentes.
• PATCH : Version incrémentée pour des corrections de bugs compatibles avec les versions précédentes.

Par exemple, la version 2.3.1 indique la deuxième version majeure, la troisième version mineure, et la première correction de bug depuis la dernière version mineure.

Qu'est-ce que Semantic Release ?

Semantic Release est un outil qui automatise entièrement le processus de versionnement et de publication de votre package. En analysant les messages de commit (suivant la convention Conventional Commits), il détermine automatiquement la prochaine version, génère des notes de version et publie la nouvelle version.

Avantages de Semantic Release

• Automatisation complète : Élimine la gestion manuelle des versions et des releases.
• Cohérence : Assure que le versionnement respecte la spécification SemVer.
• Documentation automatique : Génère automatiquement des changelogs détaillés.
• Intégration CI/CD : S'intègre parfaitement dans les pipelines d'intégration continue.

Installation et configuration de Semantic Release

Installation

npm install semantic-release @semantic-release/git @semantic-release/github @semantic-release/changelog --save-dev

Configuration

{
   "branches": [
      "main"
   ],
           "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      [
         "@semantic-release/changelog",
         {
            "changelogFile": "docs/CHANGELOG.md"
         }
      ],
      "@semantic-release/github",
      [
         "@semantic-release/git",
         {
            "assets": [
               "docs/CHANGELOG.md",
               "package.json",
               "package-lock.json"
            ]
         }
      ]
   ]
}

Explication des plugins

• commit-analyzer : Analyse les commits pour déterminer la prochaine version.
• release-notes-generator : Génère les notes de version basées sur les commits.
• changelog : Met à jour le fichier CHANGELOG.md avec les nouvelles notes de version.
• npm : Met à jour la version dans package.json
• git : Commit les fichiers mis à jour (package.json, CHANGELOG.md) et crée un tag Git.
• github : Crée une release GitHub avec les notes de version.

Intégration avec GitHub Actions

Pour automatiser le processus de release avec GitHub Actions, ajoutez un workflow spécifique dans .github/workflows/release.yml :

name: Release

on:
   push:
      branches: [main]

jobs:
   release:
      runs-on: ubuntu-latest
      permissions:
         contents: write
         packages: write
         pull-requests: write
      steps:
         - name: Generate token
           id: generate_token
           uses: actions/create-github-app-token@v1
           with:
              app-id: ${{ secrets.SEMANTIC_BOT_APP_ID }}
              private-key: ${{ secrets.SEMANTIC_BOT_PRIVATE_KEY }}

         - name: Checking out code
           uses: actions/checkout@v4
           with:
              fetch-depth: 0
              persist-credentials: true
              token: ${{ steps.generate_token.outputs.token }}

         - name: Setting up Node
           uses: actions/setup-node@v4

         - name: Install dependencies
           run: npm ci

         - name: Release
           run: npx semantic-release
           env:
              GH_TOKEN: ${{ steps.generate_token.outputs.token }}
              GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}

Étapes pour créer une GitHub App pour Semantic Release

Les branches protégées sur GitHub ajoutent une couche de sécurité à votre workflow, mais peuvent empêcher Semantic Release de fonctionner correctement car l'outil a besoin de pousser des commits et des tags directement sur vos branches protégées.

1. Créer une nouvelle GitHub App

1. Allez sur votre compte GitHub et accédez à Settings > Developer settings > GitHub Apps
2. Cliquez sur New GitHub App
3. Remplissez les informations de base :
   • GitHub App name : my-org-semantic-release (remplacez my-org par le nom de votre organisation)
   • Homepage URL : URL de votre organisation/dépôt
   • Webhook : Désactivez-le en décochant "Active" (non nécessaire pour Semantic Release)
   • Description : "GitHub App pour permettre à Semantic Release de publier sur des branches protégées"

2. Configurer les permissions requises

Dans la section Repository permissions, accordez les permissions suivantes :

• Contents : Access: Read & write (pour pousser des commits et des tags)
• Metadata : Access: Read-only
• Pull requests : Access: Read & write (si vous utilisez le plugin PR de Semantic Release)
• Issues : Access: Read & write (pour les plugins GitHub)
• Workflows : Access: Read & write (si vous utilisez des GitHub Actions)

3. Dans la section "Where can this GitHub App be installed?", choisissez :

• Only on this account (si vous souhaitez limiter l'App à votre compte)

4. Cliquez sur Create GitHub App

5. Générer une clé privée

Une fois l'App créée :

1. Faites défiler jusqu'à la section Private keys
2. Cliquez sur Generate a private key
3. Téléchargez et conservez le fichier .pem généré en lieu sûr (vous en aurez besoin plus tard)

6. Installer l'App

1. Dans la page de votre GitHub App, cliquez sur Install App
2. Choisissez les dépôts où vous souhaitez installer l'App (ou tous les dépôts)
3. Cliquez sur Install

8. Configurer les secrets GitHub

Ajoutez les secrets suivants dans votre dépôt GitHub (Settings > Secrets and variables > Actions) :

• APP_ID : L'ID de votre GitHub App (visible sur la page de l'App)
• APP_PRIVATE_KEY : Le contenu complet du fichier .pem que vous avez téléchargé (avec les lignes -----BEGIN RSA PRIVATE KEY----- et -----END RSA PRIVATE KEY-----)

Protection de branche compatible avec Semantic Release

Pour que Semantic Release fonctionne avec les branches protégées, assurez-vous que vos règles de protection incluent :

1. Allez dans Settings > Branches > Branch protection rules
2. Ajoutez ou modifiez une règle pour votre branche principale (ex. main)
3. Assurez-vous que l'option Allow specified actors to bypass required pull requests est activée
4. Ajoutez votre GitHub App dans la liste des acteurs autorisés