# How builds work

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

# How builds work

Every deployment starts with a **build**: your source code is transformed into a container image, pushed to the platform's internal registry, then deployed to the cluster.

## The build pipeline

1. **Code retrieval**: from the followed GitHub branch (or your upload).
2. **Stack detection**: the auto builder analyzes the repository and picks the appropriate recipe (Node.js, Python, Go, PHP…).
3. **Image build**: dependencies installed, build executed (`next build`, `vite build`…), final image optimized.
4. **Push to registry**: the image is versioned in the internal registry, visible in the service's **Registry** tab.
5. **Deployment**: the cluster switches to the new image with no downtime.

## The two build modes

| Mode | When to use it |
|------|------------------|
| **Auto build** (default) | Most cases, no configuration |
| **Dockerfile** | You want full control over the image ([guide](/docs/docker-dockerfile)) |

If a `Dockerfile` is present at the repository root, it can be used instead of automatic detection.

## Following a build

The service's **Deployments** tab lists all builds with their status and **full logs**, kept even after the build finishes. A build in progress can be **canceled** at any time.

## Build cache

Builds reuse a cache (dependencies, image layers) from one run to the next: a service's first build is the longest, later ones reuse everything that hasn't changed. If the cache has captured a stale dependency, **Rebuild without cache** from the service menu starts from scratch.

## Node dependency handling

Whatever package manager your repository uses, builds run with **npm**. A `bun.lock`, `pnpm-lock.yaml` or `yarn.lock` is set aside before the build, and scripts calling those tools are rewritten to their npm equivalents. All of it happens on the working copy, never on your repository.

Your `package-lock.json`, on the other hand, is **kept and used**: the versions installed are exactly the ones it pins. That is what guarantees a production image ships the same dependencies as your machine.

It is set aside in two cases only, both announced in the build logs:

- **it is out of sync with your `package.json`**, for instance because a dependency was added without regenerating the lock. An `npm install` followed by committing the lock settles it;
- **your repository is managed by bun, pnpm or yarn** (their file is the reference, and the `package-lock.json` next to it is not up to date).

In those two cases dependencies are simply re-resolved, and their versions may then differ from the ones on your machine.

> **A build fails?** Open the logs of the failing build: the error is almost always there (missing dependency, failing `build` script, runtime version). The **Diagnose with AI** button can also point you in the right direction (see [AI assistant](/docs/assistant-ia)).

## Go further

- [Deployments and rollback](/docs/deploiements-rollback)
- [The kx712.yml file](/docs/kx712-yml): run tests before each deployment