Gitea Actions : présentation et activation

Gitea Actions exécute des workflows (build, tests, déploiement) à chaque événement d’un dépôt Gitea. La syntaxe est volontairement compatible avec GitHub Actions : la plupart des workflows et des actions existants fonctionnent avec peu ou pas de changement. Cette rubrique traite l’écriture des workflows ; l’installation et l’enregistrement du runner sont détaillés dans Gitea : Actions (CI). Les exemples utilisent des noms génériques.

Composants

Élément	Rôle
Workflow	Fichier YAML décrivant quand et quoi exécuter (`.gitea/workflows/*.yaml`)
Job	Ensemble d’étapes exécutées sur un même runner
Étape (step)	Commande (`run`) ou action réutilisable (`uses`)
Runner	Processus (`act_runner`) qui exécute les jobs, le plus souvent dans des conteneurs Docker
Étiquette (label)	Nom qui relie un job à un type de runner (`runs-on: ubuntu-latest`)
Action	Brique réutilisable (`actions/checkout`, `actions/setup-node`…)

Gitea orchestre ; le runner exécute. Le runner peut tourner sur le même serveur que Gitea (déconseillé pour du code non fiable) ou sur une autre machine.

Activer

Actions est activé par défaut sur les versions récentes de Gitea. Côté serveur, dans app.ini :

[actions]
ENABLED = true

Puis, dans chaque dépôt : Paramètres > Dépôt > Activer les Actions (ou la case équivalente selon la version). Un onglet Actions apparaît dans le dépôt.

Obtenir un runner

Un workflow ne s’exécute que si un runner compatible est enregistré (voir Gitea : Actions (CI) pour l’installation et le service systemd). Niveaux d’enregistrement :

Portée	Où obtenir le jeton
Instance	Administration du site > Actions > Runners
Organisation	Paramètres de l’organisation > Actions > Runners
Dépôt	Paramètres du dépôt > Actions > Runners

Un runner enregistré sur un dépôt n’exécute que les jobs de ce dépôt.

Étiquettes et images

Le runner déclare des étiquettes qui associent un nom à un environnement :

ubuntu-latest:docker://node:22-bookworm
ubuntu-24.04:docker://ubuntu:24.04

Format : nom:docker://image. Dans un workflow, runs-on: ubuntu-latest choisit le runner qui possède cette étiquette, et les étapes s’exécutent dans un conteneur créé à partir de l’image associée.

Choix d’image	Conséquence
Image « complète » (nombreux outils préinstallés)	Compatible avec la plupart des actions, image volumineuse
Image légère (`node:22-bookworm`)	Rapide à télécharger ; installer les outils manquants dans le workflow

Beaucoup d’actions (actions/checkout, actions/setup-node) exigent Node.js dans l’image : prévoir une image qui l’inclut.

Première exécution

Créer .gitea/workflows/ci.yaml dans le dépôt :

name: CI
on: [push]

jobs:
  bonjour:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Bonjour depuis Gitea Actions"
      - run: uname -a

git add .gitea/workflows/ci.yaml
git commit -m "ci: ajouter un premier workflow"
git push

Dans le dépôt, onglet Actions : l’exécution apparaît, avec le journal de chaque étape.

Où chercher les workflows

Dossier	Remarque
`.gitea/workflows/`	Emplacement propre à Gitea (prioritaire)
`.github/workflows/`	Reconnu aussi : un dépôt migré depuis GitHub fonctionne sans déplacement

Différences avec GitHub Actions

Sujet	Gitea
Actions externes	`uses: actions/checkout@v4` est résolu par défaut depuis github.com ; l’adresse se change dans `app.ini` (`DEFAULT_ACTIONS_URL`)
Contexte	`github.` et `gitea.` sont équivalents
Artefacts	`actions/upload-artifact` et `download-artifact` en v3 (la v4 n’est pas prise en charge)
Runners hébergés	Aucun : ils sont auto-hébergés
Fonctions avancées	Certaines fonctions de GitHub (environnements protégés, OIDC, certaines options de `concurrency`) sont absentes ou partielles : vérifier la documentation de la version utilisée

Sécurité

Dépannage

Symptôme	Piste
Onglet Actions absent	Actions non activé sur le serveur (`[actions] ENABLED`) ou dans le dépôt
L’exécution reste « en attente »	Aucun runner avec l’étiquette demandée : Administration > Actions > Runners
`No matching runner`	`runs-on` ne correspond à aucune étiquette
Le workflow n’est pas détecté	Mauvais dossier ou extension (`.yaml` / `.yml`), erreur de syntaxe YAML

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

Gitea Actions ne dépend pas de la version d’Ubuntu de l’hôte. L’image du conteneur détermine l’environnement des jobs : choisir ubuntu:24.04 ou une image plus récente selon la cible. Voir Gitea : installation.

Pour aller plus loin

Documentation Gitea Actions
Suite : Écrire un workflow