Cluster Git builds

Deploy straight from Git

Point a cluster service at a Git repo and Suble does the rest: an on-demand builder VM clones the repo, builds an image, pushes it to your Container Registry, and the cluster’s rolling deploy ships it — one replica at a time. No CI to wire up, no build box to keep running.

Guide: deploy from Git Container clusters

Quickstart Build methods Build config The builder Private repos Logs & rebuild Reference

from a git push to a rolled-out release

git push  →  branch: main
   │
   ▼
┌──────────────── on-demand builder VM ────────────────┐
│  clone repo  →  build image  →  push to your registry │
└─────────────────────────┬─────────────────────────────┘
                          ▼
   registry.suble.io/acme/web:2f9c1a4   ← lands in your Container Registry
                          │  existing rolling deploy
                          ▼
   cluster shop · service web · rolled out one replica at a time

Quickstart

Three steps, all in the dashboard (Console → Clusters → a service). Connect a repo, pick how it builds, and every save turns the latest commit into a running release.

Point a service at Git

Add a service to a cluster and choose Git as its source. Paste the repository URL and pick the branch to track — that branch's latest commit is what gets built.

connect a repo

Source        Git repository
Repository    github.com/acme/web
Branch        main

Pick a build method

Choose how the image is built: from a Dockerfile, auto-detected with Railpack, or served as a static site. Set the base directory if the service lives in a subfolder.

choose a method

Build method  Dockerfile   (or: Railpack · Static)
Base dir      /
Dockerfile    Dockerfile

Save and it ships

Suble spins up a builder, builds the image, pushes it to your registry, and the cluster's rolling deploy rolls it out one replica at a time. Live logs stream while it runs.

build & roll out

✓ Builder ready — cloning github.com/acme/web@main
✓ Built + pushed registry.suble.io/acme/web:2f9c1a4
✓ Rolling out to service web (3 replicas)

The image is built into your own registry.suble.io/<project>/… namespace, so every build also shows up in Project → Container Registry with its commit tag.

Three ways to build

Every repo is different, so pick the build method that fits — you can change it later and rebuild.

Dockerfile

Build from a Dockerfile in your repo. You pick the base image, control every layer and decide exactly what the final runtime looks like.

Best when you already have a Dockerfile, or want full control over the build.

Railpack

No Dockerfile? Railpack auto-detects your stack — Node, Python, Go, PHP, Rust and more — and produces a sensible production image for you. It's a modern alternative to Nixpacks.

Best for a standard app in a common language when you'd rather not maintain a Dockerfile.

Static

Serve the repo's files as a static site behind nginx. Point the base directory at the folder to serve — a built bundle, a site generator's output, or plain HTML/CSS/JS.

Best for static front-ends, landing pages and generated documentation.

Build configuration

A few fields tell the builder where and how to build. The defaults cover a repo with a Dockerfile at its root; the rest are there for monorepos and non-standard layouts.

Fields

`Branch / ref`required	`string`	The branch or commit to build. Every build is pinned to the exact commit it ran against, and the image is tagged with that commit — so a build is always reproducible and traceable.
`Base directory`	`path`	The path inside the repo to build from — the working directory for the build. Defaults to the repo root; set it to a subfolder for monorepos where the service lives under, say, apps/web.
`Dockerfile location`	`path · Dockerfile method`	Path to the Dockerfile, relative to the base directory. Defaults to Dockerfile. Point it elsewhere for repos that keep, for example, docker/Dockerfile.prod.
`Build context`	`path · Dockerfile method`	The directory sent to the build as its context (what COPY and ADD can see). Defaults to the base directory.

Monorepo? Set the base directory to the service’s subfolder and give each service in the cluster its own base directory — one repo can feed several services, each built from its own path.

The on-demand builder

Builds don’t run on your cluster members and there’s no build server sitting idle. A builder VM appears when there’s work to do and disappears when there isn’t.

Spun up on demand

When a build is queued and no builder is already warm, Suble provisions a builder VM, runs the build on it, and pushes the finished image to your registry.

Stays warm, then vanishes

After a build the builder stays warm for an idle window (20 minutes by default) so a follow-up build is instant — then it's deleted and its IP is released back to the pool.

Billed only while running

The builder is billed hourly for the time it's actually up, at its size's rate. No builds running means no builder and nothing to pay — there's no standing build fee.

The idle window and the builder’s size are per-cluster settings — see the reference below.

Private repositories

Public repos need nothing. For a private repo, store a Git access token once and Suble uses it to clone during builds. Tokens live under Project Settings → Git and are shared by every service in the project.

Git credentials

`Access token`	`project-scoped`	A Git access token (a personal access or deploy token with read access to the repo) stored once under Project Settings → Git. Suble uses it to clone during builds. It's scoped to the project and encrypted at rest.
`Scope`	`read-only`	Read-only clone access is all that's needed. The token is used only on the builder to fetch the source — it's never baked into the image or exposed to the running containers.
`SSH keys`	`coming soon`	Deploy-key (SSH) authentication for private repos is on the way. For now, use a stored access token.

The token is used only on the ephemeral builder to fetch your source. It is never written into the image, so a running container can never read your Git credentials.

Live logs, rebuild & history

Every build streams its output to the dashboard as it happens — clone, build steps, push and rollout. When it finishes it joins the service’s build history, and you can rebuild the latest commit at any time.

live build log

╭─ web · build 2f9c1a4 ────────────────────────────────
│ 12:04:01  Builder ready (lb.s · cph)
│ 12:04:02  Cloning github.com/acme/web @ main …
│ 12:04:05  HEAD is 2f9c1a4  "fix: cache headers"
│ 12:04:06  Building with Dockerfile  (context: .)
│ 12:04:31  => exporting layers
│ 12:04:38  Pushed registry.suble.io/acme/web:2f9c1a4
│ 12:04:39  Rolling out to service "web" (3 replicas)
╰─ ✓ done in 38s

Live logs

Watch the clone, the build and the rollout stream in real time, so a failed build tells you why on the spot.

Rebuild

One button rebuilds the current branch and rolls the result out — handy after a base-image change or a flaky build.

Build history

Every build is kept per service with its commit, result and duration — each tagged image is a version you can roll back to.

Reference

Git builds sit on top of container clusters and push into your Container Registry. The build settings below are configured per cluster.

Per-cluster build settings

Settings

`Builder idle window`	`duration`	How long a builder VM stays warm after a build before it's deleted. Default 20 minutes, overridable per cluster. A warm builder makes back-to-back builds fast; deleting it frees the IP and stops the bill.
`Builder size`	`plan`	The plan the on-demand builder runs on. Bump it for large or slow builds — a bigger builder has more CPU and memory, so it finishes faster.

Per-service build config

Fields

`Branch / ref`required	`string`	The branch or commit to build. Every build is pinned to the exact commit it ran against, and the image is tagged with that commit — so a build is always reproducible and traceable.
`Base directory`	`path`	The path inside the repo to build from — the working directory for the build. Defaults to the repo root; set it to a subfolder for monorepos where the service lives under, say, apps/web.
`Dockerfile location`	`path · Dockerfile method`	Path to the Dockerfile, relative to the base directory. Defaults to Dockerfile. Point it elsewhere for repos that keep, for example, docker/Dockerfile.prod.
`Build context`	`path · Dockerfile method`	The directory sent to the build as its context (what COPY and ADD can see). Defaults to the base directory.

Prefer a prebuilt image or your own CI? A cluster service can still take a plain image: instead of Git — see the clusters docs. Git builds are just the fastest path from source to a running service.