bench.yaml reference
This page lists everything bench.yaml accepts; bench check enforces it.
Reading the tables:
- Each table is one YAML mapping, and its rows are the keys. The top-level
document is the
Benchtable. - Key names: tables show
snake_case(e.g.default_registry), but bench.yaml usescamelCase(defaultRegistry). - The label
repeatedmeans a YAML list. - Enum values are written by name, e.g.
runtime: RUNTIME_GO. - A duration field takes a string like
30s.
Table of Contents
gitlab/bench/v1/assembly.proto
Assembly
Assembly is a deployable unit: one OCI image containing one or more
composed domains, deployed and scaled together by Runway.
Domains within an assembly share a single process space and a single set of inbound ports. All I/O still flows through the framework's Inbound and Outbound layers.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | Stable UUID v4. | |
| name | string | Short name. Used as the Runway service name, and as the assembly's image sub-repository under Bench.default_registry (one image per assembly, at <default_registry>/<name>:<tag>). | |
| description | string | Optional human-readable description. | |
| domains | Domain | repeated | The domains composed into this assembly. Stays repeated, not map, for determinism: see docs/design/schema-change-process.md, "Repeated, not map, for keyed collections." |
| listeners | Listener | repeated | Externally-published inbound listeners for the assembly's OCI image: the ports a generated deployment manifest surfaces. |
A listener is an assembly-level concern: one OCI image, one process, a single set of inbound ports. The routes served on a listener live under each domain's Inbound layer.
Capped at one listener for now, matching what the deployment target publishes today. Modelled as repeated so raising that cap later is a non-breaking validator change rather than a schema edit.
An empty list is valid and marks a consumer-style assembly: one whose domains only subscribe to NATS subjects, process, and publish results, publishing no inbound port. |
| runtime |
Runtime | | Language the assembly compiles to. Required: every assembly is single-language to start (Rust or Go). RUNTIME_MULTI is reserved for a future iteration and is rejected during validation. All handlers in the assembly's domains must match this runtime. |
Listener
Listener is one externally-published inbound socket: a TCP port plus the
wire protocol served on it. It is an assembly-level concern because an
assembly is one OCI image, one process, sharing a single set of inbound
ports; the routes served on a listener live under each domain's Inbound
layer (a listener is the socket, a route is what answers on it).
A generated deployment manifest surfaces this as the published container port and its protocol.
| Field | Type | Label | Description |
|---|---|---|---|
| port | uint32 | TCP port to publish. Must be 1-65535. | |
| protocol | Protocol | Wire protocol served on this port. |
Protocol
Protocol is the wire protocol a Listener serves.
| Name | Number | Description |
|---|---|---|
| PROTOCOL_UNSPECIFIED | 0 | |
| PROTOCOL_HTTP | 1 | |
| PROTOCOL_GRPC | 2 |
Runtime
Runtime is the language an assembly compiles to. An assembly is
single-language: every domain it composes shares this runtime.
RUNTIME_MULTI is reserved for a future iteration where one assembly may
mix languages. It is named here so the roadmap is explicit, but configs that
select it are rejected during validation until the runtime support exists.
See docs/decisions/LB-D5-assembly-runtime.md.
| Name | Number | Description |
|---|---|---|
| RUNTIME_UNSPECIFIED | 0 | |
| RUNTIME_RUST | 1 | |
| RUNTIME_GO | 2 | |
| RUNTIME_MULTI | 3 |
gitlab/bench/v1/bench.proto
Bench
Bench is the root of a Lab Bench workspace configuration.
One workspace typically maps to one Git repository (the "bench repo"),
though assemblies may pull in domains from many remote repositories.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | Stable UUID v4. | |
| name | string | Short name. Used as the top-level metric namespace prefix. | |
| description | string | Optional human-readable description of the workspace. | |
| assemblies | Assembly | repeated | All assemblies managed by this workspace. Each assembly produces one independently deployable OCI image. |
| default_registry | string | Default OCI registry for assembly images. bench build --release composes each assembly's image reference as <default_registry>/<assembly.name>:<tag>, so this is the project's image repository, without a scheme or a tag. Example: "registry.gitlab.com/gitlab-org/gitlab/gate" |
Optional. When unset, images are tagged local-only as <bench.name>/<assembly.name>:<tag> and a warning is printed; a local build must not require registry configuration. |
| bench_version |
string | | Optional bench tool version this config was authored against (semver, e.g. "0.1.0"). A diagnostics-only compatibility marker, not the schema's versioning mechanism (see docs/design/schema-change-process.md). Lets the tool flag a config written for a different schema than the running binary. Optional and unenforced: unset is valid and unknown versions are accepted. |
| canonical_group |
string | | The GitLab group path that owns this workspace's canonical project, e.g. "gitlab-org/ops". Must start with gitlab-org/. bench scaffold renders it as the template's gitlab_namespace and CODEOWNERS entry; bench register writes it as canonical_group in the release-platform repos.yaml entry and derives the security namespace from it.
Optional in the schema, since a config can be built up field by field, but required by scaffold and register, which cannot run without it. |
| project_name |
string | | The name of the repository holding this workspace, e.g. "gate". bench scaffold renders it as the template's project_name; bench build names the Caproni fragment's clone URL and published chart reference with it. Keeping it here means the scaffolded repository and the fragment cannot silently name two different repositories.
Optional: when unset, the bench name is used. |
gitlab/bench/v1/common.proto
GitRef
GitRef identifies a specific source tree in a remote Git repository.
Used wherever a domain or handler can be sourced from a separate repo.
Both tag and sha1/sha256 may be set simultaneously: tag is used by
Renovate / dependency-bot for tracking; sha1/sha256 is the authoritative
pinned target for hermetic builds. If only one is provided, sha1/sha256
takes precedence for build resolution.
Local GitRef: If url or anything else except path is missing refer to the
local git repository, starting relative to the repository root.
| Field | Type | Label | Description |
|---|---|---|---|
| url | string | Full HTTPS URL of the Git repository. Example: "https://gitlab.com/gitlab-org/labkit" | |
| branch | string | Branch the pinned ref lives on. Nothing reads it yet: it is recorded for Renovate tracking, and as the fetch hint for servers that refuse a request for an arbitrary commit. Example: "main" | |
| path | string | Relative path within the repository to the domain or handler root. Example: "domains/wiki" or "crates/vulnerability-handler" | |
| tag | string | Annotated or lightweight tag. A tag can be moved, so it pins by convention rather than by construction; only the SHAs below are immutable. Example: "v1.4.2" | |
| sha1 | string | Full 40-character commit SHA-1 for hermetic, reproducible builds. Example: "a3f9c2d1b8e74f0c6d2a1b9e3f7c4d0a2b8e5f1c" | |
| sha256 | string | Full 64-character commit SHA-256 for hermetic, reproducible builds. Example: "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824" |
gitlab/bench/v1/domain.proto
Domain
Domain composes the three layers of a Lab Bench domain.
A domain can be defined inline or loaded from a remote Git repository
via the source field.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | Stable UUID v4. | |
| name | string | Short name. Used as a metric label and log field. | |
| description | string | Optional human-readable description. | |
| inbound | Inbound | Inbound layer: protocol listeners, AuthN+Z, load management, observability. | |
| outbound | Outbound | Outbound layer: backend connection pools, retry, and circuit-breaking. | |
| source | GitRef | Remote source for this domain definition and implementation. When set, the domain is loaded from a separate Git repository. When absent, the domain is defined inline in this config file, and the implementation is looked for in a directory called 'domains' relative to the current working directory. |
Reserved: nothing loads source yet, so validation rejects it until
https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/91 lands. |
gitlab/bench/v1/handler.proto
GoHandler
| Field | Type | Label | Description |
|---|---|---|---|
| pkg | string | Package that the handler function is defined in, as a path under the bench's internal/ directory (e.g. scan/handler). Not a full import path: the build prefixes the bench's Go module path, so a first segment with a dot (gitlab.com/...) is rejected. | |
| func | string | Name of handler function within the package. Must be exported (an identifier starting with an upper-case letter): the generated assembly entrypoint calls it from another package, and Go exports by case. Leave empty to take the scaffold template's default name. |
Handler
| Field | Type | Label | Description |
|---|---|---|---|
| rs | RustHandler | ||
| go | GoHandler | ||
| rb | RubyHandler | ||
| py | PythonHandler |
PythonHandler
| Field | Type | Label | Description |
|---|---|---|---|
| file | string | File (module) the handler is defined in | |
| func | string | Name of handler function within file/module, e.g. my_api::handle_request |
RubyHandler
| Field | Type | Label | Description |
|---|---|---|---|
| file | string | File the handler (with or without Module) is defined in | |
| func | string | Name of handler function within the file/module, e.g. MyAPI::handle_request |
RustHandler
| Field | Type | Label | Description |
|---|---|---|---|
| crate | string | Crate that the handler is defined in. May be nested (e.g. scanner/handler): bench scaffold renders the skeleton at that path and bench build stages it there. The crate is identified by the final path segment, because Cargo crate names are flat within a workspace, so that basename must be a valid Rust identifier. Two crates that differ in prefix but share a basename (e.g. scanner/handler and redact/handler) collide and are rejected. | |
| func | string | Entry point the generated adapter calls on the crate's Handler. Must be a valid Rust identifier (e.g. handle, create_invoice); bench build rejects empty values, leading digits, and path syntax (e.g. mycrate::api::myhandler). A crate exposes exactly one entry point: naming the same crate with two different func values is rejected. |
gitlab/bench/v1/inbound.proto
GRPCEndpoint
GRPCEndpoint registers a gRPC service handler.
| Field | Type | Label | Description |
|---|---|---|---|
| service_name | string | Fully-qualified gRPC service name as declared in the proto definition. Example: "gitlab.wiki.v1.WikiService" | |
| proto_file | string | Path to the .proto file defining this service, relative to the handler's source root: internal/<pkg> for Go, src/<crate> for Rust. Imports resolve from the same root. Example: "proto/wiki/v1/wiki.proto" | |
| handler | Handler | Handler: reference to the developer-authored business logic module. |
HTTPEndpoint
HTTPEndpoint registers a single HTTP route handler.
| Field | Type | Label | Description |
|---|---|---|---|
| methods | HTTPMethod | repeated | HTTP methods handled by this endpoint. |
| route | string | Route pattern, including path parameters. Example: "/api/v4/projects/:id/wikis/:slug" | |
| handler | Handler | Handler: reference to the developer-authored business logic module. |
Inbound
Inbound is the complete inbound configuration for a domain.
| Field | Type | Label | Description |
|---|---|---|---|
| http | HTTPEndpoint | repeated | HTTP (REST/JSON) endpoint registrations. Stays repeated, not map: see docs/design/schema-change-process.md, "Repeated, not map, for keyed collections." |
| grpc | GRPCEndpoint | repeated | gRPC endpoint registrations. |
| nats | NATSEndpoint | repeated | NATS pub/sub consumer endpoints. |
NATSEndpoint
NATSEndpoint registers a NATS consumer endpoint.
| Field | Type | Label | Description |
|---|---|---|---|
| instance | string | NATS instance name. Example: "default", "ci-events". | |
| subject | string | NATS subject to subscribe to. Example: "events.user.created". | |
| queue_group | string | Queue group for load-balanced consumption. Optional. | |
| handler | Handler | Handler: reference to the developer-authored business logic module. |
HTTPMethod
HTTP request method.
| Name | Number | Description |
|---|---|---|
| HTTP_METHOD_UNSPECIFIED | 0 | |
| HTTP_METHOD_GET | 1 | |
| HTTP_METHOD_POST | 2 | |
| HTTP_METHOD_PUT | 3 | |
| HTTP_METHOD_PATCH | 4 | |
| HTTP_METHOD_DELETE | 5 | |
| HTTP_METHOD_HEAD | 6 |
gitlab/bench/v1/outbound.proto
Backend
Backend describes a single outbound dependency and its connection pool.
| Field | Type | Label | Description |
|---|---|---|---|
| id | string | Stable UUID v4. | |
| name | string | Short name. Used as a metric label on outbound RED metrics. | |
| description | string | Optional human-readable description. | |
| postgres | PostgresConfig | ||
| http | HTTPBackendConfig | ||
| grpc | GRPCBackendConfig | ||
| pool | PoolConfig | Connection pool sizing and lifecycle configuration. | |
| retry | RetryPolicy | Retry policy override. Falls back to Outbound.default_retry if unset. | |
| circuit_breaker | CircuitBreaker | Circuit breaker override. Falls back to Outbound.default_circuit_breaker if unset. |
CircuitBreaker
CircuitBreaker prevents thundering-herd failures on degraded backends.
| Field | Type | Label | Description |
|---|---|---|---|
| failure_threshold | float | Error rate threshold (0.0–1.0) that trips the circuit open. Example: 0.5 → open when ≥50% of requests fail. | |
| min_requests | int32 | Minimum number of requests in the evaluation window before the threshold is applied. | |
| open_duration | google.protobuf.Duration | Duration the circuit stays open before moving to half-open. | |
| half_open_probe_count | int32 | Number of probe requests allowed in half-open state before fully closing or re-opening the circuit. |
GRPCBackendConfig
| Field | Type | Label | Description |
|---|---|---|---|
| address | string | host:port of the upstream gRPC service. Example: "gitaly.gitlab-system.svc:8075" | |
| mtls_enabled | bool | ||
| timeout | google.protobuf.Duration | ||
| proto_file | string | Path to the .proto file for the upstream service, relative to the handler root. |
HTTPBackendConfig
| Field | Type | Label | Description |
|---|---|---|---|
| base_url | string | Base URL of the upstream service. Example: "https://internal-api.gitlab.com" | |
| mtls_enabled | bool | ||
| timeout | google.protobuf.Duration |
Outbound
Outbound is the complete outbound configuration for a domain.
| Field | Type | Label | Description |
|---|---|---|---|
| backends | Backend | repeated | Backend connection pools. Stays repeated, not map: see docs/design/schema-change-process.md, "Repeated, not map, for keyed collections." |
| default_retry | RetryPolicy | Default retry policy applied to all backends unless overridden per-backend. | |
| default_circuit_breaker | CircuitBreaker | Default circuit breaker applied to all backends unless overridden per-backend. |
PoolConfig
PoolConfig governs connection pool behaviour for a backend.
| Field | Type | Label | Description |
|---|---|---|---|
| max_open | int32 | Maximum number of open connections in the pool. | |
| max_idle | int32 | Maximum number of idle connections kept in the pool. | |
| idle_timeout | google.protobuf.Duration | Duration after which an idle connection is closed and removed. | |
| max_lifetime | google.protobuf.Duration | Maximum lifetime of any connection, regardless of activity. |
PostgresConfig
PostgresConfig declares that a domain needs a Postgres database. The
platform provisions the instance and publishes its connection details as
gitlab.infrastructure.v1.Config, which LabKit reads at runtime.
RetryPolicy
RetryPolicy configures exponential backoff with jitter for transient failures.
| Field | Type | Label | Description |
|---|---|---|---|
| max_attempts | int32 | Maximum number of retry attempts (not counting the initial attempt). | |
| initial_backoff | google.protobuf.Duration | Initial backoff duration before the first retry. | |
| max_backoff | google.protobuf.Duration | Maximum backoff duration after repeated failures. | |
| multiplier | float | Backoff multiplier applied on each successive retry. Example: 2.0 for standard exponential backoff. | |
| retryable_status_codes | int32 | repeated | HTTP / gRPC status codes eligible for retry. Example: [429, 503] |
One numeric space for two protocols: 14 reads as gRPC UNAVAILABLE or as a nonsensical HTTP code, and Outbound.default_retry has no backend type to disambiguate against. Split by protocol:
https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/88 |
gitlab/options/v1/options.proto
File-level Extensions
| Extension | Type | Base | Number | Description |
|---|---|---|---|---|
| field_uuid | string | .google.protobuf.FieldOptions | 20111010 | |
| file_uuid | string | .google.protobuf.FileOptions | 20111008 | |
| msg_uuid | string | .google.protobuf.MessageOptions | 20111009 | |
| method_uuid | string | .google.protobuf.MethodOptions | 20111012 | |
| svc_uuid | string | .google.protobuf.ServiceOptions | 20111011 |
Scalar Value Types
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|---|---|---|---|---|---|---|---|
| double | double | double | float | float64 | double | float | Float | |
| float | float | float | float | float32 | float | float | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |