Gitea Actions : CI/CD compatible GitHub — tutoriel 2026

Introduction

Vous avez installé Gitea ou Forgejo sur votre propre serveur, vos dépôts sont hébergés localement, et maintenant la question inévitable se pose : comment automatiser les tests, la compilation et le déploiement sans dépendre d’une plateforme externe ? GitHub Actions a habitué une génération de développeurs à une syntaxe YAML déclarative, lisible, et réutilisable. La bonne nouvelle, c’est que Gitea a intégré depuis la version 1.19 un moteur d’automatisation qui parle exactement le même langage : Gitea Actions.

Gitea Actions reproduit fidèlement la syntaxe des workflows GitHub Actions — les mêmes clés on:, jobs:, steps:, uses: — tout en s’appuyant sur des runners auto-hébergés que vous déployez sur vos propres machines. Il n’y a aucun cloud tiers impliqué, aucun quota de minutes à surveiller, et aucune donnée de code source qui quitte votre infrastructure. Pour une PME en Afrique de l’Ouest soucieuse de souveraineté numérique et de maîtrise des coûts, c’est un argument décisif.

Ce tutoriel vous guide pas à pas : activation de la fonctionnalité dans l’interface d’administration, installation du daemon act_runner, enregistrement du runner auprès de votre instance, écriture de votre premier workflow CI, puis montée en compétences sur le cache, les secrets, la réutilisation des actions de la marketplace GitHub, et la gestion de plusieurs runners avec labels. Une section dédiée aborde les optimisations spécifiques au contexte réseau ouest-africain — bande passante 4G limitée, registre Docker interne, déploiement SSH via Tailscale/Headscale. Durée estimée pour l’installation complète : trente minutes sur un serveur déjà opérationnel.

Prérequis

Avant de commencer, vérifiez que les éléments suivants sont en place. L’absence de l’un d’eux bloquera certaines étapes sans message d’erreur explicite, ce qui rend le diagnostic difficile a posteriori.

• Gitea 1.21+ ou Forgejo 7.0+ installé et accessible via HTTPS. Les versions antérieures disposaient d’une implémentation expérimentale d’Actions ; à partir de la 1.21, la fonctionnalité est considérée stable et activée par défaut en configuration. Vérifiez votre version dans Administration du site → Informations sur le serveur.
• Docker Engine 24+ sur la machine qui hébergera le runner. Le runner act_runner utilise Docker pour isoler chaque job dans un conteneur éphémère. Si vous préférez ne pas utiliser Docker (runner host), c’est possible mais déconseillé en production car les jobs s’exécutent directement sur le système hôte sans isolation.
• Accès SSH ou console sur le serveur Gitea pour modifier le fichier de configuration app.ini.
• Compte administrateur Gitea pour générer le token d’enregistrement du runner.
• ~30 minutes de temps et une connexion stable (même 4G) pour télécharger l’image act_runner et l’image de base du workflow.

Étape 1 — Activer Actions dans Gitea

Par défaut, Gitea 1.21+ active Actions au niveau du moteur, mais la fonctionnalité doit être explicitement autorisée dans le fichier de configuration principal avant qu’elle apparaisse dans l’interface. Sans cette étape, l’onglet Actions reste invisible dans les dépôts, et les runners ne peuvent pas s’enregistrer.

Ouvrez le fichier /etc/gitea/app.ini (ou le chemin défini lors de votre installation) et ajoutez ou modifiez la section suivante :

[actions]
ENABLED = true
; Durée maximale d'un job en minutes (défaut : 180)
DEFAULT_ACTIONS_URL = https://gitea.com

La clé DEFAULT_ACTIONS_URL indique à Gitea où chercher les actions référencées par uses: lorsqu’elles ne sont pas préfixées d’une URL absolue. Par défaut, la valeur pointe vers gitea.com ; vous pouvez la remplacer par https://github.com si vos workflows réutilisent massivement des actions de la marketplace GitHub (nous y reviendrons à l’étape 6). Après modification, redémarrez le service : systemctl restart gitea. Connectez-vous ensuite en administrateur, naviguez vers Administration du site → Runners — la page doit maintenant être accessible et afficher « Aucun runner enregistré ».

Vous pouvez également activer ou désactiver Actions par organisation ou par dépôt depuis les paramètres correspondants dans l’interface web, ce qui permet un déploiement progressif sans tout activer d’un coup.

Étape 2 — Installer act_runner

act_runner est le daemon officiel de Gitea qui exécute les jobs définis dans vos workflows. Il s’inspire du projet nektos/act (qui permet d’exécuter des GitHub Actions localement) mais a été adapté pour communiquer avec l’API de Gitea. La version de référence au moment de cet article est la v0.2.11, disponible sur gitea.com/gitea/act_runner/releases.

Sur le serveur qui hébergera le runner (qui peut être le même serveur que Gitea, ou une machine dédiée), téléchargez le binaire correspondant à votre architecture :

# Pour Linux x86-64
wget -O /usr/local/bin/act_runner \
  https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
chmod +x /usr/local/bin/act_runner

# Vérification
act_runner --version
# Sortie attendue : act_runner version 0.2.11

Le binaire est autonome (statiquement lié) : il n’a pas besoin de dépendances supplémentaires autre que Docker pour l’isolation des jobs. Si votre serveur est en ARM (Raspberry Pi, certains VPS ARM comme Ampere sur OCI Free Tier), remplacez amd64 par arm64 dans l’URL. Une fois le binaire installé, générez un fichier de configuration par défaut que vous ajusterez :

act_runner generate-config > /etc/act_runner/config.yaml

Créez le répertoire /etc/act_runner si nécessaire (mkdir -p /etc/act_runner). Le fichier généré contient des commentaires détaillés pour chaque paramètre ; les sections les plus importantes sont runner.capacity (nombre de jobs parallèles, à calibrer selon votre RAM disponible) et container.network (réseau Docker utilisé par les conteneurs des jobs).

Étape 3 — Enregistrer le runner

L’enregistrement crée une relation de confiance entre votre instance Gitea et le daemon act_runner. Gitea émet un token d’enregistrement à usage unique ; le runner s’en sert pour obtenir un token long-terme (stocké localement dans .runner) qui sera utilisé pour toutes les communications ultérieures. Il existe trois portées d’enregistrement : instance (tous les dépôts), organisation, ou dépôt.

Dans l’interface Gitea, rendez-vous à Administration du site → Runners → Créer un runner pour un runner d’instance, ou Paramètres de l’organisation → Runners pour un runner limité à une organisation. Copiez le token affiché — il expire après 24 heures. Puis sur le serveur du runner :

act_runner register \
  --no-interactive \
  --instance https://git.mondomaine.sn \
  --token VOTRE_TOKEN_ICI \
  --name runner-prod-01 \
  --labels ubuntu-22.04:docker://node:20-bookworm-slim,ubuntu-latest:docker://node:20-bookworm-slim

Décortiquons les options importantes. Le paramètre --instance doit être l’URL HTTPS complète de votre Gitea, accessible depuis le serveur du runner (attention si les deux machines sont sur le même réseau privé — utilisez l’IP locale ou le nom DNS interne). Le paramètre --labels déclare les étiquettes auxquelles ce runner répond : dans l’exemple, on déclare deux labels (ubuntu-22.04 et ubuntu-latest) tous deux mappés sur l’image Docker node:20-bookworm-slim. Cette image légère (~180 Mo) convient à la plupart des projets Node.js, Python et Go. Si l’enregistrement réussit, un fichier .runner est créé dans le répertoire courant — sauvegardez-le, il contient le token long-terme.

Créez maintenant un service systemd pour lancer le runner automatiquement :

[Unit]
Description=Gitea act_runner
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=git
WorkingDirectory=/var/lib/act_runner
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enregistrez ce fichier dans /etc/systemd/system/act_runner.service, puis activez-le : systemctl daemon-reload && systemctl enable --now act_runner. Vérifiez l’état avec systemctl status act_runner : vous devez voir active (running). Dans l’interface Gitea, le runner apparaît maintenant dans la liste avec un indicateur vert.

Étape 4 — Premier workflow .gitea/workflows/ci.yml

Il est temps d’écrire le premier workflow. Gitea Actions cherche les fichiers de workflow dans le répertoire .gitea/workflows/ à la racine du dépôt, avec les extensions .yml ou .yaml. La syntaxe est identique à celle de GitHub Actions, ce qui signifie que vous pouvez copier-coller un workflow existant de GitHub et l’adapter en changeant uniquement le label du runner dans la clé runs-on.

Voici un exemple pour un projet Node.js qui installe les dépendances, lance les tests et produit un artefact de build. Créez le fichier .gitea/workflows/ci.yml dans votre dépôt :

name: CI Node.js

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-22.04   # doit correspondre à un label de votre runner
    steps:
      - name: Checkout du code
        uses: actions/checkout@v4

      - name: Installer Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Installer les dépendances
        run: npm ci

      - name: Lancer les tests
        run: npm test

      - name: Build de production
        run: npm run build

      - name: Uploader les artefacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-${{ github.sha }}
          path: dist/
          retention-days: 7

Commitez et poussez ce fichier. Dans l’onglet Actions de votre dépôt Gitea, vous verrez immédiatement une exécution démarrer. Le runner va d’abord tirer l’image Docker déclarée dans son label (node:20-bookworm-slim), puis exécuter chaque step dans un conteneur éphémère. La première exécution est plus longue car l’image doit être téléchargée depuis Docker Hub — les exécutions suivantes bénéficient du cache Docker local sur le serveur du runner. Notez que la clé uses: actions/checkout@v4 fait référence à l’action officielle de GitHub : Gitea va la résoudre via la valeur de DEFAULT_ACTIONS_URL configurée à l’étape 1.

Étape 5 — Cache de dépendances et secrets

Sans cache, chaque exécution de CI réinstalle toutes les dépendances depuis Internet — une opération qui peut prendre plusieurs minutes et consomme de la bande passante. Gitea Actions supporte l’action actions/cache@v3 (et v4) avec la même syntaxe que GitHub, mais le stockage du cache est local sur votre instance, pas dans le cloud de GitHub.

Pour activer le cache dans votre workflow Node.js, modifiez l’étape d’installation comme suit :

      - name: Cache npm
        uses: actions/cache@v3
        with:
          path: ~/.npm
          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            npm-${{ runner.os }}-

      - name: Installer les dépendances
        run: npm ci

La clé de cache est construite à partir du hash du fichier package-lock.json : si ce fichier ne change pas entre deux runs, le cache est réutilisé et npm ci ne fait que vérifier l’intégrité sans retélécharger. Si le fichier change (nouvelle dépendance, mise à jour), la clé change et npm retélécharge depuis npm registry. Le stockage du cache est géré par Gitea dans son répertoire de données (data/actions-cache/) — prévoyez un disque suffisant si votre équipe a de nombreux dépôts actifs.

Pour les secrets (tokens d’API, mots de passe de base de données, clés SSH), ne les inscrivez jamais en clair dans les fichiers YAML. Gitea propose une interface de gestion des secrets identique à GitHub : rendez-vous dans Paramètres du dépôt → Actions → Secrets (ou au niveau organisation/instance pour des secrets partagés). Ajoutez par exemple un secret REGISTRY_PASSWORD. Dans le workflow, référencez-le via :

      - name: Login registry Docker
        run: echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login registry.mondomaine.sn -u ci-bot --password-stdin

Les secrets sont chiffrés au repos dans la base de données Gitea et masqués dans les logs d’exécution — si un step tente d’afficher la valeur, elle apparaît sous forme de ***. Les variables d’environnement (Variables, distinctes des secrets) fonctionnent de la même façon mais leur valeur est visible dans les logs, réservez-les aux données non sensibles comme les URLs ou les noms d’environnement.

Étape 6 — Réutiliser les actions de la marketplace GitHub

L’un des atouts les plus puissants de Gitea Actions est sa compatibilité avec l’écosystème d’actions publiées sur GitHub. Des milliers d’actions existent pour des tâches courantes : configurer une version de langage (actions/setup-python, actions/setup-go), interagir avec un registre de conteneurs (docker/build-push-action), déployer sur un hébergeur cloud, ou envoyer des notifications. Gitea peut les utiliser directement.

Le mécanisme est le suivant : quand votre workflow contient uses: actions/checkout@v4, Gitea résout cette référence en allant chercher le dépôt actions/checkout sur l’URL définie par DEFAULT_ACTIONS_URL dans app.ini. Si cette URL vaut https://github.com, Gitea clone le dépôt de l’action depuis GitHub à la version spécifiée (v4) et l’exécute dans le conteneur du job. Pour maximiser la compatibilité, positionnez :

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com

Attention : cela crée une dépendance à GitHub pour la résolution des actions. Si GitHub est lent ou inaccessible depuis votre datacenter (situation rare mais possible), vos CI échouent. La solution professionnelle est de mirorer les actions dont vous dépendez sur votre propre instance Gitea et de les référencer par leur URL complète : uses: https://git.mondomaine.sn/mirror/checkout@v4. Vous pouvez automatiser ce mirroring via les fonctionnalités de miroir intégrées à Gitea (Administration → Dépôts miroirs). Pour un premier déploiement, pointer sur GitHub est acceptable ; prévoyez le mirroring avant de passer en production critique.

Exemple d’utilisation de l’action officielle Docker Build Push pour construire et pousser une image vers votre registre privé :

      - name: Build et push image Docker
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: registry.mondomaine.sn/mon-app:${{ github.sha }}
          cache-from: type=registry,ref=registry.mondomaine.sn/mon-app:cache
          cache-to: type=registry,ref=registry.mondomaine.sn/mon-app:cache,mode=max

Étape 7 — Multi-runners avec labels

Un seul runner convient pour une petite équipe, mais dès que plusieurs projets lancent des CI en parallèle ou que vous avez besoin d’environnements différents (un runner pour les projets Node.js, un autre avec GPU pour les tâches d’IA, un troisième en ARM pour tester les builds embarqués), les labels permettent de router les jobs vers le bon runner.

Chaque runner peut porter plusieurs labels, déclarés lors de l’enregistrement ou modifiables dans l’interface Gitea (Administration → Runners → éditer). Dans vos workflows, la clé runs-on doit correspondre à au moins un label déclaré par un runner disponible. Gitea sélectionne automatiquement un runner idle parmi ceux qui ont le label requis — c’est un load-balancing simple mais efficace.

Pour enregistrer un second runner dédié aux builds Docker lourds avec un label spécifique :

act_runner register \
  --no-interactive \
  --instance https://git.mondomaine.sn \
  --token VOTRE_TOKEN_ICI \
  --name runner-docker-heavy \
  --labels docker-heavy:docker://ubuntu:22.04

Dans le workflow qui nécessite ce runner puissant :

jobs:
  build-image:
    runs-on: docker-heavy
    steps:
      # ...

Les runners déclarés avec plusieurs labels permettent aussi de simuler les environnements GitHub Actions : déclarez un label ubuntu-latest sur votre runner principal pour que les workflows copiés depuis GitHub fonctionnent sans modification de la clé runs-on. Vous pouvez également définir des labels personnalisés comme production ou staging pour restreindre les déploiements à des runners précis positionnés dans les bons réseaux.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Déployer un pipeline CI/CD en Afrique de l’Ouest impose de repenser certaines hypothèses qui vont de soi dans un datacenter européen. La bande passante mobile 4G est souvent la seule option fiable pour les équipes décentralisées, et les téléchargements répétés de packages npm ou d’images Docker peuvent rapidement devenir coûteux et lents. Voici trois axes d’optimisation concrets.

Runner local pour économiser la bande passante. Installez le runner sur la même machine (ou le même réseau local) que votre instance Gitea. Ainsi, la communication entre Gitea et le runner passe par le réseau local (latence < 1 ms, bande passante illimitée) plutôt que par Internet. Combinez cela avec un proxy de cache npm (par exemple Verdaccio) ou un miroir PyPI local pour que les dépendances soient téléchargées une seule fois et servies depuis le LAN pour tous les projets. Configurez la variable d’environnement dans votre workflow : env: NPM_CONFIG_REGISTRY: http://192.168.1.50:4873. Le gain est spectaculaire : un npm ci qui prenait 4 minutes sur une 4G partagée tombe à 20 secondes depuis le cache local.

Registre Docker interne avec Distribution Registry. Plutôt que de pousser les images construites vers Docker Hub (qui nécessite une connexion Internet sortante rapide), déployez un registre Docker privé sur votre réseau local avec Distribution (anciennement Docker Registry v2). Configurez vos workflows pour pousser vers registry.lan:5000/mon-app:sha. Vos serveurs de déploiement, sur le même réseau, tirent les images depuis ce registre interne. Le flux de données entre CI et déploiement reste entièrement dans votre infrastructure — seul le code source initial arrive depuis Internet.

Déploiement SSH via Tailscale Headscale. Déployer depuis un runner CI vers un serveur de production nécessite un accès SSH sécurisé. Plutôt que d’exposer le port SSH sur Internet (risque de sécurité) ou de gérer un VPN classique (complexe), utilisez Tailscale avec votre propre serveur de coordination Headscale auto-hébergé. Chaque machine (runner CI, serveur de production) rejoint votre réseau Tailscale et obtient une IP stable dans la plage 100.x.y.z. Le workflow de déploiement utilise ensuite simplement ssh deploy@100.64.0.10 'docker pull ... && docker compose up -d' sans aucune exposition publique. Headscale étant auto-hébergé, il n’y a pas de dépendance aux serveurs de coordination de Tailscale Inc. — votre réseau reste opérationnel même en cas de défaillance du service cloud.

Tutoriels frères

• Installer Gitea ou Forgejo sur VPS Ubuntu 22.04 — tutoriel 2026 — démarrez ici si votre forge n’est pas encore en place : HTTPS, reverse proxy Caddy, sauvegarde automatique.
• GitLab CE : configurer les runners Docker en self-hosted — tutoriel 2026 — l’équivalent de ce tutoriel pour GitLab CI/CD, avec comparaison de la syntaxe YAML.

Pour aller plus loin

• Retour au pilier : Forge Git self-hosted pour équipe PME : Gitea, Forgejo, GitLab CE (2026)
• Documentation officielle Gitea Actions : docs.gitea.com/usage/actions/overview — référence complète sur les déclencheurs, les contextes, les variables et la configuration du runner.
• Releases act_runner : gitea.com/gitea/act_runner/releases — notes de version, binaires et changelogs.
• nektos/act — github.com/nektos/act — outil complémentaire pour tester vos workflows GitHub Actions localement avant de les pousser, sans consommer de minutes CI.
• Tutoriel suivant suggéré : Gitea Packages Registry : héberger npm, Docker et PyPI en interne — tutoriel 2026 — combiner le registre de paquets de Gitea avec votre CI pour des workflows entièrement offline.

FAQ

Q : Gitea Actions est-il vraiment 100 % compatible avec GitHub Actions ?

R : La compatibilité est très élevée pour la grande majorité des cas courants — syntaxe YAML, contextes (github.*, env.*, secrets.*), expressions (${{ }}), actions uses:. Quelques fonctionnalités avancées de GitHub Actions ne sont pas encore implémentées ou se comportent différemment : les reusable workflows (workflows appelant d’autres workflows) étaient en cours d’implémentation à la date de rédaction, et certains contextes spécifiques à l’environnement GitHub (github.event.deployment, etc.) n’ont pas d’équivalent. Consultez docs.gitea.com/usage/actions/comparison pour le tableau de compatibilité à jour.

Q : Puis-je utiliser Gitea Actions avec Forgejo ?

R : Oui. Forgejo est un fork de Gitea qui a maintenu la compatibilité avec le système Actions et act_runner. Les workflows et la procédure d’installation décrite dans ce tutoriel fonctionnent de manière identique sur Forgejo 7.0+. Forgejo dispose de sa propre page de documentation sur les Actions : forgejo.org/docs/latest/user/actions/.

Q : Le runner doit-il être sur le même serveur que Gitea ?

R : Non, ce n’est pas obligatoire. Le runner communique avec Gitea via des requêtes HTTP(S) sortantes — il poll l’instance Gitea pour obtenir les jobs en attente. Vous pouvez donc installer plusieurs runners sur des machines complètement différentes, y compris des machines de bureau dans vos bureaux ou des VPS dans une région différente. La seule exigence est que le runner puisse atteindre l’URL HTTPS de votre instance Gitea. En Afrique de l’Ouest, colocaliser le runner et Gitea sur le même VPS (2-4 vCPU, 4-8 Go RAM) est souvent le choix le plus pratique pour les petites équipes.

Q : Comment limiter les jobs CI aux seuls membres de l’équipe (éviter les abus sur les dépôts publics) ?

R : Par défaut, Gitea Actions ne déclenche pas de CI sur les pull requests ouvertes par des contributeurs externes non approuvés. Dans Paramètres du dépôt → Actions, la politique d’approbation permet de choisir entre : déclencher pour tous (risque d’abus), déclencher uniquement pour les membres, ou requérir une approbation manuelle pour les contributions externes. Pour les dépôts publics hébergeant des projets open source, l’option « approbation pour les nouveaux contributeurs » est le meilleur équilibre.

Q : Comment déboguer un workflow qui échoue sans message d’erreur clair ?

R : Activez le mode debug en ajoutant un secret ACTIONS_RUNNER_DEBUG avec la valeur true dans votre dépôt. Gitea injectera des logs détaillés du runner dans l’interface d’exécution. Vous pouvez également ajouter un step de diagnostic explicite dans votre workflow : run: env | sort pour afficher toutes les variables d’environnement disponibles, ou run: docker info pour vérifier l’état du daemon Docker sur le runner.

Q : Combien de jobs parallèles peut gérer un runner ?

R : C’est contrôlé par le paramètre runner.capacity dans /etc/act_runner/config.yaml. La valeur par défaut est 1, ce qui signifie que le runner traite un job à la fois. Sur un serveur avec 4 vCPU et 8 Go de RAM, une valeur de 2 à 3 est généralement stable pour des jobs de compilation classiques. Augmenter cette valeur au-delà de la capacité réelle du serveur entraîne des timeouts et des OOM kills difficiles à diagnostiquer. Ajustez progressivement et surveillez l’utilisation CPU/RAM avec htop pendant les pics de charge.