Gitea Actions : écrire un workflow

Un workflow est un fichier YAML dans .gitea/workflows/. Les exemples utilisent des noms génériques.

Structure

name: CI # nom affiché dans l'onglet Actions

on: # quand l'exécuter
  push:
    branches: [main]
  pull_request:

env: # variables pour tout le workflow
  NODE_ENV: test

jobs:
  tests: # identifiant du job
    name: Tests
    runs-on: ubuntu-latest # étiquette du runner
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test

Étapes

Clé	Rôle
`name`	Libellé affiché
`run`	Commande shell
`uses`	Action réutilisable (`dépôt@version`)
`with`	Paramètres de l’action
`env`	Variables d’environnement de l’étape
`if`	Condition d’exécution
`working-directory`	Dossier d’exécution de `run`
`shell`	Interpréteur (`bash`, `sh`, `python`)
`continue-on-error`	Ne pas faire échouer le job si l’étape échoue
`timeout-minutes`	Durée maximale de l’étape

steps:
  - name: Installer
    run: npm ci
    working-directory: ./web

  - name: Script multi-lignes
    run: |
      set -e
      echo "Version : $(node --version)"
      npm run build

  - name: Étape facultative
    run: ./verification-optionnelle.sh
    continue-on-error: true

Une étape run s’exécute avec bash -e quand bash est disponible : une commande qui échoue interrompt le job.

Récupérer le code

- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # historique complet (nécessaire pour les tags et `git describe`)

Sans checkout, le dossier de travail est vide. Le jeton fourni par défaut (gitea.token) permet de cloner le dépôt courant, y compris s’il est privé.

Variables d’environnement

env:
  APP_ENV: ci

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NIVEAU: debug
    steps:
      - run: echo "$APP_ENV $NIVEAU $MA_VAR"
        env:
          MA_VAR: valeur

Portées : workflow, job, étape (la plus précise l’emporte).

Contextes utiles

- run: |
    echo "Dépôt : ${{ gitea.repository }}"
    echo "Branche : ${{ gitea.ref_name }}"
    echo "Commit : ${{ gitea.sha }}"
    echo "Événement : ${{ gitea.event_name }}"
    echo "Auteur : ${{ gitea.actor }}"
    echo "Exécution : ${{ gitea.run_number }}"

github.* est un synonyme de gitea.* (compatibilité).

Sorties et variables entre étapes

steps:
  - id: version
    run: echo "numero=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
  - run: echo "Version ${{ steps.version.outputs.numero }}"
  - run: echo "DEPLOY_ENV=staging" >> "$GITHUB_ENV"
  - run: echo "$DEPLOY_ENV"

$GITHUB_OUTPUT transmet une valeur à une étape suivante, $GITHUB_ENV définit une variable pour les étapes suivantes.

Résumé d’exécution

- run: echo "### Résultat des tests : OK" >> "$GITHUB_STEP_SUMMARY"

Image de conteneur d’un job

jobs:
  tests:
    runs-on: ubuntu-latest
    container:
      image: node:22-bookworm
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

container exécute le job dans l’image indiquée, sans dépendre de l’image associée à l’étiquette du runner.

Services (base de données de test)

jobs:
  tests:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_PASSWORD: <mot-de-passe-de-test>
          POSTGRES_DB: boutique
        options: >-
          --health-cmd "pg_isready -U postgres"
          --health-interval 5s --health-retries 10
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
        env:
          DATABASE_URL: postgres://postgres:<mot-de-passe-de-test>@postgres:5432/boutique

Le service est joignable par son nom (postgres) depuis un job qui s’exécute dans un conteneur ; avec un job exécuté directement sur l’hôte du runner, utiliser 127.0.0.1 et publier le port. Remplacer <mot-de-passe-de-test> par une valeur de test, jetable.

Valider un workflow

Un fichier invalide n’apparaît pas dans l’onglet Actions ou échoue au démarrage :

python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' .gitea/workflows/ci.yaml && echo "YAML valide"

Cette commande contrôle seulement la syntaxe YAML (module python3-yaml, sudo apt install python3-yaml).

Bonnes pratiques

Épingler les versions des actions (@v4) ; pour une sécurité accrue, un commit précis.
timeout-minutes sur chaque job pour éviter les blocages.
Garder les workflows courts ; déplacer la logique dans des scripts versionnés (scripts/ci.sh) exécutables aussi en local.
Un fichier par préoccupation : ci.yaml (tests), deploy.yaml (déploiement), release.yaml.

Dépannage

Symptôme	Piste
`Unable to resolve action`	Action introuvable : nom ou version erronés, github.com inaccessible depuis le runner
`node: command not found` dans une action	Image sans Node.js : utiliser une image qui l’inclut
Variable vide	Portée incorrecte, ou `${{ }}` dans un script `run` mal échappé
Étape qui passe alors qu’une commande échoue	Commande suivie de `\|\| true`, ou `shell` sans `-e`
Le dossier de travail est vide	`actions/checkout` manquant

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

La syntaxe ne dépend pas de la distribution. Les outils disponibles dans les jobs sont ceux de l’image du conteneur (par exemple ubuntu:24.04 ou ubuntu:26.04).

Pour aller plus loin

Syntaxe des workflows
Suite : Déclencheurs, jobs et conditions