Wiki/infra/forgejo-runner

Forgejo Actions Runner

Runner CI/CD pour les workflows GitHub Actions execute sur git.acadenice.com.

Architecture

git.acadenice.com (Forgejo 10.0.3)
        ↓ poll long-running connection
   Forgejo Runner (ce service)
        ↓ docker.sock
     Docker host
        ↓ run jobs
     Containers ephemeres (build, test, deploy)

Prerequis

• Docker + Docker Compose v2 sur le host
• Acces sortant vers git.acadenice.com
• Acces a docker.sock (mount /var/run/docker.sock)
• Pour les jobs avec containers : Docker daemon avec privileges suffisants

Setup (premiere fois)

1. Recuperer un token de registration

Option A — via API (organizations) :

curl -sf -H "Authorization: token <TON_TOKEN_ADMIN>" \
  https://git.acadenice.com/api/v1/orgs/AcadeNice/actions/runners/registration-token \
  | jq -r '.token'

Option B — via UI Forgejo (recommande pour debutant) :

• git.acadenice.com → Login → Site Administration → Actions → Runners → Create new runner
• Copier le token affiche

Le token expire 30 min apres generation.

2. Configurer .env

cd infra/forgejo-runner
cp .env.example .env
# editer .env :
# FORGEJO_RUNNER_REGISTRATION_TOKEN=<token genere>

3. Up

docker compose up -d
docker compose logs -f
# Attendre "Runner registered successfully"

4. Verifier sur Forgejo

git.acadenice.com → Site Administration → Actions → Runners → le runner doit apparaitre comme Online.

Apres setup — usage

Les workflows .github/workflows/*.yml ou .forgejo/workflows/*.yml du repo AcadeNice/Wiki se declenchent automatiquement apres push.

Le runner pull les jobs et les execute en containers Docker.

Workflows compatibles

Forgejo Actions est 95% compatible GitHub Actions syntax. La majorite des workflows GitHub marchent tels quels.

Differences notables :

• actions/checkout@v4 : marche, mais resolu via le marketplace gitea/actions (configure auto par le runner)
• Secrets : a configurer dans Forgejo UI au niveau repo OU org
• GITHUB_TOKEN : remplace par GITEA_TOKEN (ou alias compatible)
• Pas de support actions/setup-node@v4 directement — il faut un runner avec Node pre-installe OU utiliser une image custom

Recommandation : pinner les actions tierces sur des SHA commit pour eviter les surprises.

Maintenance

Tache	Frequence
Bump runner version	Tous les 2-3 mois (cf releases)
Cleanup docker images cache	Mensuel (docker system prune -a apres backup)
Verifier logs docker compose logs --tail=100	Hebdomadaire
Backup runner data volume	Quotidien (config seulement, pas de state critique)

Securite

• docker.sock mount = privilege root sur le host. Le runner peut creer/supprimer n'importe quel container. Ne pas heberger sur un host sensible.
• Recommandation : VPS dedie pour le runner (5€/mois Hetzner CPX11).
• Si VPS partage : utiliser docker-in-docker (DinD) au lieu de docker.sock mount.

Troubleshooting

Symptome	Cause probable	Fix
Runner "Offline" sur Forgejo	Token expire ou network	Regenerer token, restart container
Job stuck en pending	Pas de runner disponible avec les labels demandes	Verifier runs-on du workflow vs labels du runner
permission denied sur docker.sock	User dans le container n'est pas root	Verifier user: "0:0" dans compose
Build lent	Pas de cache Docker	Activer BuildKit avec DOCKER_BUILDKIT=1

References

• Forgejo Actions docs
• act_runner project