Connections

Kairoku reads a forge; it never writes to one. Two are supported and they sit beside each other rather than one behind the other: a workspace can hold a GitHub connection and a GitLab connection at the same time, and a project can carry repositories from both.

This page is the web app's Settings → Connections (the section was called Integrations in the v1.1 release — /settings/connections redirected there then; 1.2 renames the sidebar label back to Connections to cover the Hub below, and /settings/integrations keeps working as the underlying route). It covers two kinds of connection:

In an organization context these connections belong to the organization, not to you — see Organizations.

Connections Hub

Each row on this page sits in one of two groups — Enabled (already connected) or Available (not yet) — searchable by name. A hub row's status word is a round-tripped fact: active only ever comes from a successful connect or tool refresh, needs reauth from a refused call, error from one that failed outright.

GitHub, GitLab and Atlassian are the same connections as the integrations below — connecting one there is enough; there is no separate Hub step for them. Everything else gets its own row: open it, and either Connect (OAuth — each authorization server gets its own callback) or paste an API key, depending on the connector; Custom MCP additionally asks for the server's URL.

What a connected run gets

Every tool a connected service advertises is added to the MCP endpoint next to Kairoku's own, named <connector>__<tool> — for example linear__create_issue or context7__get-library-docs — so a model never has to guess which server a call belongs to. A dispatched run's injected kairoku entry and any MCP session both see every one of the owner's active connections this way: connect once in this workspace, and every machine and every run gets the tools, with no second sign-in. See MCP for the naming rule and how scopes apply to them.

GitHub's connection also reaches git itself, without an agent ever signing in: a dispatched run's push access comes from the daemon's own credential helper, never a token the agent session can see, and it is gone the moment the run ends.

Refresh and revoke

Refreshing an expiring access token is centralized and single-flighted: however many calls land near-expiry together, the API refreshes upstream once, not once per call. Refresh tools in a connection's drill-in re-reads its tool list on demand — useful right after the upstream adds one.

Disconnect deletes the stored credential and asks the provider to revoke it. Nothing already running is interrupted mid-call, but the next call any run makes through that connection comes back as a tool error naming the connection and asking a person to reconnect it here — never a bare failure a model has to interpret. A connection a refresh itself can't get past is flagged needs reauth on its own row rather than silently dropped.

Connect a forge

Each forge row opens to a single Connect with GitHub or Connect with GitLab button. It sends you to the forge to authorize Kairoku's OAuth app and brings you back to this page with a notice saying the connection was saved. There is no token field to paste into any more. If the deployment has no OAuth app configured for a forge, the button is disabled and says so.

Once connected, the row shows Verified as @username after a successful check, and offers two actions: Test connection, which re-checks the stored credential and prints the result with the time it was checked, and Remove, which deletes the saved connection after a confirmation. A stored credential is never rendered back.

Two things about those scopes are worth knowing:

• GitHub's repo scope is write-capable. A classic GitHub OAuth app has no read-only scope for private repositories, so the token GitHub issues could write. Kairoku's own calls only read with it — see What the app reads.
• GitLab is gitlab.com only. The OAuth app lives on gitlab.com, so there is no instance URL to enter and no self-managed GitLab path in this release.

A personal access token saved before the switch to OAuth still shows as connected and keeps working; there is simply no form to paste a new one.

Point a project at its repositories

A project's Settings → Connections card lists what the project is linked to — the Primary repository first, then any others. + Add repository opens a short guided form.

• Each connected forge gets a searchable picker over the repositories that account can see. You pick; you do not type a path.
• With no forge connected the form says so and links to Settings › Integrations.
• When more than one repository is picked, choose which one is Primary repository. The panels and chat read the primary; the others are listed under Additional repositories, can carry an optional label, and stay switchable on Overview.
• Saving a change that unlinks a repository asks you to confirm first. Nothing is deleted on the forge.
• If a forge is disconnected later, the project's stored repositories on it stay visible and removable here.

Repo chips and the Overview panel carry the forge's own glyph and the forge's own words: pull requests on GitHub, merge requests on GitLab. The board's tile reads Open PRs, Open MRs, or Open PRs & MRs depending on what is actually linked.

What the app reads

That is the whole list. There is no write path to either forge: Kairoku opens no pull request, pushes no branch, leaves no comment and registers no webhook.

Merge detection reads GitHub only. When the Floor reconciles merges, the app looks up the pull request for each finished run's branch on the project's primary GitHub repository (up to five runs per pass) and records the run as merged when GitHub says so — that is what turns the plan item done. A project whose primary repository is on GitLab is not reconciled; mark its items done in the app.

The board's open-PR tile folds across every repository on the page, keyed by (provider, path) rather than by project — so two projects pointed at the same repository count once.

Slack and the wake relay

The Slack row on this page has two parts.

Connect with Slack authorizes Kairoku's Slack app and ends on a notice — Slack authorised — saying your linked daemon collects it within a minute. The web app does not store the Slack token: the API holds it in a single-use handoff for 10 minutes, and your running, linked daemon collects it into its own vault. If no daemon collects it in time, connect again. See Slack.

The wake relay status. The relay is a small cloud service that queues Slack events for 72 hours while your desktop daemon is offline. The row reports its status and never involves a Slack token:

To check, the Kairoku API mints a short-lived operator ticket scoped to install id owner:<your owner id> (your user or organization) and asks the relay for pending counts; the ticket never reaches the page. Refresh status checks again. See Slack for how the relay itself works.

Related

• MCP — how a connected service's tools are named and scoped on the shared endpoint
• Operator and Plugin — agents that call those tools once you've connected