Gitea Actions : dépannage

Procédure de diagnostic

Le workflow est-il détecté ? Onglet Actions du dépôt : la liste des workflows doit afficher le fichier.
Une exécution a-t-elle été créée ? Sinon, le déclencheur ne correspond pas (branche, chemins, [skip ci]).
Est-elle « en attente » ? Aucun runner disponible avec l’étiquette demandée.
A-t-elle échoué ? Ouvrir l’exécution, lire le journal de l’étape en rouge.
Côté runner, lire son journal :

sudo systemctl status act_runner
sudo journalctl -u act_runner -n 100 --no-pager

Côté serveur Gitea, sudo journalctl -u gitea -n 100 (selon l’installation, voir Gitea : installation).

Le workflow ne démarre pas

Cause	Vérification
Actions désactivé	Paramètres du dépôt, et `[actions] ENABLED = true` dans `app.ini`
Mauvais dossier	`.gitea/workflows/` (ou `.github/workflows/`), extension `.yaml` ou `.yml`
YAML invalide	`python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' fichier.yaml`
Filtre de branche ou de chemin	`on.push.branches`, `paths`
Message de commit	`[skip ci]` présent
Workflow absent de la branche par défaut	`schedule` et `workflow_dispatch` lisent la branche par défaut

L’exécution reste en attente

Cause	Solution
Aucun runner enregistré pour cette portée	Administration > Actions > Runners (instance, organisation ou dépôt)
Étiquette inconnue	`runs-on` doit correspondre à une étiquette du runner
Runner hors ligne	`sudo systemctl restart act_runner`, jeton ou adresse de l’instance erronés
Tous les runners occupés	Attendre, ou augmenter `runner.capacity` dans `config.yaml`

sudo journalctl -u act_runner -f

Erreurs fréquentes dans un job

Message	Cause et solution
`Cannot connect to the Docker daemon`	Docker arrêté ou utilisateur du runner hors du groupe `docker` : `sudo usermod -aG docker <utilisateur-du-runner>` puis redémarrer le service
`unable to resolve action` / `failed to fetch`	Action introuvable ou accès à github.com bloqué : vérifier le réseau, ou héberger l’action sur l’instance Gitea et la référencer par URL complète
`node: command not found`	Image sans Node.js : utiliser une image qui l’inclut
`GHESNotSupportedError` / `v4+ is not currently supported`	Utiliser `upload-artifact@v3`
`fatal: could not read Username` au `checkout`	Dépôt privé, jeton absent ou instance injoignable depuis le conteneur : vérifier `ROOT_URL` et la résolution DNS dans le conteneur
`Permission denied`	Utilisateur non-root dans l’image, droits sur les fichiers
`exec format error`	Architecture de l’image différente de celle du runner
`no space left on device`	Disque du runner plein : `docker system prune -af`, nettoyage des caches
`context deadline exceeded`	Réseau ou DNS du conteneur : `docker run --rm alpine nslookup git.exemple.com`
Secret vide	Mauvaise portée, workflow lancé par un fork

Le runner ne joint pas l’instance

curl -I https://git.exemple.com/
sudo journalctl -u act_runner -n 50 --no-pager

Si Gitea est derrière un reverse proxy ou un pare-feu : l’adresse d’instance du runner (config.yaml ou fichier .runner) doit être joignable depuis la machine du runner et depuis les conteneurs qu’il lance (adresse publique plutôt que localhost). Voir Gitea : configuration (ROOT_URL).

Réseau des conteneurs

Un job qui doit joindre un service local (base de données sur l’hôte) ne le trouve pas via 127.0.0.1, qui désigne le conteneur lui-même. Utiliser l’adresse de l’hôte vue depuis le conteneur (passerelle du pont Docker, 172.17.0.1 par défaut) ou un service déclaré dans le workflow. Si UFW est actif sur l’hôte, autoriser le pont Docker (voir UFW et Docker).

Relancer et annuler

Relancer : bouton « Réexécuter » dans la page de l’exécution (tous les jobs ou un seul).
Annuler : bouton « Annuler » d’une exécution en cours.
Supprimer les anciennes exécutions : page de l’exécution, ou réglage de rétention de l’instance.

Activer plus de détails

env:
  ACTIONS_STEP_DEBUG: true

Et dans le workflow, afficher le contexte pour comprendre une condition :

- run: |
    echo "ref=${{ gitea.ref }} event=${{ gitea.event_name }}"
    env | sort | grep -E '^(GITHUB|GITEA|RUNNER)_' | head -30

Ne pas afficher l’ensemble de l’environnement (env sans filtre) : il peut contenir des secrets.

Journal du runner plus bavard

Dans config.yaml du runner :

log:
  level: debug

sudo systemctl restart act_runner
sudo journalctl -u act_runner -f

Repasser à info après le diagnostic.

Ubuntu 24.04 et 26.04 : différences à connaître

Les diagnostics sont identiques. Sur l’hôte du runner, Docker et systemd ont des versions différentes selon la version d’Ubuntu (voir Docker : installation et systemd : bases).

Pour aller plus loin

FAQ Gitea Actions
Retour : Présentation et activation