Gitea Actions : cache et artefacts

Cache des dépendances

Le cache conserve les dépendances (node_modules, paquets pip…) d’une exécution à l’autre, pour éviter de les télécharger à chaque fois.

Activer le cache sur le runner

Le cache repose sur un serveur intégré au runner, activé dans config.yaml de act_runner :

cache:
  enabled: true
  dir: '' # défaut : dossier de cache du runner
  host: '' # adresse du runner joignable par les conteneurs (déduite si vide)
  port: 0 # port du serveur de cache (0 : choisi automatiquement)

sudo systemctl restart act_runner

Le conteneur du job doit pouvoir joindre l’adresse du runner : si le cache échoue silencieusement, renseigner host avec l’adresse de la machine du runner visible depuis les conteneurs.

Utiliser le cache

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 22
  - uses: actions/cache@v4
    with:
      path: ~/.npm
      key: npm-${{ hashFiles('package-lock.json') }}
      restore-keys: |
        npm-
  - run: npm ci

Paramètre	Rôle
`path`	Dossier(s) à mettre en cache
`key`	Clé exacte : change quand les dépendances changent (empreinte du fichier de verrouillage)
`restore-keys`	Clés de repli (préfixes) si la clé exacte n’existe pas

Avec actions/setup-node, l’option cache: npm fait la même chose en une ligne ; de même cache: pip avec actions/setup-python.

Exemples de chemins

Outil	`path`	`key` basée sur
npm	`~/.npm`	`package-lock.json`
pnpm	`~/.local/share/pnpm/store`	`pnpm-lock.yaml`
pip	`~/.cache/pip`	`requirements.txt`
Composer	`~/.cache/composer`	`composer.lock`

Mettre en cache le dossier de téléchargement (le magasin du gestionnaire de paquets) plutôt que node_modules : plus fiable.

Artefacts

Un artefact est un fichier produit par un job, conservé après l’exécution (téléchargeable dans l’interface) et transmissible à un autre job.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: site
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: site
          path: dist/
      - run: ls -R dist | head

Les artefacts se retrouvent dans la page de l’exécution (Actions > l’exécution > section Artefacts). Leur durée de conservation se règle avec retention-days et, côté serveur, avec [actions] ARTIFACT_RETENTION_DAYS dans app.ini.

Cache ou artefact ?

Besoin	Outil
Accélérer des téléchargements répétés entre exécutions	Cache
Transmettre un résultat entre jobs d’une même exécution	Artefact
Conserver un résultat de build (binaire, rapport) pour le télécharger	Artefact

Espace disque du runner

Les images de conteneurs, les caches et les dossiers de travail s’accumulent sur le runner :

docker system df
docker image prune -af --filter "until=168h"
docker volume prune -f
du -sh ~/.cache/act ~/.cache/actcache 2>/dev/null

Planifier un nettoyage périodique (minuteur systemd, voir systemd : minuteurs), et surveiller l’espace disque de la machine.

Dépannage

Symptôme	Piste
Le cache n’est jamais restauré	`cache.enabled: false`, adresse du cache injoignable, clé qui change à chaque fois
`Failed to restore: ... connect ETIMEDOUT`	Renseigner `cache.host` avec l’adresse joignable depuis les conteneurs
`v4+ is not currently supported`	Utiliser `upload-artifact@v3` / `download-artifact@v3`
Artefact absent dans le job suivant	Nom ou chemin différents, `needs` manquant
Disque du runner plein	`docker system prune`, nettoyage des caches
Téléchargement de dépendances lent malgré le cache	Clé trop spécifique : ajouter `restore-keys`

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

Aucune propre à la distribution. Le cache est géré par act_runner ; l’espace disque et Docker sont ceux de la machine du runner (voir Docker : installation).