Gitea : Gitea Actions (intégration continue)

Gitea Actions exécute des workflows (tests, compilation, déploiement) déclenchés par les événements d’un dépôt. La syntaxe est proche de celle de GitHub Actions. Les tâches sont exécutées par un runner (act_runner), installé sur une machine à part ou sur le serveur. Les exemples utilisent des noms génériques.

Principe

Élément	Rôle
Workflow	Fichier YAML dans `.gitea/workflows/` du dépôt
Runner	Programme `act_runner` qui récupère les tâches et les exécute
Étiquette (label)	Associe `runs-on:` d’un workflow à une image Docker du runner

Prérequis

Gitea avec Actions activé (section [actions] ENABLED = true dans app.ini si nécessaire, puis redémarrage).
Docker sur la machine du runner (voir Installer Docker sur Ubuntu).

Installer le runner

Version courante : voir dl.gitea.com/act_runner (exemple : 0.6.1).

VERSION=0.6.1
cd /tmp
curl -fsSLO "https://dl.gitea.com/act_runner/${VERSION}/act_runner-${VERSION}-linux-amd64"
sudo install -m 755 "act_runner-${VERSION}-linux-amd64" /usr/local/bin/act_runner
act_runner --version

Créer un utilisateur dédié qui a accès à Docker, et son dossier :

sudo adduser --system --group --home /var/lib/act_runner --shell /bin/bash runner
sudo usermod -aG docker runner

Obtenir un jeton d’enregistrement

Origine	Où
Interface (instance)	Administration du site, Actions, Runners, Créer un nouveau runner
Interface (organisation ou dépôt)	Paramètres, Actions, Runners
Ligne de commande (sur le serveur Gitea)	`sudo -u git gitea --config /etc/gitea/app.ini --work-path /var/lib/gitea actions generate-runner-token`

Le jeton est secret : ne pas le conserver dans l’historique ni dans un dépôt.

Configurer et enregistrer le runner

sudo -u runner mkdir -p /var/lib/act_runner && cd /var/lib/act_runner
sudo -u runner act_runner generate-config > config.yaml

Le fichier config.yaml règle notamment le nombre de tâches parallèles (runner.capacity), les étiquettes et le réseau des conteneurs. Enregistrer le runner auprès de l’instance :

sudo -u runner act_runner register --no-interactive \
  --instance https://git.exemple.com \
  --token <jeton> \
  --name runner-1 \
  --labels "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"

Option	Rôle
`--instance`	URL de Gitea (accessible depuis le runner)
`--token`	Jeton d’enregistrement
`--name`	Nom affiché dans l’interface
`--labels`	Étiquettes `nom:docker://image` (plusieurs séparées par des virgules)
`--ephemeral`	Le runner ne traite qu’une tâche puis s’arrête

L’enregistrement crée le fichier .runner dans le dossier courant.

Service systemd

sudo tee /etc/systemd/system/act_runner.service <<'CONF'
[Unit]
Description=Gitea Actions runner
After=network.target docker.service

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

[Install]
WantedBy=multi-user.target
CONF
sudo systemctl daemon-reload
sudo systemctl enable --now act_runner
systemctl status act_runner

Le runner apparaît ensuite comme « Inactif » (disponible) dans l’interface Gitea.

Écrire un workflow

Fichier .gitea/workflows/ci.yml dans le dépôt :

name: CI
on:
  push:
    branches: [main]
  pull_request:

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

on : événements déclencheurs (push, pull_request, schedule, workflow_dispatch).
runs-on : étiquette du runner (ici ubuntu-latest).
uses : action réutilisable (téléchargée depuis github.com par défaut ; l’URL d’un dépôt Gitea est aussi possible).
run : commande du shell.

Après un git push, l’exécution se suit dans l’onglet Actions du dépôt.

Secrets et variables

Paramètres du dépôt (ou de l’organisation), Actions, Secrets et Variables :

steps:
  - run: ./deploy.sh
    env:
      DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
      DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

Les secrets sont chiffrés, masqués dans les journaux et non transmis aux workflows déclenchés par des demandes de fusion issues de forks.

Tester un workflow en local

act_runner exec -W .gitea/workflows/ci.yml          # exécute le workflow sans passer par le serveur

Maintenance du runner

sudo journalctl -u act_runner -f
sudo systemctl restart act_runner
docker system prune -f                              # libère l'espace des conteneurs et images inutilisés

Mise à jour : télécharger la nouvelle version, remplacer /usr/local/bin/act_runner, sudo systemctl restart act_runner.

Dépannage

Symptôme	Piste
Le runner reste « Hors ligne »	`sudo journalctl -u act_runner` : adresse de l’instance injoignable, jeton invalide ou Docker arrêté
`Cannot connect to the Docker daemon`	L’utilisateur du runner n’est pas dans le groupe `docker` (ou session non rouverte)
Un job reste en attente	Aucune étiquette ne correspond à `runs-on:` : `--labels` et `config.yaml`
Les actions `uses:` ne se téléchargent pas	Accès sortant vers `github.com` bloqué, ou configurer une URL d’actions par défaut dans `app.ini` (`[actions] DEFAULT_ACTIONS_URL`)
Beaucoup d’anciens runs	Régler `RUN_RETENTION_DAYS` (Gitea 28), supprimer les artefacts
Un job échoue sur la mémoire ou le disque	Limiter `runner.capacity`, `docker system prune`