Lesson 2: Multi-Repo Workflows

Video Walkthrough

See multi-repo workflows in action:

The Problem

Real-world projects often span multiple repositories:

• A frontend app that consumes a backend API
• A shared library used by several services
• A monorepo with multiple packages that depend on each other

When you change an API endpoint in the backend, the frontend types need to update too. When you modify a shared utility, every consumer needs to be tested. ReArch handles this with workspace-aware agents.

Configuring a Workspace

A workspace connects multiple repositories under a single ReArch configuration:

~/.rearch/workspace.yaml

workspace:
  name: acme-platform
  repos:
    - name: frontend
      path: ~/code/acme-frontend
      language: typescript
      framework: next
    - name: backend
      path: ~/code/acme-backend
      language: typescript
      framework: express
    - name: shared
      path: ~/code/acme-shared
      language: typescript

Create the workspace:

rearch workspace init --config ~/.rearch/workspace.yaml

Cross-Repo Tasks

Assign a task that spans repositories:

rearch task create \
  --workspace acme-platform \
  --description "Add a new /api/invoices endpoint to the backend and create a corresponding API client in the frontend shared library" \
  --repos backend,shared,frontend

The agent will:

1. Backend: Create the endpoint, add validation, write tests
2. Shared: Generate TypeScript types and an API client function
3. Frontend: Import the new client and add a basic UI hook

Each repository gets its own pull request, and they are linked together in the PR descriptions.

Dependency-Aware Ordering

ReArch understands dependency graphs. If frontend depends on shared, the agent:

1. Makes changes to shared first
2. Runs shared tests to confirm nothing broke
3. Updates frontend to use the new shared exports
4. Runs frontend tests

You can define these relationships explicitly:

workspace:
  dependencies:
    frontend:
      - shared
    backend:
      - shared

Or let ReArch auto-detect them from package.json, go.mod, Cargo.toml, etc.

Monorepo Support

For monorepos using Turborepo, Nx, or pnpm workspaces, ReArch detects the package structure automatically:

# In a monorepo root
rearch init --monorepo

This scans your workspace configuration and creates per-package contexts:

.rearch/
├── config.yaml
├── packages/
│   ├── web.yaml          # Config overrides for packages/web
│   ├── api.yaml           # Config overrides for packages/api
│   └── shared.yaml        # Config overrides for packages/shared

Tasks can target specific packages:

rearch task create \
  --description "Add rate limiting to the API package" \
  --package api

Coordination Strategies

Strategy	When to use	Configuration
Sequential	Changes must be applied in order	coordination: sequential
Parallel	Independent changes across repos	coordination: parallel
Staged	Shared lib first, consumers second	coordination: staged (default)

.rearch/pipelines/cross-repo.yaml

pipeline:
  name: cross-repo
  coordination: staged
  steps:
    - explore_all
    - plan_changes
    - implement_dependencies_first
    - implement_consumers
    - test_all
    - create_prs

What’s Next

In the next lesson, you will learn how to trigger ReArch tasks automatically from your CI/CD pipeline.

---