Forgejo Actions CI/CD : tutoriel pratique 2026

Forgejo Actions (et son équivalent Gitea Actions) est l’un des arguments massifs en faveur de la migration depuis GitHub : un système CI/CD intégré, compatible à 90 % avec les workflows GitHub Actions, qui tourne sur vos propres runners. Pas de minutes facturées, pas de limites artificielles, vos secrets restent chez vous. Voici le tutoriel complet 2026.

Voir notre guide Forgejo.

Compatibilité avec GitHub Actions

Forgejo Actions a été conçu pour exécuter directement les workflows YAML de GitHub Actions, avec quelques différences :

• Syntaxe YAML : 100 % identique
• Actions GitHub Marketplace : la plupart fonctionnent (clone via URL Git)
• actions/checkout@v4, actions/setup-node@v4, etc. fonctionnent natifvement
• Différences : pas de GITHUB_* mais GITEA_* en plus, certaines actions très spécifiques GitHub ne marchent pas

Étape 1 — Activer Actions dans Forgejo

Dans app.ini :

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = github

L’option DEFAULT_ACTIONS_URL = github permet d’utiliser uses: actions/checkout@v4 qui sera résolu vers github.com/actions/checkout.

Activer Actions au niveau repo : Repo → Settings → Advanced → Enable Actions.

Étape 2 — Installer un runner

Forgejo Actions nécessite des « runners » pour exécuter les jobs. Le runner officiel est act_runner :

# Sur un VPS dédié runner (recommandé) ou même VPS Forgejo
wget -O act_runner https://code.forgejo.org/forgejo/runner/releases/download/v3.x.x/forgejo-runner-3.x.x-linux-amd64
chmod +x act_runner
sudo mv act_runner /usr/local/bin/

# Générer config
forgejo-runner generate-config > config.yaml

# Récupérer un token d'inscription depuis Forgejo :
# Site Administration → Actions → Runners → New Runner Token

forgejo-runner register \
  --instance https://git.exemple.sn \
  --token TOKEN_xxx \
  --name runner-prod-01 \
  --labels ubuntu-latest:docker://node:20-bookworm,ubuntu-22.04:docker://node:20-bookworm

# Démarrer
forgejo-runner daemon

Étape 3 — Service systemd pour le runner

# /etc/systemd/system/forgejo-runner.service
[Unit]
Description=Forgejo Actions Runner
After=network.target docker.service

[Service]
Type=simple
User=runner
Group=runner
WorkingDirectory=/home/runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now forgejo-runner
sudo systemctl status forgejo-runner

Étape 4 — Premier workflow

# .forgejo/workflows/test.yml (ou .gitea/workflows/test.yml)
name: Test

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - run: npm ci
      - run: npm test
      - run: npm run build

Push, et dans l’onglet Actions du repo vous voyez le job s’exécuter en direct.

Étape 5 — Secrets

1. Repo → Settings → Secrets → Add Secret
2. Référencer dans workflow : {{ secrets.MY_SECRET }}

Les secrets sont chiffrés au repos et exposés uniquement aux jobs autorisés.

Étape 6 — Déploiement automatique

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build
        run: |
          npm ci
          npm run build
      
      - name: Deploy via SSH
        env:
          SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H web-prod-01 >> ~/.ssh/known_hosts
          rsync -avz dist/ deploy@web-prod-01:/var/www/site/
          ssh deploy@web-prod-01 'systemctl --user reload caddy'

Étape 7 — Cache de dépendances

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

Adaptation Afrique de l’Ouest

Forgejo Actions économise ce qui peut devenir une ligne de coût significative chez GitHub : 0,008 USD/min au-delà des 2000 min gratuites. Pour une équipe avec 10 builds/jour de 5 min, c’est ~12 USD/mois, soit ~150 USD/an sur GitHub. En self-host, vous payez juste le VPS runner (4 €/mois Hetzner CX22 supplémentaire).

Erreurs fréquentes

Pour aller plus loin

• Guide Forgejo complet
• Installer Forgejo sur Coolify
• Migrer GitHub vers Forgejo
• Documentation Forgejo Actions : forgejo.org/docs