GitHub integration

Once GitHub is connected, Kolleague automatically links pull requests based on issue identifiers. Issue detail shows PR state, change size, CI results, and merge conflicts in place.

Kolleague only acts on repositories authorized at install time. It never pushes code on its own; an eligible agent task can receive a short-lived token for its assigned repository so it can check out code, push its task branch, and open a pull request.

Connect GitHub

A workspace owner or admin can complete the connection:

1. Open Settings → GitHub.
2. Turn on the GitHub integration master switch.
3. Click Connect GitHub.
4. In GitHub, pick the account or organization and authorize all repositories or a chosen subset.
5. Return to Kolleague after the installation completes.

The connection status shows on the same page. Regular members can view the status but can't connect, disconnect, or change the switches.

Let an agent inspect the connection

Agents can distinguish the GitHub App connection from their checkout context through the Kolleague CLI:

kolleague integration github status --output json
kolleague integration github repositories --output json
kolleague repo list --output json

The first command reports the connected GitHub account. The second queries the repositories authorized during GitHub installation, while the third reports the separate workspace repository registry available to agent tasks.

Authorized private repository names remain owner/admin-only. An agent whose human requester is a regular member can report that GitHub is connected, but cannot enumerate those names—even when the runtime owner is an admin. A repository returned by the GitHub integration command is not automatically registered for checkout; add it in Settings → Repositories when it should become durable agent context.

When an issue is assigned, its project repositories—or the workspace repository registry when the project has none—are delivered to the agent as task context. For a GitHub repository included in the assignment, checkout asks Kolleague for a one-hour GitHub App token scoped to that exact repository. Kolleague only issues it when the task was originated by a workspace owner or admin. Regular members cannot use a shared owner-backed agent to enumerate private repository names or obtain write access.

The token is used in memory for clone/fetch and is not stored in Git config. The checkout installs a credential helper that obtains another short-lived token when a later git push needs one. For GitHub CLI operations, agents use:

kolleague integration github gh <repository-url> -- pr create --title "..." --body "..."

Agents may create a branch, commit, push, and open a pull request for their assignment. They do not merge unless a user explicitly asks them to do so.

Feature switches

Settings → GitHub has four switches:

Link a PR to an issue

The simplest approach is to put the issue identifier in the branch name or PR title. For example, for issue KOL-123:

kol-123-fix-login-redirect

KOL-123 Fix the redirect after login

Kolleague ignores case and only matches the current workspace's issue prefix. One PR can link to multiple issues.

If the identifier appears only in the PR body, use one of GitHub's close intents:

Closes KOL-123
Fixes KOL-123
Resolves KOL-123

A reference-only mention in the body, such as Related to KOL-123, is not shown as a working PR for that issue. Commit messages and PR comments don't trigger linking either.

View PRs on an issue

Once linked, PRs appear in the Pull requests block of issue detail. Each entry shows:

• repository, number, title, and author;
• Open, Draft, Merged, or Closed state;
• added and deleted lines and the number of changed files;
• CI status: all passed (with a count), some failed (naming the failing checks), or some in progress; PRs with no checks configured don't show this item — "no checks" is never treated as passing;
• mergeability: mergeable (only when GitHub reports a clean merge state), conflicting, blocked, or behind.

CI status and mergeability come from snapshots Kolleague pulls from the GitHub API, and the two are independent; merged or closed PRs no longer show either. When GitHub is temporarily unavailable, the card keeps the last snapshot and marks it stale instead of going blank.

Click an entry to open the PR on GitHub. Turning off the PR sidebar only hides this block; it doesn't disconnect anything.

When a merged PR moves an issue to Done

A merged PR doesn't necessarily mean the issue is finished. Kolleague only moves an issue to Done when all of the following hold:

1. at least one merged linked PR used a close intent immediately followed by the identifier, such as Closes KOL-123 (forms with words in between, like Closes login KOL-123, don't count);
2. the issue has no other working PR still Open or Draft (reference-only mentions in the body don't count);
3. the issue is not currently done or cancelled.

So writing KOL-123 only in the branch name or title establishes the link but doesn't by itself trigger completion. A PR closed without merging doesn't complete the issue either.

The status change is written to the timeline as a system action, and members subscribed to the issue are notified.

Multiple workspaces

The same GitHub App installation can be connected to multiple Kolleague workspaces. GitHub events flow into each workspace separately and are matched against each workspace's own issue prefix.

For example, a PR that references both KOL-1 and ENG-2 can link in two workspaces with different prefixes. Workspaces never see each other's issues.

Disconnect

Clicking Disconnect in Settings → GitHub only removes the relationship between the current Kolleague workspace and the installation; it does not uninstall the App from GitHub for you. Existing PR records are kept, and new events stop flowing into that workspace.

To revoke repository authorization on the GitHub side, uninstall the App or adjust its repository scope from your personal or organization GitHub App installations page. After uninstalling, every Kolleague workspace linked to that installation stops receiving events.

Troubleshooting

• Connect button disabled: check that GITHUB_APP_SLUG and GITHUB_WEBHOOK_SECRET reached the API process.
• Webhook returns 401: confirm the GitHub App and the API use the same webhook secret, then redeliver from GitHub's Recent Deliveries.
• PR not linked: check that the repository is in the App's authorized scope, auto-linking is on, and the identifier belongs to the current workspace.
• Identifier in the body but not shown: switch to Closes KOL-123, or put the identifier in the branch name or PR title.
• No CI status: confirm GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are configured, and that the App has read-only Checks and Commit statuses permissions with the matching events subscribed. After adding permissions to an installed App, each installation's owner must also approve them on GitHub before they take effect.
• Agent sees the repository but checkout is unauthorized: confirm the repository is attached to the task's project or workspace registry, the assigning user is still an owner/admin, the App has Contents and Pull requests write permission, and the installation owner approved those permissions.
• Issue not completed after the PR merged: confirm the PR used a close intent, and check whether other linked PRs are still Open or Draft.

Next steps

• Issues — how status transitions relate to merge-to-Done.
• Project resources — which repositories agents use when running.