Integrations¶

An integration connects Kapelle to a chat or work-tracking service: Mattermost, Slack, GitHub, Linear or Jira. Each is a record with settings, secrets and an enabled flag; the surface gateway reads the records and turns messages, issues and webhooks into work for teams.

Kind	What it is	Required settings	Required secrets
`mattermost`	Chat rooms, threads and the slash command	`url`	`bot_token` (and `command_token` for the slash command)
`slack`	Channels and threads	none	`bot_token`, `app_token`
`github`	Issues, pull requests and repository access, through one GitHub App	`app_id`, `installation_id`	`app_key`, `webhook_secret`
`linear`	The Linear agent app	none	`access_token`, `webhook_secret`
`jira`	The Jira agent	`client_id`, `cloud_id`, `account_id`	`client_secret` (and `webhook_secret`)

Connecting one¶

Register the app at the service: GitHub App, Slack app, Linear app, Jira app. Mattermost needs a bot account and a token.
Enter each secret once with PUT /secrets/integrations/<kind>/<setting> (or in the Console). A secret is never returned.
PUT /integrations/{kind} with {enabled, settings} and If-Match. Enabling with a required setting or secret missing is a 422 that names what is missing.
POST /integrations/{kind}/test checks the credentials: state is ok, error or unknown, with a one-line detail.
GET /integrations/{kind} shows status.applied. pending means the gateway reads the change when it restarts; a person restarts it, an agent cannot.

GET /integrations/{kind}/deliveries lists recent webhook deliveries for diagnosing a service that does not seem to reach Kapelle. The webhook URLs to give the service are derived from KAPELLE_PUBLIC_BASE_URL.

Linking teams¶

A team is linked to a repository, a Linear team or a Jira project with PUT /teams/{name}/links ({surface, external_id}); work arriving there becomes a task for the team's lead. A GitHub link is refused with 422 when the GitHub App is not installed on the repository. A team's home room is separate from its links: every step of its work is posted to the home room, while another linked surface receives only its own work items.

Mattermost role bots¶

On Mattermost each role can post as its own bot account (coder, reviewer, ...); a role without a bot is posted by the single surface bot with the role named in the text. The mapping is GET /integrations/mattermost/role-bots, and just mattermost-role-bots creates the accounts.

Console as a surface¶

A team with no chat home (home: none) works from the Console: tasks, questions and answers are the run's posts, see runs.

Depth: architecture, Surfaces.