Mettre en place une CI sur Codeberg

Introduction

Lorsque j’ai décidé de mettre en place une intégration continue (CI) sur Codeberg, je me suis retrouvé face à une situation assez classique : beaucoup de notions évoquées, mais peu d’explications réellement concrètes. On comprend globalement ce qu’est Forgejo Actions, mais rarement comment cela se traduit dans un dépôt, ni comment les différents éléments interagissent entre eux.

Cet article est né de ce constat. Son objectif est simple : expliquer de manière claire comment utiliser la CI de Codeberg pour un cas concret, la construction et la publication d’un site statique Hugo.

Ce que Codeberg propose réellement comme CI

Codeberg repose sur Forgejo et propose une CI intégrée appelée Forgejo Actions. Il n’y a aucun service externe à connecter, aucune machine à administrer, ni d’infrastructure à maintenir. La CI est disponible par défaut dès qu’un dépôt existe.

Les workflows sont exécutés sur des runners Linux mutualisés opérés par Codeberg. Ces runners sont volontairement limités en ressources et en durée d’exécution. Cette contrainte définit clairement le périmètre de la plateforme : Forgejo Actions est pensée pour des tâches simples, reproductibles et rapides.

Dans ce cadre, la génération d’un site statique s’inscrit naturellement dans les usages attendus.

Comment Codeberg détecte un workflow

Pour qu’un workflow soit exécuté, Forgejo Actions impose une règle stricte : le fichier YAML doit se trouver dans un dossier précis du dépôt.

Avec Codeberg, les workflows doivent être placés dans :

.forgejo/workflows/

Par exemple :

.forgejo/workflows/hugo.yml

Dès qu’un fichier valide est présent à cet emplacement et poussé sur le dépôt, Codeberg l’analyse automatiquement. Si des événements de déclenchement sont définis, la CI est exécutée sans aucune action supplémentaire dans l’interface.

Un pipeline parfaitement écrit mais placé ailleurs dans le dépôt ne sera jamais exécuté.

Un pipeline Hugo simple et explicite

Pour comprendre la CI de Codeberg, il est important de commencer par un pipeline volontairement simple. L’objectif n’est pas de couvrir tous les cas possibles, mais de montrer un workflow réel, lisible, et suffisant pour un site statique.

Le fichier .forgejo/workflows/hugo.yml peut par exemple contenir :

name: Build Hugo site

Cette ligne donne un nom au workflow. Il sera affiché tel quel dans l’onglet Actions du dépôt et permet d’identifier rapidement ce que fait la CI.

Les événements de déclenchement sont ensuite définis :

on:
  push:
    branches: [ main ]
  pull_request:

Le workflow est exécuté à chaque push sur la branche main, ainsi qu’à chaque pull request. Cela permet de vérifier que le site se construit correctement avant un merge et de s’assurer que la branche principale reste toujours publiable.

Le workflow définit ensuite un job unique :

jobs:
  build:

Un workflow peut contenir plusieurs jobs, mais dans ce cas un seul suffit. Le nom build est libre et sert uniquement à la lisibilité.

Le job s’exécute sur un runner Linux fourni par Codeberg :

    runs-on: ubuntu-latest

Il s’agit d’un environnement standard, mutualisé, mais suffisant pour exécuter une génération de site statique.

Les étapes du job sont ensuite décrites dans l’ordre :

    steps:
      - uses: actions/checkout@v4

Cette étape récupère le contenu du dépôt dans l’environnement du runner. Cette ligne utilise une action, c’est-à-dire un composant réutilisable du moteur Forgejo Actions utilisé par Codeberg.

Forgejo Actions reprend largement le modèle de GitHub Actions. Certaines actions connues, comme actions/checkout, fonctionnent sur Codeberg car elles sont miroitées et ne dépendent pas de services spécifiques à GitHub.

Les actions compatibles Forgejo sont principalement hébergées sur l’instance Forgejo officielle. Elles peuvent être explorées ici : https://code.forgejo.org/explore/repos

Hugo est ensuite installé explicitement :

      - name: Install Hugo
        run: sudo apt-get update && sudo apt-get install -y hugo

Il n’existe pas encore d’action Forgejo dédiée pour installer Hugo. L’installation via le gestionnaire de paquets du système est donc la solution la plus simple et la plus lisible. Elle permet de savoir exactement ce qui est installé et comment.

Enfin, la génération du site est lancée :

      - name: Build site
        run: hugo

Si cette commande échoue, le job échoue immédiatement et la CI indique clairement que le site ne peut pas être construit dans son état actuel.

Secrets : où ils sont définis

Tant que l’on se contente de construire le site, aucun secret n’est nécessaire. Les secrets interviennent uniquement au moment de la publication.

Sur Codeberg, les secrets sont définis directement dans l’interface du dépôt, et non dans le workflow. Ils sont stockés côté serveur et ne sont jamais inclus dans le code source.

Concrètement, depuis la page du dépôt, ils sont ajoutés via :

Settings → Secrets → Actions

Un secret est défini par un nom et une valeur. Le nom est visible, la valeur ne l’est plus jamais après l’enregistrement. Une fois créé, le secret est associé au dépôt et accessible uniquement lors de l’exécution d’un workflow Forgejo Actions.

Comment un secret est utilisé dans un workflow

Un secret n’est jamais injecté automatiquement. Le workflow doit décider explicitement où et comment il est utilisé.

Dans un fichier YAML, un secret est référencé via le contexte secrets. Par exemple, pour exposer une clé à une commande de déploiement :

      - name: Deploy site
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          echo "$DEPLOY_KEY" > key
          chmod 600 key
          # commandes de déploiement

La valeur du secret n’apparaît jamais dans les logs, sauf si elle est explicitement affichée. Elle n’existe que dans l’environnement du job, pendant la durée de son exécution.

Cette approche permet de séparer clairement le code versionné des informations sensibles, tout en conservant un workflow lisible.

Conclusion

La CI fournie par Codeberg est volontairement sobre, mais cohérente. Elle ne cherche pas à couvrir tous les usages possibles et s’inscrit dans un cadre clairement défini.

En comprenant où placer un workflow, comment il est déclenché, et comment les secrets sont définis et utilisés, il est possible de mettre en place une automatisation fiable, lisible et facile à maintenir pour la publication d’un site statique Hugo.