# Comment fonctionnent les builds

Source : https://webgune.cloud/fr-fr/docs/builds-railpack · Mis à jour le 2026-10-27

# Comment fonctionnent les builds

Chaque déploiement démarre par un **build** : votre code source est transformé en image conteneur, poussée dans le registre interne de la plateforme, puis déployée sur le cluster.

## Le pipeline de build

1. **Récupération du code**, depuis la branche GitHub suivie ou votre upload.
2. **Détection de la stack** : le builder auto analyse le dépôt et choisit la recette adaptée (Node.js, Python, Go, PHP…).
3. **Construction de l'image** : dépendances installées, build exécuté (`next build`, `vite build`…), image finale optimisée.
4. **Push au registre** : l'image est versionnée dans le registre interne, visible dans l'onglet **Registry** du service.
5. **Déploiement** : le cluster bascule vers la nouvelle image sans coupure.

## Les deux modes de build

| Mode | Quand l'utiliser |
|------|------------------|
| **Build auto** (défaut) | La plupart des cas, sans configuration |
| **Dockerfile** | Vous voulez un contrôle total sur l'image ([guide](/docs/docker-dockerfile)) |

Si un `Dockerfile` est présent à la racine du dépôt, il peut être utilisé à la place de la détection automatique.

## Suivre un build

L'onglet **Déploiements** du service liste tous les builds avec leur statut et leurs **logs complets**, conservés même une fois le build terminé. Un build en cours peut être **annulé** à tout moment.

## Cache de build

Les builds réutilisent un cache (dépendances, couches d'image) d'une fois sur l'autre : le premier build d'un service est le plus long, les suivants réutilisent tout ce qui n'a pas changé. Si le cache a capturé une dépendance périmée, **Rebuild sans cache** dans le menu du service repart de zéro.

## Gestion des dépendances Node

Quel que soit le gestionnaire de votre dépôt, les builds s'exécutent avec **npm**. Un `bun.lock`, `pnpm-lock.yaml` ou `yarn.lock` est écarté avant le build, et les scripts qui appellent ces outils sont réécrits vers leurs équivalents npm. Tout cela se fait sur la copie de travail, jamais sur votre dépôt.

Votre `package-lock.json`, lui, est **conservé et utilisé** : les versions installées sont exactement celles qu'il fige. C'est ce qui garantit qu'une image de production embarque les mêmes dépendances que votre poste.

Il n'est écarté que dans deux cas, tous deux annoncés dans les logs du build :

- **il est désynchronisé de votre `package.json`**, par exemple une dépendance ajoutée sans régénérer le lock. Un `npm install` suivi d'un commit du lock règle la question ;
- **votre dépôt est géré par bun, pnpm ou yarn** (c'est leur fichier qui fait référence, et le `package-lock.json` à côté n'est pas à jour).

Dans ces deux cas les dépendances sont simplement re-résolues, et leurs versions peuvent alors différer de celles de votre machine.

> **Un build échoue ?** Ouvrez les logs du build fautif : l'erreur y figure presque toujours (dépendance manquante, script `build` en échec, version de runtime). Le bouton **Diagnostiquer avec l'IA** peut aussi vous orienter (voir [Assistant IA](/docs/assistant-ia)).

## Aller plus loin

- [Déploiements et rollback](/docs/deploiements-rollback)
- [Le fichier kx712.yml](/docs/kx712-yml) : exécuter des tests avant chaque déploiement