---
source: CrewKit documentation
url: https://crewkit.io/docs/workspaces.md
title: "Workspaces"
description: "Multi-repo projects for teams with split codebases."
---


Workspaces let you group multiple git repositories under a single project. Use them when your team splits code across repos (e.g., frontend and backend) but wants unified session tracking and analytics.

---

## When to use workspaces

- **Multi-repo teams** — Frontend in one repo, backend in another, but they're all part of "Customer Portal"
- **Monorepo with components** — Single repo with distinct components that get separate session tracking
- **Microservices** — Multiple services that belong to the same product

If you have a single repo per project, you don't need workspaces. The regular project setup works fine.

---

## Create a workspace

### Dashboard

1. Go to **Projects** > **New Project**
2. Select **Workspace** as the project type
3. Name it (e.g., "Customer Portal")
4. Add repositories by their git remote URLs

### CLI

```bash
crewkit init --workspace
```

This walks you through creating a workspace project and linking the current repo.

---

## Link repositories

Add repos to an existing workspace:

### Dashboard

Go to your project settings and click **Add Repository**. Enter the git remote URL.

### API

```bash
POST /:org_id/projects/:project_id/repos
{
  "remote_url": "git@github.com:acme/backend.git",
  "name": "backend"
}
```

---

## Session attribution

When you run `crewkit code` in a linked repo, sessions are automatically attributed to the correct repository and project. The CLI:

1. Reads your git remote
2. Matches it to a linked repository
3. Detects the component (api, dashboard, cli) from your working directory
4. Tags the session with repository and component

In the dashboard, sessions show a repository badge so you can tell which repo they came from.

---

## Filtering by repository

Workspace projects show a repository filter dropdown in the sessions list. Filter to see sessions from a specific repo, or view all sessions across the workspace.

---

## CI/CD integration

For CI/CD, set the repository ID explicitly:

```bash
# Via environment variable
export CREWKIT_REPOSITORY_ID=repo_abc123
crewkit code --yes --prompt "Run tests"

# Via flag
crewkit code --yes --repo-id repo_abc123 --prompt "Run tests"
```

---

## Session visibility

Each repository has a session visibility setting:

| Level | Who can see sessions |
|-------|---------------------|
| **Public** | All project members |
| **Restricted** | Repo contributors + managers |
| **Private** | Session owner + admins only |

Configure this per-repository in the dashboard or API.

---

## Analytics

Workspace analytics aggregate across all linked repositories. The dashboard shows:

- Total metrics across the workspace
- Per-repository breakdown as a drill-down
- Cross-repo patterns in team dashboards

---

## Next steps

- [Configuration](/docs/configuration)
- [Team management](/docs/team)
- [Analytics](/docs/analytics)