Installation Introduction
This section describes how to set up your self-managed instance of the Plumber Platform, the control plane that turns the scores your pipelines produce into continuous governance.
What you get
Analysis stays where it belongs: in the open-source Plumber CLI, running inside your pipelines. The Platform never re-runs an analysis and never produces a verdict of its own. Your pipelines push their results to it with their own native CI OIDC token (id_tokens), and the Platform:
- keeps the score and the findings of every project, on the default branch and per branch
- applies your policies and portfolios to the estate, and proves coverage
- tracks issues through their lifecycle, with the automated fix flows
- flags drift and stale results instead of inventing a verdict
- sends scheduled reports, and exposes everything through the API
Info
No shared secret ever lives in a runner: pipelines authenticate with the identity token GitLab mints for them, and the Platform verifies it.
Quick Installation Guide
plumber-platform Helm chart.Everything is published from the getplumber/plumber-platform repository: the Compose stack, the installer, the update, backup and restore scripts, and the Helm chart.
Infrastructure
A Plumber Platform install is made of four components:
- Plumber backend: one process that serves the API, runs the background workers and the schedulers, and migrates the database on boot. Image
docker.io/getplumber/platform-backend, distroless and non-root, listening on port8080. - Plumber frontend: the Plumber interface (Next.js). Image
docker.io/getplumber/platform-frontend, listening on port3000. - PostgreSQL 18: stores everything the Platform knows.
- Redis 8.4: caches, queues and the live event stream.
There is no separate worker service: the backend owns its job queues in-process. Both images are released together on one version tag, and both must always run the same one.
Caution
One origin is mandatory. The browser calls the API same-origin, so a single hostname serves both apps: /api is routed to the backend and everything else to the frontend. The bundled Traefik (Docker Compose) and the chart’s Ingress (Kubernetes) already do exactly that. Do not split the frontend and the API across two hostnames.
💻 Requirements
GitLab
- GitLab 17.7 or later
Runtime, one of:
- Docker with the Compose plugin 2.20.2 or later, on a Linux host
- Kubernetes with Helm 3
Network
- Users must be able to reach the Plumber server on TCP ports 80 and 443
- The Plumber server must be able to reach your GitLab instance
- The installation requires write access to the DNS zone of the domain you pick for Plumber
GitLab OAuth application
Every installation method needs a GitLab OAuth application: it is how users sign in to Plumber. Create it before you start (the Docker Compose installer prints the link and the exact values), on the whole instance (Admin > Applications) or in the root group you want to connect (Settings > Applications):
| Field | Value |
|---|---|
| Name | Plumber |
| Redirect URI | <your Plumber URL>/api/v1/auth/callback |
| Confidential | yes (keep the box checked) |
| Scopes | api |
The application id and secret, the GitLab access token, SMTP and the licence are stored encrypted in the Platform database, never in .env or in a values file. plumber-bootstrap stores the OAuth credentials during the install; the access token, SMTP and the licence are set later in Settings as an Admin. Each installation method has its own invocation; it refuses an instance that is already configured, so running it again is safe.
The setup is finished by a Plumber Admin: a GitLab instance Admin when Plumber is connected to the whole instance, a user who is at least Maintainer of the root group when it is connected to a group (see Roles & Permissions). That account sets the access token, SMTP and the licence.