Ressources-relationnel/docs/05-mise-en-place-gitea-actions.md

05 — Mise en place de Gitea Actions (CI/CD)

Guide d'installation du moteur d'automatisation (CI/CD) pour le dépôt. Contexte : Gitea en Docker / docker-compose, accès SSH au serveur.

Gitea Actions nécessite deux choses :

1. Activer la fonctionnalité Actions dans Gitea.
2. Enregistrer au moins un runner (act_runner) qui exécute les workflows.

---

Étape 1 — Activer Actions dans Gitea

Se connecter en SSH au serveur, puis se placer dans le dossier du docker-compose.yml de Gitea (⚠️ celui de Gitea, pas celui de l'application Laravel).

Option A (recommandée) — via variable d'environnement

Dans le service Gitea du docker-compose.yml, ajouter la variable :

services:
  server:            # nom du service Gitea (peut s'appeler "gitea")
    image: gitea/gitea:latest
    environment:
      - GITEA__actions__ENABLED=true
    # ... reste de la configuration inchangé

Puis recharger Gitea :

docker compose up -d

Option B — via le fichier app.ini

Éditer le fichier app.ini (dans le volume Gitea, souvent ./gitea/gitea/conf/app.ini) et ajouter :

[actions]
ENABLED = true

Puis redémarrer : docker compose restart.

Vérification

Dans l'interface web du dépôt, un onglet « Actions » doit apparaître.

---

Étape 2 — Obtenir un jeton d'enregistrement du runner

Deux niveaux possibles :

• Niveau instance (runner partagé par tous les dépôts) : Site Administration → Actions → Runners → Create new Runner.
• Niveau dépôt (runner dédié au projet) : Dépôt → Settings → Actions → Runners → Create new Runner.

Copier le jeton (registration token) affiché.

---

Étape 3 — Lancer un runner (act_runner) en Docker

Créer un dossier de travail sur le serveur, par exemple ~/gitea-runner, avec un fichier docker-compose.yml :

services:
  runner:
    image: gitea/act_runner:latest
    container_name: gitea_runner
    restart: always
    environment:
      GITEA_INSTANCE_URL: "https://gitea.sam-coffre.duckdns.org"
      GITEA_RUNNER_REGISTRATION_TOKEN: "COLLER_LE_JETON_ICI"
      GITEA_RUNNER_NAME: "runner-docker-1"
      # Images utilisées pour `runs-on: ubuntu-latest`
      GITEA_RUNNER_LABELS: "ubuntu-latest:docker://catthehacker/ubuntu:act-latest"
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock

Le montage de /var/run/docker.sock permet au runner de créer les conteneurs qui exécutent chaque job. L'image catthehacker/ubuntu:act-latest fournit un environnement compatible ubuntu-latest (Node, outils de base).

Démarrer le runner :

cd ~/gitea-runner
docker compose up -d
docker compose logs -f runner   # doit afficher "runner registered successfully"

Le runner apparaît alors en vert dans Settings → Actions → Runners du dépôt.

---

Étape 4 — Ajouter les secrets de déploiement

Dans Dépôt → Settings → Actions → Secrets, créer :

Secret	Valeur
SSH_HOST	IP ou domaine du serveur de production
SSH_USER	utilisateur SSH (ex. sam)
SSH_PRIVATE_KEY	clé privée SSH autorisée sur le serveur
SSH_PORT	port SSH (ex. 22)

Générer une paire de clés dédiée au déploiement : ssh-keygen -t ed25519 -C "gitea-deploy" -f deploy_key puis ajouter deploy_key.pub dans ~/.ssh/authorized_keys du serveur, et coller le contenu de deploy_key (clé privée) dans le secret SSH_PRIVATE_KEY.

---

Étape 5 — Déclencher et vérifier

Un simple push sur master déclenche les workflows :

git commit --allow-empty -m "test: déclenche la CI"
git push

Dans l'onglet Actions du dépôt :

• le workflow CI (ci.yml) exécute Pint puis PHPUnit ;
• le workflow CD (deploy.yml) déploie via SSH.

Une exécution en vert constitue une preuve idéale à intégrer au dossier (capture d'écran).

---

Dépannage rapide

Symptôme	Cause probable / solution
Pas d'onglet Actions	Actions non activé (Étape 1) ou Gitea non redémarré
« No runner available »	Runner non enregistré / hors ligne (Étape 3)
ubuntu-latest introuvable	Label non défini → variable GITEA_RUNNER_LABELS
actions/checkout échoue	Le serveur doit accéder à github.com (Gitea proxy les actions)
Déploiement SSH refusé	Vérifier la clé dans authorized_keys et les secrets SSH_*