Code Federation

The problem

Polyrepo or monorepo. Both are broken.

Every engineering organization eventually faces the same fork in the road. Both paths cost.

scatter_plot

Polyrepo

closeFragmented

closeDuplicated tooling and CI
closeGovernance impossible to enforce
closeCross-repo changes take days

database

Monorepo migration

timerCostly

closeMulti-quarter migration project
closeCustom build infrastructure
closeTooling breaks at scale

layers

checkReversible

check_circleOne unified workspace
check_circleNo migration. Your repos stay put.
check_circleReversible at any time

Most organizations live with the polyrepo problem because the monorepo solution costs more than the pain. Code Federation is the third option: developers get the experience of working in a single repository while your existing repository structure stays intact.

The product

A federated layer over the repos you already have.

Code Federation composes any number of repositories into a virtual monorepo — mounted, not cloned. Developers see one tree. Changes route back to native commits in each upstream.

layers

Federation
Component

Composes any number of upstream repositories into a virtual monorepo, and routes outbound changes back to each one through a Federated PR.
cloud_sync

Federated Remote Workspace
Component

A per-user state layer that holds your edits, branches, and index against the virtual monorepo. Materialized lazily; nothing on disk by default.
terminal

gitfs
Local client

A thin FUSE client that mounts a Workspace as a local directory. Your IDE, your git CLI, and your scripts work against it unchanged.
shield

Governance
Property

Not a separate product. Every API publishes structured events, every Workspace runs as an authenticated principal, and the layer model lets platform teams own paths across repositories by construction.
smart_toy

Agent context
Property

Because the whole federation mounts as one real directory, coding agents like Copilot, Claude Code, Cursor, and others get a 360° view across every repository — not just the one you cloned. See how →

Developer machine

codeIDE terminalgit CLI folder_openFUSE mount conversion_pathgitfs

gitfs

Code Federation

layersFederation API edit_noteWorkspace API databaseRepository API

git protocol

Upstream repositories

GitHub GitLab Bitbucket dnsSelf-hosted

01 — Composition

Federation

A virtual monorepo composed of upstream repositories arranged as layers. The Federation API defines the stack and its order; on commit, a routing file fans changes back to the right upstream.

Layers stack like a Docker image: the topmost layer wins on conflicts; lower layers contribute everything the top hasn’t claimed. Platform teams own shared paths — build configuration, CI definitions, schemas — while individual teams own everything else in their own repositories.

Developers see a single tree with the full commit history of every layered repository merged into one DAG. They branch, commit, and push as they would in any Git repository, without knowing how many repositories are underneath.

1 Compose

Upstream repositories as layers

Top wins on conflict.

layer-0 platform

descriptionBUILD

descriptionMODULE.bazel

folder.github/

layer-1 api-team

descriptionapi/user.proto

folderapi/billing/

layer-2 web-team

descriptionweb/Home.tsx

descriptionweb/styles.css

layer-3 base

BUILD

descriptionREADME.md

descriptionsrc/main.go

2 Virtual monorepo

One tree, one history

Resolved files, tagged by source layer.

├ .github/L0
├ api/
│ ├ billing/L1
│ └ user.protoL1
├ web/
│ ├ Home.tsxL2
│ └ styles.cssL2
├ BUILDL0
├ MODULE.bazelL0
└ README.mdL3

3 Route

FEDERATION.sky fans out to upstreams

First rule that matches wins.

description FEDERATION.sky starlark

*.proto arrow_forward api-protos

BUILD · MODULE.bazel · *.bzl arrow_forward build-infra

web/** arrow_forward web-app

README.md · docs/** arrow_forward docs

Hover a layer to see what it contributes and where it lands. The Federation API defines what stacks; FEDERATION.sky defines where commits go on the way out. Unmatched files fall to the Federated PR’s default repository.

The Federated PR lifecycle

1

Plan. Code Federation generates a deterministic rollout plan — exactly which commits, trees, and blobs will be written to which repositories. If anything changes underneath, the plan is rejected and a new one is required.
2

Rollout. Code Federation writes the planned commits directly to the target branch of each upstream repository. Reviews happen once, in the Federated PR.
3

Speculative rollout (coming soon). For organizations that require upstream review on each repository, Code Federation can instead open native pull requests in each upstream and merge them when their preconditions are met.

In practice

One change. Three repositories. One review.

A protobuf API definition with artifacts in three repositories. Today: three PRs, three reviews, manual sequencing — and a coding agent that can only see one of them at a time. With Code Federation, the whole change (and the agent driving it) works across all three:

Step 01

Mount the Workspace

Three upstream repositories — api-protos, build-infra, generated-go — layered into one Workspace, mounted as a local directory.

terminal Terminal

                    $ gitfs mount ./workspace \
                    --workspace projects/acme/codebases/api/workspaces/me
                    ✓ mounted
                    · 3 layers · 0 bytes on disk
                  

workspace/ ← virtual monorepo ├── api/ │ └── user.proto [api-protos] ├── gen/ │ └── user.pb.go [generated-go] ├── BUILD [build-infra] ├── FEDERATION.sky [federation] └── README.md [base]

Step 02

Edit the source you own

Add a name field. Update the BUILD rule. Two files, two repositories — the generated gen/user.pb.go comes next, server-side.

difference api/user.proto api-protos +1 -0

                    // api/user.proto message User { string id =
                    1; string email = 2;
                    + string name = 3;
                    }
                  

difference BUILD build-infra +1 -1

                    proto_library( name = "user_proto", srcs = ["api/user.proto"],
                    - deps = [],
                    + deps = ["@com_google_protobuf//:any_proto"],
                    )
                  

Step 03

Server tasks regenerate artifacts on save Coming soon

Reactive, server-side. When you save a .proto (not commit), a task subscribed to that path runs in the Workspace API, regenerates gen/user.pb.go, and materializes it back into your mount — like CI, but at save granularity and against your in-progress edits.

saveSave event

api/user.proto 432 B

Workspace API publishes a file-change event for any subscribed task.

easttrigger

boltServer task

protoc-gen-go running…

Subscribed to **/*.proto. Runs server-side, not on your laptop.

eastmaterialize

folder_openWorkspace mount

gen/user.pb.go generated

Written back through the FUSE mount — your IDE sees it immediately.

Not CI. CI runs after a push and writes to artifacts. Server tasks run on save, inside the Workspace API, and write directly into your in-progress working tree. The Federated PR (Step 05) still fans the generated file out to generated-go on rollout — you just didn’t have to author it.

Step 04

Commit — gitfs moves objects upstream

A commit moves your three working-tree edits from the per-user Workspace API (mutable WIP) into the shared Repository API (immutable, content-addressed) — the same way git push moves local commits to a remote.

terminal Terminal

                    $ git add api/user.proto
                    BUILD gen/user.pb.go $
                    git commit -m
                    "feat(user): add name field"
                    [workspace/me a1b2c3d] feat(user): add name field
                     3 files changed, 7 insertions(+), 1 deletion(-)
                  

edit_noteWorkspace API

per-user, mutable WIP changes

api/user.proto staged moved

BUILD staged moved

gen/user.pb.go staged moved

east gitfs

databaseRepository API

shared, content-addressed objects

blob e4f2a1c stored

blob 7b9d83e stored

blob c2104ff stored

tree 2d6a91b stored

commit a1b2c3d HEAD stored

Step 05

Open a Federated PR

FEDERATION.sky routes each file in the commit to its destination upstream. Each routed group becomes a per-repository diff inside one PR.

feat(user): add name field #421 · 3 repositories

descriptionFEDERATION.sky 3 files routed · +7 / -1

database api-protos ← api/user.proto +1 -0 modified

message User { string id = 1; string email = 2; + string name = 3; }

database build-infra ← BUILD +1 -1 modified

proto_library( name = "user_proto", - deps = [], + deps = ["@com_google_protobuf//:any_proto"], )

database generated-go ← gen/user.pb.go +5 -0 modified

type User struct { Id string // ... Email string // ... + Name string `protobuf:"bytes,3,opt,name=name"` } + func (x *User) GetName() string { ... }

Step 06

Rollout — click to run

After approval, the PR rolls out as native commits in each upstream. Hit Run rollout to watch it land.

desktop_windows Console — representative mock

Approved · Ready to roll out #421

api-protos main api/user.proto Pending

build-infra main BUILD Pending

generated-go main gen/user.pb.go Pending

celebration 3 native commits landed in 3 upstream repositories.

01 / 06

02 — Workspaces

Federated Remote Workspace

A per-user state layer on top of the virtual monorepo. Mounted, not cloned. Your laptop becomes a thin client.

Committed objects are shared, content-addressed, and immutable; your edits, branches, and index are private. The Workspace mounts as a local FUSE filesystem — git status, git add, git commit, your IDE all work unchanged. Nothing is on disk by default. Objects materialize lazily as you read.

No multi-terabyte clones.

Large monorepos that would refuse to clone — or take hours to do so — mount in seconds. Working tree size is bounded by what you actually touch.

Portable across devices.

Your in-progress work lives server-side. Open your laptop in the morning, mount the same Workspace on a different machine in the afternoon, finish the commit from a third device. Nothing to copy, nothing to lose.

Faster onboarding.

A new engineer doesn’t run git clone, make bootstrap, or fight a toolchain. They authenticate, mount the Workspace, and start reading code.

A Workspace, end to end

From creating a codebase to pushing a commit — plus a glimpse of what’s next.

Step 01

Create a Workspace, then mount it

Same shape as a Federated PR: pick the codebase, name the Workspace. The server allocates per-user state (HEAD, branch refs, an empty index) against the existing virtual monorepo — no bytes copied yet. Then one CLI command attaches a FUSE filesystem at a local path.

desktop_windows Console — New Workspace mock

Codebase

Workspace name

me

Step 02

Listing a directory materializes its tree

First, attach a FUSE filesystem at a local path. Then run ls and the kernel asks gitfs for that path. gitfs fetches just the tree metadata from the Repository API — entries, modes, object IDs — never the file content. The kernel returns the listing; nothing is on disk yet.

terminal Terminal — mount & list

                    $ gitfs mount ./workspace \
                    --workspace projects/acme/codebases/api/workspaces/me
                    ✓ mounted
                    · FUSE attached · 0 bytes resident

                    $ ls ./workspace
                    api/ BUILD FEDERATION.sky
                    gen/ README.md src/
                    web/

                    $ ls ./workspace/api
                    billing/ user.proto
                  

cloud_downloadRepository API · trace

GET tree HEAD (root) 7 entries · 412 B · 184 ms

GET tree api/ 2 entries · 178 B · 22 ms

Workspace state

├ api/listed
│ ├ billing/not fetched
│ └ user.protonot fetched
├ BUILDnot fetched
├ FEDERATION.skynot fetched
├ gen/not fetched
└ README.mdnot fetched

On disk: 2 directories listed · 0 files downloaded ~590 B

Step 03

Blobs download only when you read them

Open api/user.proto in your editor: the kernel asks for content, gitfs requests the blob by content-address from the Repository API and streams it back. Once fetched, it’s cached for re-reads. Working tree size grows only with what you touch.

terminal Terminal

                    $
                    cat ./workspace/api/user.proto
                    // api/user.proto
                    message User { ... }

                    $
                    open ./workspace/web/Home.tsx
                    # IDE opens it
                  

cloud_downloadRepository API · trace

GET blob 7b9d83e api/user.proto 412 B · 18 ms

GET blob c2104ff web/Home.tsx 2.4 KB · 24 ms

CACHED 7b9d83e re-read api/user.proto 412 B · 0 ms

Workspace state

├ api/listed
│ ├ billing/not fetched
│ └ user.protodownloaded · 412 B
├ BUILDnot fetched
├ web/listed
│ └ Home.tsxdownloaded · 2.4 KB
└ README.mdnot fetched

On disk: 3 directories listed · 2 files downloaded ~3.3 KB

Step 04

Push commits to the virtual monorepo

Save uploads your edit to the Workspace API. git commit turns staged edits into a commit; its blobs and trees move into the Repository API as content-addressed objects — the same way git push moves local commits to a remote.

terminal Terminal

                    $ git add api/user.proto
                    [gitfs] upload edit → Workspace API · 432 B
                    $ git commit -m
                    "feat(user): add name field"
                    [gitfs] push blob e4f2a1c → Repository API
                    [gitfs] push tree 2d6a91b → Repository API
                    [gitfs] push commit a1b2c3d → Repository API
                    ✓ HEAD now a1b2c3d
                  

01 / 04

How gitfs merges the two APIs

The Repository API serves immutable, content-addressed objects. The Workspace API serves your private, in-progress state — including a per-user .git/ directory. gitfs materializes both and lets Workspace API objects override Repository API objects wherever their paths overlap.

top · wins on overlap

edit_noteWorkspace API

per-user · mutable · private

.git/user-only
.git/HEADuser-only
.git/indexuser-only
api/user.protooverrides
BUILDWIP edit

conversion_path

gitfs

FUSE merge · Workspace overrides Repository on overlap

south materialize

fallback · shared

databaseRepository API

immutable · content-addressed

api/user.protoshadowed
api/billing/
gen/user.pb.go
web/Home.tsx
README.md

folder_open workspace/ virtual working tree

W.git/user-only
Wapi/user.protoWIP edit overrides shared
Rapi/billing/
WBUILDWIP edit
Rgen/user.pb.go
Rweb/Home.tsx
RREADME.md

03 — Governance

Built for governance

The federated layer is the right place to enforce policy. Repository-level permissions on GitHub and GitLab cannot express “this team can read everything in api/ but only modify api/billing/” — they were never meant to.

Code Federation’s architecture is built around what governance requires: every mutation publishes a structured event, every Workspace runs in the context of an authenticated identity, and the layer model lets platform teams own shared paths across repositories.

10:42 commit.write a1b2c3d acme/api

10:42 pr.route #421 · 3 repos fed.sky

10:43 rollout.land api-protos main

Event-sourced

Every mutation across the Federation, Repository, and Workspace APIs publishes a structured event. The audit trail is a property of the system, not a feature you turn on.

Identity-aware

Every Workspace, every Federated PR, every routing decision happens in the context of an authenticated principal. There is no “anonymous read” path to file content.

layer-0 platform lock

layer-1 api-team lock_open

layer-2 web-team lock_open

Layer-bound ownership

Because layers stack with explicit priority, the platform layer can own paths that tenant layers cannot override. Ownership is enforced by composition, not by convention.

Per-path ACLs, file-level audit logs, and policy enforcement at routing time grow naturally on these foundations — not bolted on later.

04 — Agentic development

Coding agents work better with a 360° view.

Copilot, Claude Code, Cursor, and others are scoped to the repository you opened. The definitions, build rules, and callers they need often live in a repository they can’t see — so they guess. Code Federation mounts every upstream as one tree, giving the agent the whole picture.

Repo-scoped agent

errorPartial context

Copilot · Claude Code · Cursor & others — scoped to the repo you cloned

smart_toy agent 1 repo

visibility_off 1 of 4

folderweb-app in view

› where is the User.phone field defined? ✗ not in this repository — guessing the schema… - string phone = 5; // field number unknown

✗Guesses at APIs and types that actually live in another repo
✗Can’t open the build rule that compiles the change
✗A cross-repo edit stops dead at the repository boundary

Federation-mounted agent

check_circle360° context

The same agent, run against a Workspace — one tree over every repo

smart_toy agent all repos

hub one tree

folderapi-protos in view

folderbuild-infra in view

folderweb-app in view

foldergenerated-go in view

› where is the User.phone field defined? ✓ api-protos/user.proto:12 — next free field number is 4 + string phone = 4; // edits api-protos, build-infra & web-app

✓Reads the real definition across every upstream, not a guess
✓Follows types and callers straight through repo boundaries
✓Edits and commits span repos, landing in one Federated PR

Agents are only as good as the context they can reach. Because Code Federation composes your repositories into one virtual tree — and mounts it as a real directory through gitfs — any agent that works in a folder now works across your whole infrastructure. No new integration to build; the 360° view is just the filesystem.

Comparisons

Why not submodules, or a monorepo?

Code Federation is a new shape. Compare against the alternatives.

Monorepo migration

01 / 06

warningWhere it falls short

A multi-quarter project. Custom build infrastructure (Bazel at scale). Tooling that breaks above a certain size — git status, IDE indexers, CI. Often shelved before completion.