--- source: CrewKit documentation url: https://crewkit.io/docs/workspace-setup.md title: "Set up a workspace" description: "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](/docs/workspaces#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 ```bash 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](/docs/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 `. - 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](#8-give-the-workspace-a-slack-agent). 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](/docs/workspaces#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 ` 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](/docs/api-overview)): `POST /api/v1//projects//repositories//webhook`, where `` is the linked repository's id from `GET /api/v1//projects//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](/docs/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 (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](/docs/workspace-handoff#agent-settings). --- ## Next steps - [Fix a ticket end to end](/docs/workspace-fix) - [Workspaces](/docs/workspaces)