# 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) :
```bash
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

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

### 3. Up

```bash
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](https://code.forgejo.org/forgejo/runner)) |
| 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](https://forgejo.org/docs/latest/admin/actions/)
- [act_runner project](https://code.forgejo.org/forgejo/runner)