> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# workspace — Multi-Repo Orchestration

> Declare a dependency graph across repositories and apply them in the right order.

At sufficient scale, infrastructure is not one repository — it's many. The networking stack in one repo, the platform (EKS, IAM) in another, the backend services in a third, the frontend in a fourth. Each team owns their repo, each stack has its own apply pipeline. But the stacks aren't independent: the backend needs the platform to exist before it can deploy, the platform needs the networking to be in place, the frontend needs the backend API to be reachable. Running these in the wrong order produces failures. Running them manually in the right order doesn't scale. The `workspace` block is ubx's answer: a declarative manifest of your multi-repo dependency graph. Declare the repos, their stacks, and which stack depends on which, and `ubx workspace apply` runs them in topological order — parallel where safe, sequential where required.

## What you'll learn

* How `workspace` declares a multi-repo stack dependency graph
* How `depends_on` expresses cross-repo dependencies
* How `ubx workspace apply` orchestrates the graph in topological order

***

## Why this matters

<Info>
  `workspace` is documentation that runs. The dependency graph between your repositories is always implicit — `workspace` makes it explicit, machine-readable, and executable. A new team member can read the workspace manifest and immediately understand the full platform topology.
</Info>

***

## The source code

<CodeGroup>
  ```hcl main.iac theme={"theme":"css-variables"}
  # workspace "name" declares a multi-repo orchestration manifest.
  # No TypeScript/Python/Go is generated — this block is read by the
  # workspace runner (ubx workspace plan/apply) only.
  workspace "myorg" {
    repo "platform" {
      url    = "github.com/myorg/platform"
      stacks = ["networking", "eks"]
      # no depends_on — runs first, in parallel
    }

    repo "backend" {
      url    = "github.com/myorg/backend"
      stacks = ["api", "worker"]
      depends_on = {
        api    = ["platform/networking", "platform/eks"]
        worker = ["backend/api"]
      }
    }

    repo "frontend" {
      url    = "github.com/myorg/frontend"
      stacks = ["web"]
      depends_on = {
        web = ["backend/api"]
      }
    }
  }
  ```

  ```hcl ubx.iac theme={"theme":"css-variables"}
  ubx {
    name    = "workspace-multi-repo"
    runtime = "typescript"
    stacks  = ["prod"]
  }

  backend "s3" {
    bucket = "my-ubx-state"
    region = "us-east-1"
    key    = "${stack}/workspace.tfstate"
  }
  ```
</CodeGroup>

***

## How it works

<Steps>
  <Step title="ubx builds a topological sort of the stack graph">
    The workspace manifest declares stacks as nodes and `depends_on` entries as directed edges. ubx builds a DAG and topologically sorts it: `platform/networking` and `platform/eks` run first (in parallel), then `backend/api` (depends on both), then `backend/worker` and `frontend/web` (in parallel, since both depend only on `backend/api`).
  </Step>

  <Step title="Parallel stacks run concurrently">
    Stacks with no dependency relationship between them run concurrently. `platform/networking` and `platform/eks` have no declared dependency on each other — ubx runs them in parallel. `ubx workspace apply` uses goroutines to execute independent stacks simultaneously, minimising total wall-clock time.
  </Step>

  <Step title="workspace produces no generated Pulumi code">
    `workspace` blocks compile to zero TypeScript/Python/Go. They're read by the `ubx workspace` subcommand, which clones each repository, resolves the dependency graph, and runs `ubx apply` on each stack in order. The workspace runner is separate from the per-stack compiler.
  </Step>
</Steps>

***

## The execution order

```
ubx workspace apply
  │
  ├─ [parallel] platform/networking
  ├─ [parallel] platform/eks
  │
  ├─ [after platform/networking + platform/eks] backend/api
  │
  ├─ [parallel, after backend/api] backend/worker
  └─ [parallel, after backend/api] frontend/web
```

Total wall-clock time is dominated by the longest sequential chain — `platform → backend/api → frontend/web` — not the sum of all stacks.

***

## Common mistakes

<Warning>
  `depends_on` entries use the format `"repo_name/stack_name"` — for example `"platform/networking"`, not `"github.com/myorg/platform/networking"` or just `"networking"`. The repo name is the label in the `repo "..."` block, not the full GitHub URL. Using the wrong format produces a compile error.
</Warning>

<Tip>
  You don't need to declare a `workspace` block in every repository — only in the repository (or a dedicated orchestration repo) that owns the top-level orchestration manifest. Individual stack repos remain independent and can be applied directly with `ubx apply` without the workspace runner.
</Tip>

***

## Run it

```bash theme={"theme":"css-variables"}
ubx validate                    # validates the workspace manifest syntax
ubx workspace plan              # plans all stacks in topological order
ubx workspace apply             # applies all stacks in topological order
ubx workspace apply --stack backend/api  # apply a single stack only
```

***

## What you learned

<Check>`workspace` declares a multi-repo dependency graph — stacks with `depends_on` run after their prerequisites</Check>
<Check>Independent stacks run in parallel; dependent stacks run sequentially</Check>
<Check>`workspace` produces no generated code — it's read by the `ubx workspace` subcommand only</Check>

***

## Next steps

<CardGroup cols={2}>
  <Card title="remote stack reference" href="/v1/tutorials/34-remote-stack-reference">
    Consume outputs between stacks in the workspace
  </Card>

  <Card title="workspace block reference" href="/v1/language/workspace">
    Full workspace block syntax and all options
  </Card>
</CardGroup>

***

<Info>
  Full runnable example: [github.com/ubiquex/ubx-examples/36-workspace-multi-repo](https://github.com/ubiquex/ubx-examples/tree/main/36-workspace-multi-repo)
</Info>