Skip to documentation
Documentation
Documentation
OverviewInstallationQuickstartConfigurationTroubleshootingFAQ

Usage

Terminal interfaceCLIDashboardAnalytics

Collaborate

ArtifactsSession sharingAsks privacy fact sheetBlueprintsAgent identitiesMCP server

Configure

AgentsSkillsRulesCommandsInheritancePlaybooksExperimentsHooksCapture modesTeam

Workspaces

WorkspacesSet up a workspaceFix a ticket end to endShip a feature with approvalHand off work and set agent settings

API Reference

API OverviewAuthenticationSessions APIResources APIOrganizations APIProjects APIPlaybooks APIExperiments API
Need a hand?Find an answer in troubleshooting.
Loading docs…
CREWKIT / DOCUMENTATION

Set up a workspace

Create a workspace, add its members, link its repositories, and connect your code host, Jira and Slack.

You end up with a workspace your team can start work in: its members and leads added, its repositories linked with the right base branch and reporting their pull requests, its Jira key and Slack channel set, and a local workspace folder that crewkit work runs in.

You need:

  • What every workspace guide needs — see Before you start. Each step names the role it takes.
  • A folder holding a clone of each repository, e.g. ~/code/acme/api and ~/code/acme/web.

1. Create the workspace from your local folder

cd ~/code/acme
crewkit init --workspace

Developer or above. crewkit asks for the organization (when you belong to several) and the Workspace name (default: the folder's name), creates the workspace, lists the git repositories in child folders and asks Link these repositories to the workspace? Each one is linked with its origin's default branch as its base branch. It writes .crewkit/config.toml and ends with Workspace acme initialized. With --yes it takes every default without asking.

crewkit init --workspace always creates a new workspace. The dashboard's New Project form (Kind Workspace) creates one too, but gives you no local folder for crewkit work, so start from the CLI.

2. Add members and leads

Creating the workspace did not make you its member or lead, and until it has a lead only managers and above can manage it or start work in it. So this step comes first, by a manager or above (or, later, by an existing lead). If you are a developer, ask a manager to add you as its lead.

Open the workspace from Projects. In the Members card, choose a person in Choose a person, pick Member or Lead, and click Add. To promote someone later, change their role to Lead in their row. Invite people to the organization first — see Team.

3. Add member projects

On the same page, in the Member projects card, choose a repository project in Choose a project and click Add. Their repositories, skills and agents become available in the workspace. Leads, or managers and above.

4. Fix repositories if needed

Click Settings on the workspace page. The Repositories card lists every linked repository with its Base branch — the branch work is cut from and pull requests go into. Repositories from a member project show · via <project>.

  • A clone init skipped: click Add Repository, enter its Name (e.g. api) and Remote URL, and click Add Repository.
  • A wrong base branch (managers and above): click the pencil next to it, type the branch, and click Save.

5. Set the Jira key and the Slack channel

Still on Settings, under Project Details (leads, or managers and above):

  • Jira project key — e.g. CREW. Leave it empty to fall back to the member projects' keys.
  • Slack channel for work updates — the channel id, e.g. C0123456789. Work items post there through the workspace's Slack agent, set up in step 8. Leave it empty to post nothing.

Click Save Changes.

6. Connect Jira

An admin or owner opens Integrations in the sidebar and, under Issue tracker, clicks Connect Jira:

  • Site URL — https://your-site.atlassian.net, with no path
  • Service account email
  • API token — stored encrypted, never shown again

Click Connect. crewkit uses this account to search and create Tasks and Epics, and only reads card status after that — see Jira status. Without a connection you can still start work from a card key with a title (crewkit work start CREW-123 --title "…"), but not from a description.

7. Connect your code host

crewkit learns that a pull request opened, merged or closed only from your code host's webhooks; it never polls. Without them a work item stays In review after its pull request merges, Slack posts no merge, and someone has to run crewkit work close. An admin or owner sets them up for each repository.

The webhooks are matched through the crewkit project each repository belongs to: the member project for a repository marked · via <project> in Settings → Repositories, the workspace itself otherwise. A project links one repository, so of the repositories the workspace holds itself, only one can report; give each of the others its own member project.

GitHub:

  1. Open Integrations in the sidebar and, under Git providers, click Connect on the GitHub row, and authorize crewkit on GitHub.
  2. Open the project the repository belongs to, click Settings, and in the Repository card click Link Repository. Pick the repository and click Link Repository.
  3. Register the repository's webhook. The dashboard has no button for this yet, so call the API as an admin (see API overview): POST /api/v1/<org>/projects/<project>/repositories/<repository>/webhook, where <repository> is the linked repository's id from GET /api/v1/<org>/projects/<project>/repositories.

GitLab:

  1. Open Integrations and, under Git providers, click Connect GitLab to connect a top-level group.
  2. Under the GitLab group's row, click Link a project, pick the GitLab project and choose the crewkit project it belongs to. Linking registers the webhook; the row reads Receiving events once GitLab delivers.

8. Give the workspace a Slack agent

Work items post to the channel from step 5 through an active team agent of the workspace that has a Slack workspace ID. Without one, nothing is posted and nothing reports an error.

  1. An admin or owner opens Integrations and, under Messaging, clicks Connect Slack.
  2. A manager or above opens the workspace page, clicks Team Agents, then New team agent, and fills in its Slack handle and Slack workspace ID (e.g. T0123456789). See Agent identities. Pausing or archiving the agent stops the posts.

9. Set up the folder on other machines

Each teammate needs a folder with clones of the same repositories, marked as this workspace. Because crewkit init --workspace would create a second workspace, copy .crewkit/config.toml from your workspace folder to the same place in theirs instead. It holds the organization's and workspace's ids and names, never a credential.

crewkit trusts the copy only if the workspace folder, its .crewkit folder and config.toml are all owned by the teammate who runs crewkit, and neither .crewkit nor config.toml is a symbolic link. Otherwise it ignores the file without saying so, and crewkit work reports not in a crewkit workspace directory. Copy it as that teammate, not with sudo.

If it stops

  • Workspace already initialized — this folder already belongs to a workspace. Delete .crewkit/config.toml only if you really want a new one.
  • Skipped <folder> (no git remote) — that clone has no origin. Add one and link it with Add Repository.
  • not in a crewkit workspace directory — run crewkit work from the workspace folder or below it.
  • Agent settings: held back … — see agent settings.

Next steps

  • Fix a ticket end to end
  • Workspaces

Workspaces

Plan and ship work across several repositories, keyed to Jira cards.

Fix a ticket end to end

Start a fix from a Jira card, work in its worktrees, save, open pull requests and close it.

On this page

1. Create the workspace from your local folder2. Add members and leads3. Add member projects4. Fix repositories if needed5. Set the Jira key and the Slack channel6. Connect Jira7. Connect your code host8. Give the workspace a Slack agent9. Set up the folder on other machinesIf it stopsNext steps