Set up a team

A team is where kanman works with your engineers. It is bound to one tracker project and one or more repositories, and it has its own policy, budget and board. Most companies start with one team per product or service. This page walks through the setup.

Plan about 20 minutes for a typical repository. Owners, admins and members of the workspace can set up a team; viewers can’t, and kanman tells them who can. If something fails while the team is being created, nothing is left behind: your entries stay in the setup and you can try again.

Before you start

• Tracker: GitHub Issues of a repository, GitLab issues of a project, or a Jira project. kanman reads stories from it and writes approved stories back to it. You can also start without one: see Use kanman without a tracker.
• Code: the GitHub or GitLab repositories the team works on, and the base branch kanman should open pull requests against (usually main).
• A connection: you can connect GitHub, GitLab or Jira right in the first step of the setup. See Connect GitHub or Connect Jira and GitLab for the permissions.
• CI: your existing CI keeps running on kanman’s pull requests. kanman waits for it as part of verification.
• Acceptance manifest (recommended): a .kanman/acceptance.json in the repository, so kanman can prove each outcome. You can add it later; see Add an acceptance manifest.

Start the setup

Ask kanman in the conversation, for example “Set up a new team”, and kanman opens the setup. You can also choose New team in the chip under the message box, or type /new team in the message box and press Enter (Ctrl+Shift+B, Cmd+Shift+B on Mac, does the same). The setup lives at /teams/new/<step>, so every step has its own address and the browser’s back button moves between steps. It has these steps:

You can go back to any step before you create the team. Your draft is kept while you move between steps. Everything can be changed later in the team settings.

Step 1: Tracker

Pick the tracker connection the team mirrors. The list shows the tracker connections of the workspace and your own GitHub and GitLab connections.

To add one, use Add a connection below the list, without leaving the setup:

• GitHub or GitLab: Connect opens the provider’s sign-in in a small window. When you have authorized kanman, the window closes, the new connection appears in the list and is selected. If your browser blocks the window, Open in this tab runs the same sign-in in the current tab and brings you back to this step with everything you entered.
• Jira: Connect unfolds the Jira form right in the step (Jira Cloud with site, email and API token, or Jira Server / Data Center with a personal access token). After Save connection the connection is selected.

Providers that are already connected show as a connected chip. A self-managed GitLab with an access token is added once in Workspace settings > Connections.

Details and permissions:

• Connect GitHub
• Connect Jira and GitLab

Connections belong to the workspace, so a second team reuses them.

No tracker? Pick kanman board (no external tracker). It is listed even when the workspace has no connection, and the team’s stories then live on its own board. Repositories become optional, and developers can take stories from their own Claude Code. See Use kanman without a tracker and Use kanman from Claude Code or Codex.

Step 2: Project and repositories

1. Enter the Tracker project: for GitHub or GitLab issues the repository whose issues hold the stories, for Jira the project key. For Jira, kanman suggests the projects of your Jira; when you pick one, its workflow statuses become the team’s columns for the next step.
2. Check the Team name. kanman suggests one from the project, for example “Sandbox Team”.
3. If your tracker is Jira, choose the Code host: GitHub or GitLab (gitlab.com or your own GitLab server). With GitHub or GitLab issues, the code host is the tracker’s.
4. Add one or more repositories: pick them from the list of repositories your connection can reach, or type owner/name (on GitLab group/project, subgroups included) and press Enter. If your code host is not connected yet, a link takes you to Workspace settings > Connections.
5. Set the Base branch kanman opens pull requests against. The default is main.

Repositories you leave out are off limits. kanman checks this before every run and again on the final diff. You can add more repositories and branches later in the team settings under Repositories and tracker.

Step 3: Columns

kanman uses six column roles. The setup reads your tracker’s status names and suggests a role for each (click Use suggested roles), which you confirm or change:

Exactly one status must be Ready, and at least one status each must be In progress, Review and Done. Several statuses can share the other roles. Boards with German status names are covered in Connect Jira and GitLab.

Step 4: Policy

Pick the preset the team starts with. Each card shows how many runs may work at the same time:

Whatever preset you pick, a new team starts with a run budget of 2.00 EUR, plan approval always (you approve every plan before code is written) and a human merge. Every preset except Autonomous denies infra/**, **/*.tf and .github/workflows/**; Autonomous denies only .github/workflows/**.

Every setting is described in Policy settings. Choosing between presets is covered in Choose and tune a preset.

Step 5: Executor

Choose the coding agent that writes the code: Claude Code or Codex. Then choose how compute is paid. The choice starts with what your workspace set under New teams use in Workspace settings > Model access:

• Pay through kanman: usage is billed at cost plus 15 percent. No key needed.
• Use your own key: runs use a model provider key of your workspace. Pick it under Key, or add one with Manage keys (Workspace settings > Model access). Claude Code works with Anthropic and Amazon Bedrock keys, Codex with OpenAI and Azure OpenAI keys.

The reviewer that checks the result runs on a different model vendor than the executor, so the same model never grades its own work. The fallback executor and the model per story size are set later in the team settings under Agent and models.

Step 6: Look (optional)

Pick a wallpaper from Unsplash and an icon. They show on the team page and on every run of the team, which helps when you run several teams. You can skip this step. See Personalize your team.

Step 7: Dry run

Click Run dry run. kanman reads up to three open issues that it would pick up (in the Ready status with the pickup label) and shows how it would size and refine them: a size, a readiness score and notes such as “Write Given/When/Then acceptance criteria” or “Add a Demonstrate step”. Nothing is changed in your tracker or repositories.

Acceptance manifest check

The dry run also checks each picked repository for .kanman/acceptance.json, the file that tells kanman how to start your app and run acceptance specs. For every repository you see one of three results:

• Manifest found and valid, with the test framework it names.
• Manifest found, but it is not valid, with the first problems to fix.
• No acceptance manifest yet.

If the manifest is missing, click Open a pull request. kanman opens a pull request from the branch kanman/acceptance-manifest that adds a starter manifest for the repository’s stack and a short note in the README (or in .kanman/README.md when the repository has no README). The stack is read from the scripts and dependencies in package.json (Playwright, Vitest, Jest), from pytest in Python projects and from whether the repository has a Docker Compose file. If such a pull request is already open, kanman links to it instead of opening a second one. The start command and the ready_url are educated guesses when nothing in the repository names them: check the values the pull request lists, then merge it. Add an acceptance manifest explains every field.

The check uses your GitHub or GitLab connection (Workspace settings > Connections). You can repeat it at any time in the team’s Settings > Repositories and tracker with Check acceptance manifests; there, owners and admins can open the pull request.

Use the dry run to judge whether your issues are written in a way kanman can finish. If the readiness scores are low, read Write requirements kanman can finish before you start.

Create the team

Click Create team. The new team’s board opens beside your conversation with kanman, for example app.kanman.ai/acme/teams/billing, with the team’s status and preset in its header. With a tracker, kanman reads the project right away, so its stories arrive on the board within seconds.

At the top of your conversation, the pinned Setup card shows how far the team is: workspace, connection and team are done; first story, first run, first decision, evidence and the merged pull request follow. Its next step always has a button that takes you there (Describe it puts you in the message box to describe work, Pick a story highlights the Ready column, Review the plan opens the run with its decision). A team without repositories (kanman board with Claude Code) shows Claude Code connected instead of the first run and Done instead of merged. The Setup card is stored for the team, so everyone in the workspace sees the same progress in every browser; Hide removes it for everyone.

The last step of the setup lists Where you change this later: each choice of the setup and the team settings page it lives on.

Next: Your first story.

Change the setup later

Everything from the setup lives in the team settings (Settings tab in the team header, /teams/<team>/settings/<section>): twelve pages in four groups in the list on the left. Every change saves at once, with a Saved tick and Undo.

The team is paused and resumed with the pause button next to its status line in the team header, not in the settings. Old links to pages that were merged still work and open the new page.

Only workspace admins can change the settings; members see them read-only. Every change is recorded in the audit log.