Skip to content
FAQ

Frequently asked questions

Short answers, each pointing at the page that covers the topic properly. If your question isn’t here and the docs don’t answer it, see Where do I get help? at the bottom.

Getting started

What is Theseus, exactly?

Theseus is GitLab’s paved path for building modular services. It makes the platform GitLab already has easier to build on rather than replacing it. It is the set of components (Lab Bench, LabKit, Caproni, Runway, Fairway, the project template, and the CI components) that together take a service from copier copy to a deployed, instrumented, PREP-ready artifact. The goal is to move mean time to production for a new modular service from weeks to hours. See Vision.

How do I create a new service today?

Run common-template-copier:

copier copy https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git my-service --trust

Answer golang, release_platform, and three_layer_go with yes to get the modular service skeleton. The Get Started tutorial walks the whole flow, including pushing the project and bringing it up locally.

What about bench? The vision page talks about bench new.

bench is the CLI from the LabBench project that will automate the copier flow and project registration. It is not the paved path yet; until it lands, use copier directly. See Lab Bench and the bench CLI reference.

Do I have to write my service in Go?

Go is the language the template scaffolds today, and the Go three-layer skeleton is what the tutorials and the exemplar show. Rust is a first-class target for the library layer: labkit-rs is a deliberately wire-compatible port — same header names, gRPC metadata keys, and log field names — so Rust and Go services look identical in dashboards and share traces. A rust-service-template plays the exemplar role for Rust. See LabKit.

Can I bring an existing service onto Theseus?

Partly. Release Framework supports importing existing projects, but the import path is fragile and the guide recommends splitting the work across two merge requests: one to align Terraform state, one to apply configuration. See Importing existing projects. Note that scaffolding with common-template-copier is mandatory for Release Framework projects, so retrofitting the template is part of the job.

The pieces

What’s the difference between Runway and Fairway?

Fairway generates the Helm chart: it reads your .runway/fairway.yaml manifest and emits a packaged, infrastructure-agnostic chart. Runway is the deployment platform that takes that chart to production. One writes the artifact; the other ships it.

Do I need to write Helm charts?

No. You write a FairwayManifest — image, port, probes, and abstract dependencies — and Fairway generates the Deployment, Service, HPA, optional PDB/VPA, ingress, and cron jobs from it. The chart is a build output published as an OCI artifact on tagged releases; it is never committed to Git. See Fairway and the manifest schema.

Why local Kubernetes (Caproni) instead of docker-compose?

Because Caproni runs the same CNG images and the same Fairway-generated chart that ship to customers, with hot-reload and full debugging. Your laptop and production consume the same service declarations and differ only in how the dependencies are satisfied, which is what the core contract describes. See Caproni and Run locally with Caproni.

What do I get from LabKit without doing anything?

Structured JSON logging in the format GitLab’s pipeline expects, Prometheus metrics on /-/metrics on the probe port, OpenTelemetry tracing, correlation IDs, access logging, panic recovery, health endpoints, and graceful shutdown. The template wires all of it in from the first commit. The how-to guides for tracing, logging, and metrics each cover getting that data all the way into Grafana.

Configuration and deployment

Where does my service’s configuration come from?

Declare it once as spec.values.appConfig in your Fairway manifest and each environment delivers it its own way: a ConfigMap in-cluster, a baked profile on Runway, per-cell values on Cells. See Pass application configuration via Fairway, and Set up typed configuration for protobuf-defined, validated config via LabKit v2/config.

How do I change a value or a secret without rebuilding?

You don’t need to rebuild. Deploy-time values live under spec.values and secrets are Vault-backed via secretEnvFrom and secretVolumes. See Modify the values and secrets passed to your service.

Which platform binding should my service target?

If your service has synchronous dependencies on Cell infrastructure, or could go down when one Cell goes down, it is not an Enterprise service; it belongs in a Cell. The Enterprise binding is for GitLab Inc operational services that sit above every tenant (licensing, billing aggregation, cross-tenant data pipelines) and it carries a hard requirement: no synchronous dependency on the GitLab application or on components running in Cells. See Platform bindings.

Does Theseus deploy and operate my service in production?

Theseus’s scope runs from your laptop to a deployed, operable artifact. Fleet management of GitLab’s SaaS is not part of it: GitLab.com and Cells are operated by Tenant Scale, Dedicated environments by the Dedicated team, and rollout policy — rings, progressive rollouts, maintenance windows, upgrade groupings — belongs to them. Theseus’s job is to make the artifacts they orchestrate uniform and safe. See Separation of concerns between Theseus and Cells.

Does using Theseus mean I pass PREP automatically?

No. Theseus gives you evidence, not sign-off. Build & Release, Deployment, Service Architecture, Observability, Operational Lifecycle, and several other categories arrive largely satisfied by the scaffold, so the review becomes confirmation rather than construction. Platform stakeholders still review and approve, and threat modelling and AppSec review remain service-specific. The bench prep evidence report is still to ship. See the PREP connection.

Day to day

How do I pull in template improvements after scaffolding? 

copier update --trust --skip-answered

Your project’s template version is recorded in .copier-answers.yml. See Update your service template for conflict handling and migrations.

Can I use feature flags outside the monolith?

Yes. The feature-flags service is generally available. Flags are plain YAML in the feature-flags repository, evaluated with the LabKit client, toggled by merge request, and deleted when the rollout is done. See Use feature flags in your service and the strategy page.

How do I test a modular feature without spinning up the world?

Test against the contract edges: in-process fakes for service dependencies and real infrastructure from Caproni. No monolith, no neighbouring services. See Modular feature test isolation and the companion how-to.

Where do I get help?

Last updated on
Documentation gaps