---
title: "Workspace Governance"
description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime governance alongside git-level governance."
---

# Workspace Governance

<Callout tone="info">

**Developer page.** This page is for platform engineers setting up repo governance — branching, code review, CI. It covers **governance**: who reviews, approves, and owns what across many apps in one repo. For the agent customization layer (Agent Resources: `AGENTS.md`, memory, skills, custom agents) see [Agent Resources](/docs/agent-resources); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).

</Callout>

This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the Dispatch control plane fits into your governance model.

<Diagram id="doc-block-1krauqp" title="Two governance planes" summary={"Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."}>

```html
<div class="gov">
  <div class="diagram-card">
    <span class="diagram-pill accent">Git / GitHub</span
    ><strong>Code governance</strong>
    <div class="gov-list">
      <span class="diagram-pill">CODEOWNERS</span
      ><span class="diagram-pill">branch protection</span
      ><span class="diagram-pill">PR review</span
      ><span class="diagram-pill">git log / blame</span>
    </div>
  </div>
  <div class="diagram-pill diagram-muted">+</div>
  <div class="diagram-card">
    <span class="diagram-pill accent">Dispatch</span
    ><strong>Runtime governance</strong>
    <div class="gov-list">
      <span class="diagram-pill">vault secrets &amp; grants</span
      ><span class="diagram-pill">workspace resources</span
      ><span class="diagram-pill">agent profiles</span
      ><span class="diagram-pill">approvals &amp; audit</span>
    </div>
  </div>
</div>
```

```css
.gov {
  display: flex;
  align-items: center;
  gap: 16px;
  flex-wrap: wrap;
}
.gov .diagram-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 16px 18px;
  flex: 1;
  min-width: 240px;
}
.gov .gov-list {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
  margin-top: 4px;
}
```

</Diagram>

## Branching

### Feature Branches

Use short-lived feature branches for all work:

```text
main                         ← production
├── feat/mail-filters        ← single-app change
├── feat/core-oauth-refresh  ← framework change
├── fix/analytics-chart      ← targeted bug fix
└── feat/vault-encryption    ← dispatch/infra change
```

**Naming conventions:**

- **Single-app changes:** `feat/<app>-<description>` or `fix/<app>-<description>` — e.g. `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
- **Framework changes:** `feat/core-<description>` or `fix/core-<description>` — e.g. `feat/core-polling-v2`
- **Dispatch changes:** `feat/dispatch-<description>` — e.g. `feat/dispatch-vault-policies`
- **Cross-app changes:** if a framework change requires template updates, do both in one branch so they ship atomically

Keep branches short-lived. Long-lived branches diverge from main and create painful merges — especially in a monorepo where multiple teams push daily.

### Non-Developer Branching

Not everyone who needs to make changes is comfortable with git. [Builder.io](https://www.builder.io?utm_source=agent-native&utm_medium=docs&utm_campaign=framework&utm_content=workspace_management) supports a visual branching model that maps to git branches under the hood — useful for content and copy changes, layout adjustments, design iterations, and A/B testing without a dev environment.

## Code Ownership

Code governance is configured by a handful of files at the repo root:

<FileTree
  id="doc-block-b82ryc"
  title="Governance config in the repo"
  entries={[
    {
      path: ".github/CODEOWNERS",
      note: "Auto-assigns reviewers per changed path",
    },
    {
      path: ".github/labeler.yml",
      note: "Auto-labels PRs by app",
    },
    {
      path: "pnpm-workspace.yaml",
      note: "Workspace-level — broad review",
    },
    {
      path: "package.json",
      note: "Workspace-level — platform team owns",
    },
  ]}
/>

GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. Create `.github/CODEOWNERS` at the repo root:

```text filename=".github/CODEOWNERS"
# Framework core — affects every app; platform team reviews all changes
packages/core/                     @your-org/platform-team

# Dispatch control plane — secrets, integrations, workspace resources
templates/dispatch/                @your-org/platform-team

# Per-app ownership — each team reviews their own app
templates/mail/                    @your-org/mail-team
templates/analytics/               @your-org/analytics-team
templates/calendar/                @your-org/calendar-team
# ... add an entry per app

# Workspace-level config — broad review since it affects everyone
.github/                           @your-org/platform-team
package.json                       @your-org/platform-team
pnpm-workspace.yaml                @your-org/platform-team
```

Key tips: use GitHub teams (`@org/team`), not individuals. Framework and Dispatch changes should always require platform review. See [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) for glob syntax and multiple-owner patterns.

To enable required reviews: Settings → Branches → Branch protection for `main` → **Require a pull request before merging** → **Require review from Code Owners**.

## PR Labeling

Auto-label PRs by app with `.github/labeler.yml` (excerpt):

```yaml
app:mail:
  - changed-files:
      - any-glob-to-any-file: templates/mail/**
app:analytics:
  - changed-files:
      - any-glob-to-any-file: templates/analytics/**
core:
  - changed-files:
      - any-glob-to-any-file: packages/core/**
```

Then add the [actions/labeler](https://github.com/actions/labeler) action — see that repo's README for the full workflow YAML. Labels apply automatically when PRs are opened or updated.

## PR Review Guidelines

| Change type                       | Who reviews                           | What to watch for                                                         |
| --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
| **App-only** (`templates/<app>/`) | Owning app team                       | Domain correctness, action schemas                                        |
| **Framework** (`packages/core/`)  | Platform team + one affected app team | Breaking changes, performance, backwards compat                           |
| **Schema migrations**             | Platform team + senior engineer       | Data safety, dialect agnosticism (SQLite + Postgres)                      |
| **Actions**                       | Owning team                           | Actions are both agent tools AND HTTP endpoints — review from both angles |
| **Cross-app A2A**                 | Both app teams                        | If you change an A2A interface, the callers need to know                  |
| **Dispatch vault/resources**      | Platform team                         | Secret access, grant scope, who gets what                                 |

### Concurrent Agent Work

Agent-native workspaces often have multiple AI agents working on the same branch simultaneously. This is by design — the agents share a branch and push independently.

<Callout id="doc-block-smcj91" tone="warning">

**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken.

</Callout>

When reviewing PRs in this environment:

- **Don't revert changes you didn't make** unless they're clearly broken
- **Files may be modified by multiple agents** in the same PR — this is normal
- **Run `pnpm run prep`** (typecheck + test + format) before pushing to catch integration issues between agents' changes
- **If two agents touch the same file,** the later commit wins. Conflicts surface at review time, not at commit time
- **Fix bugs in any code in the PR,** regardless of which agent wrote it. The PR is reviewed as a whole.

## Dispatch as Governance

The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It complements git-level governance with runtime governance:

| Concern                         | Git / GitHub                  | Dispatch                                                     |
| ------------------------------- | ----------------------------- | ------------------------------------------------------------ |
| Who can change code             | CODEOWNERS, branch protection | —                                                            |
| Who can access secrets          | —                             | Vault policy, grants, request workflow                       |
| What instructions agents follow | —                             | Global workspace resources (AGENTS.md, instructions, skills) |
| Which agents are shared         | —                             | Workspace agent profiles                                     |
| Integration inventory           | —                             | Workspace connections and integrations catalog               |
| Runtime change approval         | —                             | Dispatch approval flow                                       |
| Audit trail                     | `git log` / `git blame`       | Vault audit + dispatch audit logs                            |
| Messaging & routing             | —                             | Slack / Telegram integration                                 |

**Git handles code governance. Dispatch handles runtime governance.** Don't try to replicate git workflows inside Dispatch or vice versa.

Dispatch manages: vault secrets, reusable workspace connections, workspace resources (skills, instructions, agent profiles, MCP servers), approvals, and audit logs. For public app route configuration (`workspaceApp.audience` / `publicPaths` / `protectedPaths`), see [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).

For the resource model and canonical paths, see [Agent Resources — Global resources](/docs/agent-resources#global-resources).

## Setup Checklist

For a new workspace, after running `npx @agent-native/core@latest create`:

**Git & GitHub:**

- [ ] Create `.github/CODEOWNERS` with per-app team ownership
- [ ] Enable branch protection on `main` with required code owner reviews
- [ ] Add `.github/labeler.yml` for auto-labeling PRs by app
- [ ] Create GitHub teams for each app and the platform team

**Dispatch:**

- [ ] Add shared secrets to the vault (API keys, OAuth credentials, etc.)
- [ ] Keep the default all-apps vault policy or switch to manual per-app grants
- [ ] Sync vault secrets to push them to apps
- [ ] Register reusable workspace connections for shared provider accounts, then
      grant apps such as Brain, Analytics, Mail, or Dispatch only when they need
      that account
- [ ] Add workspace-wide skills, guardrail instructions, and brand/company reference resources via the Resources page. See [Agent Resources](/docs/agent-resources#global-resources) for the full resource-model table and the recommended starter pack.
- [ ] Configure the approval policy and approver emails
- [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
- [ ] Connect Slack or Telegram for workspace messaging
- [ ] Configure shared MCP servers — see [Multi-App Workspaces — Shared MCP servers](/docs/multi-app-workspace#shared-mcp)

## What's next {#whats-next}

- [**Agent Resources**](/docs/agent-resources) — the customization layer this page governs (skills, memory, agents, MCP servers)
- [**Multi-App Workspaces**](/docs/multi-app-workspace) — the deployment shape: one monorepo, many apps
- [**Dispatch**](/docs/dispatch) — the runtime control plane referenced throughout this page
- [**Sharing**](/docs/sharing) — access control for individual resources, complementing repo-level CODEOWNERS
- [**Audit Log**](/docs/audit-log) — the action-level audit trail that complements `git log`/`git blame`