fix(confluence): retry transient attachment metadata 500s and skip a failing parent instead of aborting the sync

[waleedlatif1]

Summary

• Atlassian intermittently answers attachment metadata GETs with a bare 500, which the shared retry set never retries, so a single 500 aborted the whole Confluence sync and put the connector into failure backoff
• Retry 500s on attachment metadata reads through the existing fetcher + retryCondition hooks (same pattern as Coda / Google Workspace), scoped to the Confluence connector; shared isRetryableError is unchanged
• A parent whose attachment listing still 5xx's after retries is skipped and recorded as a listing failure, same path as the existing 403/404/scope handling, so deletion reconciliation is held and the parent is retried next sync
• Three consecutive server failures still fail the sync, so a real Atlassian outage fails fast instead of spending the retry budget on every remaining parent
• Log Atlassian's atl-traceid / x-arequestid response headers for every 5xx attempt so failures can be traced with Atlassian support; the error body is never read or logged, so a stalled body cannot consume the retry budget
• 5xx metadata errors now carry their status (provider_unavailable), so sync diagnostics classify them instead of reporting none; the error message is unchanged
• Docs: the Atlassian service-account page (the setup guide the connector modal links for non-Search knowledge bases) now lists the connector's full service-account scope set from confluenceConnectorMeta.serviceAccountScopes, including read:attachment:confluence, and how to replace a token that is missing scopes

Type of Change

• Bug fix

Testing

• New cases in connectors/confluence/attachments.test.ts: transient 500 retried (including one whose body never finishes), isolated persistent failures skipped with deletions held, consecutive 500/503 fail the sync, trace ids logged but never the body
• Each case goes red on the pre-fix code or with its guard reverted individually (retry, skip, outage cap, streak reset, header sanitization, body leak)
• connectors/confluence/ + lib/knowledge/connectors/ suites, bun run type-check, bun run lint, bun run check:audits, docs-manifest:check

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing (new tests pass the test-audit authoring gate)
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
docs	Skipped		Sep 30, 2026 2:09am UTC

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Confluence attachment sync error handling and retry logic.

The PR appears safe to merge; no outstanding findings or new actionable issues were identified.

Summary

The PR retries transient Confluence attachment-metadata 500s, records persistent per-parent listing failures without reconciling deletions, and stops after consecutive server failures. It also adds regression tests and documents the connector’s service-account scopes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Read parent attachment metadata] --> B{Response}
  B -->|500| C[Cancel body and retry]
  C -->|Recovers| D[Process attachments]
  C -->|Retries exhausted| E[Record failed parent; hold deletions]
  B -->|Other persistent 5xx| E
  E --> F{Three consecutive server failures?}
  F -->|No| A
  F -->|Yes| G[Fail sync]

Loading

_{Reviews (4) · Last reviewed commit: "fix(confluence): keep the 500 status whe..."}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[waleedlatif1]

@greptile

[waleedlatif1]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@waleedlatif1 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}