Skip to main content

​
Branch-based servers

RBS provisions a dedicated build server for every active branch in your project. When you start working on a branch, the platform:
  1. Spins up an RBS server for that branch.
  2. Clones the repository and checks out the branch.
  3. Deploys all workers automatically — CI workers, schedulers, job workers, and build workers.
  4. Connects your editor to the server via the RBS extension.
┌──────────────────────────────────────────────────────┐
│                    RBS Platform                       │
│                                                       │
│  main branch ────→ [RBS Server] ← CI workers (auto)  │
│                       ↑                               │
│                    Dev A (editor)                      │
│                                                       │
│  feature/auth ──→ [RBS Server] ← CI workers (auto)   │
│                       ↑  ↑                            │
│                  Dev B   Dev C  (collaborating)        │
│                                                       │
│  feature/pay ───→ [RBS Server] ← CI workers (auto)   │
│                       ↑                               │
│                    Dev D (editor)                      │
└──────────────────────────────────────────────────────┘

​
Collaboration

Multiple developers can connect to the same branch server simultaneously. Everyone sees:
  • The same build state and outputs.
  • The same test results and logs.
  • Real-time updates when teammates run builds.

​
Server lifecycle

EventWhat happens
Developer starts working on a branchServer is provisioned, repo cloned, workers deployed.
Teammate joins the same branchConnects to the existing server.
All developers disconnectServer idles (configurable timeout).
Branch is merged or deletedServer is decommissioned.
Push to branch (no active editor)CI workers run automatically.

​
Built-in Git server

RBS includes an integrated Git server. You can host your repositories directly on the platform — no GitHub, GitLab, or Bitbucket required.
  • Push and pull with standard Git commands.
  • Branch management from the dashboard or editor.
  • Webhooks and triggers for CI/CD workflows.
  • Access control with team-based permissions.
If you prefer to use an external Git host, RBS can import and mirror repositories from GitHub, GitLab, and other providers.

​
Workspace

Every RBS project starts with a workspace — defined by a WORKSPACE.rbs file at the repository root. This file configures project-wide settings, toolchains, and external dependencies. 
# WORKSPACE.rbs
config_setting(key = "project_name", value = "my-app")
config_setting(key = "version", value = "1.0.0")

# Register toolchains (managed by the server)
load("@rbs//python/toolchain.rbs", "python_toolchain")
python_toolchain(name = "python", version = "3.11.0")

# Declare external dependencies
load("@rbs//python/dependencies.rbs", "py_repository")
py_repository(name = "requests_lib", package = "requests", version = "2.31.0")
When the RBS server starts, it reads WORKSPACE.rbs and sets up the entire build environment — downloading toolchains, resolving dependencies, and preparing workers.

​
Packages

A package is any directory within a workspace that contains a BUILD.rbs file. Each package defines its own set of build targets. 
my-app/
├── WORKSPACE.rbs
├── BUILD.rbs               # Root package
├── services/
│   ├── api/
│   │   └── BUILD.rbs       # Package: services/api
│   └── worker/
│       └── BUILD.rbs       # Package: services/worker
└── libs/
    └── common/
        └── BUILD.rbs       # Package: libs/common
Packages provide logical grouping for related targets. You can reference targets across packages using labels.

​
Targets

A target is a single buildable unit declared in a BUILD.rbs file — a binary, library, test, container image, or any custom rule. Every target has a unique name within its package. 
# services/api/BUILD.rbs
load("@rbs//python/rules.rbs", "py_binary", "py_test")

py_binary(
    name = "server",
    srcs = ["main.py", "routes.py"],
    main = "main.py",
    deps = [":handlers"],
)

py_test(
    name = "server_test",
    srcs = ["test_main.py"],
    deps = [":server"],
)

​
Labels

Labels uniquely identify targets across a workspace. RBS supports two syntax styles:

​
Traditional syntax

//package/path:target_name
LabelMeaning
//services/api:serverTarget server in services/api
//:helloTarget hello in root package
//...All targets in all packages
:serverTarget server in current package

​
Natural syntax

RBS also supports a more intuitive syntax: 
# package target
rbs build services/api server

# Multiple targets in same package
rbs build services/api server server_test

# Root package targets
rbs build hello

​
Dependencies

Targets can depend on other targets. RBS automatically builds dependencies in the correct order using a dependency graph (DAG).

​
Local dependencies

Reference targets in the same package with :name: 
py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [":utils", ":models"],   # Same-package dependencies
)

​
Cross-package dependencies

Reference targets in other packages with //package:target: 
py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [
        "//libs/common:utils",       # Cross-package dependency
        ":local_lib",                 # Same-package dependency
    ],
)

​
External dependencies

Reference packages managed by RBS from your WORKSPACE.rbs: 
py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [
        "@external://requests:2.31.0",   # External pip package
    ],
)

​
Output directory

RBS places all build outputs in the .rbs/ directory on the server, organized by platform: 
.rbs/
├── bin/linux-amd64/           # Compiled binaries
├── out/linux-amd64/           # General outputs
├── testlogs/linux-amd64/      # Test logs and coverage reports
├── toolchains/                # Managed toolchains
└── external-deps/             # Cached external dependencies
Build outputs are accessible from your editor and via the RBS dashboard.

​
Output path variables

In BUILD.rbs files, use the built-in output_path variable to reference output directories:
VariablePath
output_path.bin.rbs/bin/{platform}
output_path.out.rbs/out/{platform}
output_path.testlogs.rbs/testlogs/{platform}
native.task(
    name = "generate_report",
    command = ["sh", "-c", "echo 'Report' > " + output_path.out + "/report.txt"],
    outputs = [output_path.out + "/report.txt"],
)

​
Platform detection

RBS servers run on Linux by default. You can use the platform variable in your BUILD.rbs files: 
native.task(
    name = "build",
    command = ["echo", "Building on " + platform.name],
)

​
Platform constraints

Restrict targets to specific platforms: 
native.task(
    name = "linux_only",
    command = ["echo", "Linux specific"],
    target_compatible_with = ["@platforms//os:linux"],
)

​
Hermetic builds

RBS ensures hermetic builds — every dependency, toolchain, and runtime is managed by the platform. This means:
  • No local dependencies: You don’t need Python, Node.js, or Java installed on your machine.
  • Reproducible: The same build always produces the same output, regardless of who runs it.
  • Consistent across branches: Every branch server starts from a clean, identical base.
  • Portable: Your project works identically in development and production.

​
Next steps

RBS DSL reference

Learn the full syntax for BUILD.rbs and WORKSPACE.rbs files.

Language SDKs

Set up your first language SDK.