feat(linear): re-fetch failed documents by id (Resolver)

Merged
EV
12h ago
+558-66

Description

LinearConnector now implements Resolver. A targeted reindex fetches the failed Linear issues again by id, without a full crawl.

Document types

  • The connector emits one document type: the issue. The document id is the issue UUID (issue.id). The issue identifier (for example ENG-123) is only in the title and the URL.
  • Issues are covered. Comments are part of the issue document, so they come back with it.
  • No types are left out. The crawl yields no hierarchy nodes, so reindex yields none.

How it works

  • reindex checks that each input id is a UUID. An id that is not a UUID yields a ConnectorFailure.
  • It queries the issues with the GraphQL issues filter id: { in: [...] }, in batches of batch_size. The filter also has the configured team and project scope.
  • An id that Linear does not return yields a ConnectorFailure. This covers a deleted issue, an issue outside the configured teams or projects, and an issue the token cannot read.
  • The crawl's document builder moved into _issue_to_document. The crawl and reindex both use it.
  • A failed query yields failures for the ids in that batch only. The other batches continue. LinearAuthError and ConnectorMissingCredentialError still stop the run, as in the crawl.
  • Entity failures (failed_document is None) are skipped, as in Confluence.

Permissions

  • With include_permissions=True, reindex sets external_access through the new EE function issue_access_by_id (ee/onyx/external_permissions/linear/connector.py).
  • That function uses the same parts as the doc sync: iterate_issue_access, SharedAccessIndex (with get_issue_share for ancestors outside the batch) and issue_access. It runs one access query per batch.
  • The CE connector reaches it through fetch_versioned_implementation_with_fallback, as the Box connector does. Without EE, external_access stays None.
  • An issue with no access result yields a failure, so it is not indexed without its permissions.

Tests and CI

  • New daily test backend/tests/daily/connectors/linear/test_linear_resolver.py. It reads one crawl page (5 issues) to get real ids.
  • New TestSecret.LINEAR_API_KEY = "linear-api-key".
  • The connector workflow runs all of backend/tests/daily/connectors and fetches secrets from AWS, so it needs no change.
  • The CI secret test/linear-api-key is in AWS Secrets Manager.

How Has This Been Tested?

uv run --env-file .vscode/.env pytest -xv backend/tests/daily/connectors/linear/test_linear_resolver.py: 9 passed, against a real workspace (8 teams, about 1,000 issues, with sub-issues).

The tests cover: one issue, several issues, a mixed batch (good, unknown UUID, not a UUID), an unknown UUID, an id that is not a UUID, an issue outside the team scope, empty input, entity-only input, and include_permissions=True (asserts external_access names the issue's team group).

Existing Linear unit tests (tests/unit/onyx/connectors/linear, tests/unit/ee/onyx/external_permissions/linear, test_perm_sync_valid.py): 106 passed after the rebase onto main.

Additional Options

  • [Optional] Please cherry-pick this PR to the latest release version.
  • [Optional] Override Linear Check

🤖 Generated with Claude Code

Summary by cubic

LinearConnector now implements Resolver, so a targeted reindex re-fetches failed documents by ID instead of running a full crawl.

  • reindex queries failed issue UUIDs in batches inside the configured teams and projects, reusing the crawl's _issue_to_document. Invalid, missing, out-of-scope, or unreadable IDs yield a ConnectorFailure; entity failures are skipped; a failed batch fails only its own IDs.
  • Linear now raises LinearAuthError for an AUTHENTICATION_ERROR returned in a 200 answer, so a targeted reindex stops instead of failing every batch.
  • With include_permissions, reindex sets external_access through the EE issue_access_by_id (CE falls back to none); an issue with no access result yields a failure.
  • Adds daily resolver tests against a real workspace plus unit tests covering failed batches, out-of-scope IDs, and refused credentials; CI needs the new test/linear-api-key secret.

Summary by CodeRabbit

  • New Features

    • Added targeted reindexing for individual or multiple Linear issues.
    • Reindexing preserves successful results in mixed batches and reapplies team and project filters.
    • Added optional restoration of direct and inherited Linear issue permissions.

  • Bug Fixes

    • Improved per-issue reporting for invalid, inaccessible, missing, out-of-scope, or failed issues.
    • Improved Linear authentication error handling during synchronization and reindexing.

  • Documentation

    • Clarified how targeted reindexing applies Linear issue access rules.