Linear Integration Setup

This guide walks you through connecting Linear to Codity so that linked Linear issues — and their PRDs — are pulled into your code reviews, and so Codity can check a pull request against the issue's requirements and report progress back to Linear.

Overview

The Linear integration lets Codity:

  • Detect Linear issue IDs (e.g. ENG-123) in pull request titles and descriptions
  • Fetch the issue's title, description, status, and its PRD (the linked

    project's description/content and attached Linear documents)

  • Inject that business context into the review so the reviewer can judge the change

    against intended behavior, not just generic code quality

  • Post a requirements checklist on the PR showing which acceptance criteria are

    implemented

  • Write progress back to the Linear issue — a comment with the PR link and

    completed criteria struck through, and a move to In Progress

Prerequisites

  • A Linear workspace and a user who can create a personal API key
  • The team key(s) whose issues you want recognized (the prefix in issue IDs,

    e.g. ENG for ENG-123)

  • A Codity account with at least one connected provider (GitHub, GitLab, Azure

    DevOps, or Bitbucket)

Setup Steps

Step 1: Create a Linear API key

  1. Open Linear API settings
    • Go to <https://linear.app/settings/api>
    • Or in Linear: Settings → Security & access → Personal API keys
  2. Create the key
    • Click "Create key"
    • Enter a label: Codity Integration (or any descriptive name)
    • Click "Create"
    • IMPORTANT: copy the key immediately — Linear shows it only once. Store it

      securely.

> Tip: for org-wide use, create the key from a service / bot account rather than a personal account, so the write-back comments aren't attributed to an individual and the integration keeps working if that person leaves.

Step 2: Configure Linear in the Codity dashboard

  1. Open settings
    • Log in to your Codity dashboard
    • Go to Settings → Integrations → Linear
  2. Enter your configuration
    • API Key: paste the personal API key from Step 1
    • Team Keys: enter comma-separated team prefixes, e.g. ENG,OPS
      • These scope which IDs are treated as Linear issues. Because Linear IDs look

        identical to Jira keys (ENG-123), setting team keys prevents the two from

        cross-firing.

      • Leave empty to match any TEAM-123-style ID (only recommended if you don't

        also use Jira).

  3. Test connection
    • Click "Test" to verify the key. A success message confirms Codity can reach

      Linear with your key.

  4. Save
    • Click "Save". The API key is encrypted at rest (Fernet) before storage.

> Set it up once for your whole team. Linear settings are resolved org-wide: if one member configures the key while the dashboard is switched to the organization context, every member's PRs in that org use it automatically — no need for each developer to re-enter the key. Make sure the org switcher shows your organization (not your personal account) when you save. See Organization-wide setup.

Step 3: Reference Linear issues in your pull requests

Codity detects issue IDs from the PR title and description. Supported forms:

  • ENG-123 — standard
  • [ENG-123] — bracketed
  • (ENG-123) — parenthesized
  • ENG-123, ENG-124 — multiple issues (up to five per PR)

Matching is case-insensitive (eng-123 works) and, when team keys are configured, only those prefixes are recognized.

Example PR titles

  • ENG-42: rate-limit the checkout endpoint
  • [ENG-128] add idempotency keys to payments
  • Fix flaky logout (ENG-77, ENG-78)

> Where the ID must appear. Only the PR title and description are scanned — > branch names and commit messages are not. Putting ENG-123 in a commit or > branch is good hygiene (and GitHub often pre-fills the PR body from your first > commit), but make sure the ID actually ends up in the PR title or description, or > Codity won't link the issue.

Step 4: See it in action

Open a PR that references a Linear issue with the integration configured. During the review Codity will:

  1. Pull the issue + PRD into the review context (business-intent lens)
  2. Post a requirements checklist comment on the PR
  3. Post a progress comment on the Linear issue and move it to In Progress

What Codity posts

On the pull request — a requirements checklist

Codity posts a single comment listing the issue's requirements and whether each is implemented in the diff. It is state-aware:

## Linear requirements — 1/3 implemented

Status of the linked Linear requirements in this PR:

**[ENG-42](https://linear.app/acme/issue/ENG-42)**
- [x] Health checks are not rate-limited
- [ ] Rate limit is per user (keyed by user_id)
- [ ] 429 responses include a Retry-After header

Please implement the remaining requirements before merging.

The header reflects the case: none implemented yet, N/M implemented, or all implemented. If automatic completion checking is unavailable for a run, Codity still posts the tracked requirements (without the checked/unchecked state).

On the Linear issue — a progress comment + status move

Codity writes back to each linked issue:

**Codity review — PR progress**

PR: https://github.com/acme/checkout/pull/12
Status: in progress — 1/3 requirements implemented

Completed:
- ~~Health checks are not rate-limited~~

Remaining:
- Rate limit is per user (keyed by user_id)
- 429 responses include a Retry-After header

It also transitions the issue to an In Progress state — but only from a not-yet-started state, so a Done or cancelled issue is never moved backwards.

How it works

Issue detection and fetching

  • IDs are matched from the PR title/description, then each issue is fetched by an

    exact lookup (team key + number). An ID that doesn't resolve to a real issue is

    simply skipped — Codity never substitutes a different issue.

  • For each issue Codity also fetches the PRD: the linked Linear project's

    description/content and any attached Linear documents.

Requirements

  • Acceptance criteria are taken from the issue description and PRD. Codity reads

    bullet, checkbox, and numbered list items as individual requirements.

  • If an issue has no list items, Codity falls back to meaningful prose lines, so a

    plainly written issue still yields trackable requirements. For the cleanest results,

    write acceptance criteria as a bulleted list.

Completion check

Whether each requirement is implemented is determined from the diff on a best-effort basis. If that check can't run, the write-back still happens (without strike-through), so the PR link and tracked requirements always reach the issue.

Organization-wide setup

Linear credentials are stored on the configuring user's settings but resolved org-wide: any member of the same organization who opens a PR will use the org's configured key automatically.

For this to work:

  1. The person configuring must save while the dashboard org is set to the

    organization (not their personal account).

  2. Teammates viewing the Integrations page should also be in that organization's

    context — the panel then shows the integration as configured (key masked) along

    with the shared team keys.

Personal repositories (not owned by an organization) are inherently per-user and are not shared.

Best practices

  1. Configure team keys so Linear IDs don't collide with Jira keys.
  2. Write acceptance criteria as a bulleted list in the issue (or its PRD) for the

    most accurate checklist.

  3. Put the issue ID in the PR title for visibility and reliable detection.
  4. Use a service-account API key for org-wide setups so write-back authorship is

    neutral.

  5. Keep the key secret — never commit it; rotate periodically.

Security

  • The Linear API key is encrypted with Fernet before it is stored.
  • All communication with Linear uses HTTPS.
  • Only authorized users can view or update integration settings; the key itself is

    never returned to the browser (the UI shows only a masked placeholder).

Troubleshooting

  • No Linear context / no checklist appears — confirm the issue ID is in the PR

    title or description (not just the branch/commit), and that its team prefix is in

    your configured Team Keys.

  • "0 requirements" / checklist not posted — the issue has no parseable acceptance

    criteria. Add them as a bulleted list in the issue description or PRD.

  • A teammate can't see the integration in settings — make sure both the person who

    configured it and the teammate are viewing the dashboard in the organization

    context, and that it was saved under the org (not a personal account).

  • A finding cites the wrong issue ID — the reviewer quotes IDs it sees **in the

    code/diff** (TODOs, docstrings). Keep ticket references in code consistent with the

    PR's linked issue.

Next Steps