docs: simplify public documentation for scanning (#2139)
This commit is contained in:
Carlos Florêncio
@@ -7,6 +7,13 @@ description: "Connect Azure DevOps, GitHub, GitLab, Jira, Linear, Sentry, and Sl
|
||||
|
||||
Integrations let Kandev's backend read and update provider data. They power repository and issue browsers, task associations, watches, pull-request review, and provider-specific task launchers.
|
||||
|
||||
## Quick path
|
||||
|
||||
1. Open the integration for the workspace that owns the work.
|
||||
2. Connect the narrowest provider credential that supports the task.
|
||||
3. Test the connection before browsing or enabling watches.
|
||||
4. Keep provider API credentials, task Git credentials, and agent credentials separate.
|
||||
|
||||
They do **not** provide every credential a task needs. Keep these paths distinct:
|
||||
|
||||
- an integration credential lets the Kandev backend call a provider API;
|
||||
@@ -45,6 +52,9 @@ Health results are cached and periodically refreshed (normally about every 90 se
|
||||
|
||||
## GitHub
|
||||
|
||||
<details>
|
||||
<summary>GitHub details</summary>
|
||||
|
||||
Use GitHub for pull requests, issues, reviews, checks, repository discovery, task associations, and provider-triggered work. Browse it at `/github` after connecting an account.
|
||||
|
||||
### Authenticate
|
||||
@@ -257,8 +267,13 @@ For recovery:
|
||||
registration, rotate the credentials in GitHub, and add the App again. Kandev does not rotate App
|
||||
private keys, OAuth client secrets, or webhook secrets automatically.
|
||||
|
||||
</details>
|
||||
|
||||
### Configure and use the workspace
|
||||
|
||||
<details>
|
||||
<summary>Workspace GitHub details</summary>
|
||||
|
||||
Workspace GitHub settings control repository scope, default/saved searches, quick-action prompts, pull-request analytics, review watches, and issue watches. At `/github`, search or browse pull requests and issues, save queries, apply prompt presets, and launch a Kandev task. A saved query can default to one repository; choose **All repos** for no repository default, and change the repository filter without rewriting the saved query. An associated pull request also appears in task review surfaces for feedback, checks, reviews, and merge actions.
|
||||
|
||||
A **Review Watch** polls a GitHub search and creates review work. It requires a workflow, starting step, prompt, and workspace. The default query is `type:pr state:open review-requested:@me -is:draft`; add repository filters or replace the query as needed. An optional agent or executor profile overrides the selected step's defaults. The poll interval defaults to 300 seconds and accepts 60–3,600 seconds. The prompt field accepts `@name` references to saved prompts, resolved the same way as in a workflow step; see [Saved prompt references in step prompts](workflow-tips.md#saved-prompt-references-in-step-prompts).
|
||||
@@ -288,8 +303,13 @@ observed event without prescribing an action; the task workflow and agent
|
||||
context determine the response. Destination workflow steps and GitLab lifecycle
|
||||
parity are follow-up work.
|
||||
|
||||
</details>
|
||||
|
||||
## GitLab
|
||||
|
||||
<details>
|
||||
<summary>GitLab details</summary>
|
||||
|
||||
GitLab supports workspace-scoped connections, issue and merge-request browsing, task launch and durable MR links, automation watches, linked-MR review actions, and merge-request creation. GitHub and GitLab can be connected at the same time; each provider uses its own credentials and records.
|
||||
|
||||
### Connect a workspace
|
||||
@@ -342,8 +362,13 @@ For a task repository whose `origin` matches the workspace's GitLab host, the Ch
|
||||
|
||||
A successful create returns the MR URL and asynchronously records it against the originating task repository. If association fails, use the manual link action. Retrying is idempotent for an existing open MR with the same source and target branches. A push can succeed even when MR creation fails; Kandev reports that partial result and leaves the remote branch in place for retry.
|
||||
|
||||
</details>
|
||||
|
||||
## Azure DevOps
|
||||
|
||||
<details>
|
||||
<summary>Azure DevOps details</summary>
|
||||
|
||||
Azure DevOps configuration is workspace-specific. The current integration supports Azure DevOps Services organizations at `https://dev.azure.com/<organization>`. A trailing slash is accepted and removed when Kandev saves the canonical URL. Azure DevOps Server/TFS and alternate organization URL forms are not supported.
|
||||
|
||||
Enter the organization URL on the Azure DevOps settings page, then hover, focus, or tap the info icon beside **Personal Access Token**. Follow its **Create personal access token** link. In Azure DevOps, select **New Token**, choose the organization and an expiration, and select **Custom defined** scopes. Under **Work Items**, check **Read**; under **Code**, check **Read**; leave every other scope unchecked. Create the token, copy it while Azure DevOps still displays it, and paste it into Kandev.
|
||||
@@ -358,8 +383,13 @@ The **Remote** picker in **New Task** searches configured GitHub, GitLab, and Az
|
||||
|
||||
This release has no Entra OAuth flow, webhook, or watch poller.
|
||||
|
||||
</details>
|
||||
|
||||
## Jira
|
||||
|
||||
<details>
|
||||
<summary>Jira details</summary>
|
||||
|
||||
Jira configuration is workspace-specific. Use `/jira` to search with JQL, save views, open issue details, run supported transitions, and launch tasks with Jira prompt presets. Launch copies Jira URL/content into the task title and description; it does not store a durable Jira issue association on the task.
|
||||
|
||||
Enter the site URL (a missing scheme is normalized to HTTPS), choose **Cloud** or **Server/Data Center**, and optionally set a default project key. Authentication options are:
|
||||
@@ -382,8 +412,13 @@ The maximum in-flight value defaults to 5. Leave it blank for no cap. A cap defe
|
||||
|
||||
Deleting a Jira watch leaves its previously created tasks in place. **Reset** is destructive: after the preview, it permanently deletes every watch-created task, including archived tasks, clears cursor/deduplication state, and makes current matches eligible for the next poll.
|
||||
|
||||
</details>
|
||||
|
||||
## Linear
|
||||
|
||||
<details>
|
||||
<summary>Linear details</summary>
|
||||
|
||||
Linear configuration is workspace-specific. Enter a personal API key and optionally a default team. Kandev calls the fixed Linear GraphQL endpoint at `https://api.linear.app/graphql` and sends the key as its authorization value. Leaving the credential blank during an edit keeps the stored key.
|
||||
|
||||
After saving and testing the connection, use `/linear` to search by text, team, or assignee, view issue details, change supported states, and launch tasks. Linear launch uses fixed title/description construction, has no prompt-preset editor, and does not store a durable Linear issue association.
|
||||
@@ -394,8 +429,13 @@ Leaving the repository blank creates repo-less tasks. When a repository is selec
|
||||
|
||||
Linear polling is also bounded. **Default (Linear order)** reads one page of 50; an explicit dispatch sort reads at most five pages of 50 before sorting locally. Matches outside that window can remain unseen, and reset does not bypass the bound.
|
||||
|
||||
</details>
|
||||
|
||||
## Sentry
|
||||
|
||||
<details>
|
||||
<summary>Sentry details</summary>
|
||||
|
||||
Sentry configuration is workspace-specific and supports multiple named instances. This is useful when one Kandev workspace spans different Sentry organizations or self-hosted installations.
|
||||
|
||||
Create an instance with a unique name, base URL, and bearer authentication token. The default URL is `https://sentry.io`; replace it for self-hosted Sentry. A URL with no scheme becomes HTTPS. It must be a bare HTTP(S) host root—paths, queries, and fragments are rejected. The UI lists `org:read`, `project:read`, and `event:read` as the required read scopes.
|
||||
@@ -410,8 +450,15 @@ Each Sentry poll reads only the newest first page (up to 100 issues) and does no
|
||||
|
||||
An instance cannot be deleted while a watch references it. Because the instance binding is immutable, delete those watches first and recreate them against another instance if needed. Sentry issues appear in task issue-selection/current-task surfaces; there is no top-level `/sentry` browser comparable to GitHub, GitLab, Jira, or Linear.
|
||||
|
||||
</details>
|
||||
|
||||
## Slack
|
||||
|
||||
> **Security:** Slack matching text is untrusted input, and the external MCP endpoint exposes destructive task/configuration tools. Use a constrained utility agent and model; review the [external MCP security boundary](automation-and-mcp.md#external-mcp-security-boundary).
|
||||
|
||||
<details>
|
||||
<summary>Slack details</summary>
|
||||
|
||||
Slack support currently uses a browser-session polling connection. It is intended for a controlled personal workspace and is more fragile than OAuth or a bot installation. Kandev does not currently offer a Slack OAuth/bot install flow.
|
||||
|
||||
Configure, per workspace:
|
||||
@@ -436,8 +483,13 @@ Slack has no separate prompt editor. It uses the chosen Utility Agent's prompt f
|
||||
|
||||
Slack does not trigger on reactions, expose a slash command/shortcut, mirror task status, or provide a live chat bridge to a running coding agent. It searches matching messages rather than performing a one-time history import, which is why the first scan can process existing matches. Browser session credentials can expire without notice; reconnect when polling starts returning authentication failures. Turning off the browser-local **Enabled** switch does not stop the backend poller—remove the saved Slack configuration to stop it.
|
||||
|
||||
</details>
|
||||
|
||||
## Copy configuration between workspaces
|
||||
|
||||
<details>
|
||||
<summary>Copy configuration details</summary>
|
||||
|
||||
Supported integration pages offer **Copy configuration** with provider-specific behavior:
|
||||
|
||||
- GitHub copies repository scope, saved/default searches, and quick-action presets. It does not copy authentication or watches.
|
||||
@@ -447,6 +499,8 @@ Supported integration pages offer **Copy configuration** with provider-specific
|
||||
|
||||
Workspace automations are never copied by this action. Review the target workspace's repository and workflow scope before enabling any copied connection.
|
||||
|
||||
</details>
|
||||
|
||||
## Security and troubleshooting
|
||||
|
||||
Issue bodies, pull-request comments, commit messages, Slack threads, and incident details are untrusted prompt input. Use read-only credentials for triage, restrict repositories/projects/channels, and keep a human workflow gate before merge, release, deployment, or sensitive transitions.
|
||||
|
||||
Reference in New Issue
Block a user