# Issue trackers: Jira, Linear and GitHub Issues

Bucker links an issue to a ticket in your tracker three ways, and keeps the two statuses in step.

| Way | Where |
| --- | --- |
| By hand | **Links** on the issue page: pick a connected tracker, press create. Pressing twice finds the same ticket. |
| From an alert | A notification channel of kind `jira`, `linear` or `github_issues`. An issue alert files (or finds) the issue's ticket; a metric alert files a standalone ticket. |
| By API | `POST /orgs/:org/projects/:project/issues/:id/links` with `{ "integrationId": "..." }`. |

Every create is idempotent: the link is claimed before the tracker is called, so a double click, an alert storm and a retried delivery produce one ticket.

## Linear

Connect under **Settings, Integrations, Linear**.

| Field | Meaning |
| --- | --- |
| `teamId` | The Linear team UUID. Tickets are created there. |
| `apiKey` | A personal API key, or an OAuth access token (`lin_oauth_...`). Stored encrypted; never shown again. |
| `stateIds` (API only) | Bucker status to Linear workflow-state id. Needed for Bucker-to-Linear sync; without an entry for a status nothing is pushed. |
| `stateMap` (API only) | Linear state name to Bucker status. By default `completed` and `canceled` states resolve the issue, and `started` and `unstarted` mark it ongoing. |

Inbound sync: create a Linear webhook (resource type **Issues**) pointing at the URL shown when you connect, and paste the signing secret shown with it. Bucker verifies `Linear-Signature` (HMAC-SHA256 of the raw body) and bounds replays with the signed `webhookTimestamp`.

## GitHub Issues

Connect under **Settings, Integrations, GitHub Issues**. It stores no credential. `repoConnectionId` names a GitHub repository you already connected; Bucker uses that connection's PAT or GitHub App installation, so revoking the connection revokes this too. The connection must belong to the same organization.

The GitHub App needs the **Issues: read and write** permission.

Closing a Bucker issue as resolved closes the GitHub issue (reason `completed`); any other status that needs work reopens it. For the other direction add a repository webhook for **Issues** events to the URL shown on connect, with the secret shown there (`X-Hub-Signature-256`). `closed` resolves the Bucker issue; `reopened` marks it regressed.

## What stays a human step

- **Linear connects with an API key, not one-click OAuth.** Paste a personal API key (or an OAuth access token you already hold) into the form above; that is the supported connection and it does create, link, the alert channel and two-way sync. One-click "Connect Linear" is not offered: Bucker has not built the OAuth connect flow and registers no Linear OAuth application until it does. The trade is that the key is tied to the Linear user who created it, so use a dedicated user if you can.
- **GitHub Issues through the Bucker GitHub App needs the Issues permission accepted on your installation.** Bucker's App requests Issues read and write. If your installation was made before the App asked for it, GitHub shows a pending permission request under your account's or organization's installed GitHub Apps settings; until you accept it, creating, closing and reopening issues fails with "Resource not accessible by integration". A connection made with a personal access token needs a token that can write issues.
- Accepting a Linear "delegate to Bucker" as a remediation trigger is not built; it would go through the same autonomy gate as other triggers.