feat(custom-headers): add SENTRY_CUSTOM_HEADERS for self-hosted proxy auth

[BYK]

Summary

Adds support for injecting custom HTTP headers into all requests to self-hosted Sentry instances behind reverse proxies (e.g., Google IAP, Cloudflare Access).

• SENTRY_CUSTOM_HEADERS env var — for CI/scripting overrides
• sentry cli defaults headers — for persistent local configuration

Format: semicolon-separated Name: Value pairs (newlines also accepted as separators).

Self-hosted only

Custom headers are only applied when targeting a self-hosted instance (SENTRY_HOST/SENTRY_URL is set to a non-*.sentry.io URL). When configured on SaaS, headers are ignored with a one-time warning.

Injection points

Headers are injected at all three request paths to the Sentry server:

1. Authenticated API requests — prepareHeaders() in sentry-client.ts
2. OAuth device flow — fetchWithConnectionError() in oauth.ts (fixes the login error from the issue)
3. Shared issue resolution — getSharedIssue() in api/issues.ts

Resolution priority

SENTRY_CUSTOM_HEADERS env var > defaults.headers in SQLite > none

Reserved headers

Authorization, Host, Content-Type, Content-Length, User-Agent, sentry-trace, baggage — these are managed by the CLI and cannot be overridden.

Usage

# Set via defaults (persistent)
sentry cli defaults headers "X-IAP-Token: abc123"

# Or via env var (CI/scripting)
SENTRY_CUSTOM_HEADERS="X-IAP-Token: abc123; X-Forwarded-For: 10.0.0.1"

# View current headers
sentry cli defaults headers

# Clear
sentry cli defaults headers --clear

Closes #759

[github-actions]

Semver Impact of This PR

🟡 Minor (new features)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

New Features ✨

• (custom-headers) Add SENTRY_CUSTOM_HEADERS for self-hosted proxy auth by BYK in #761

• (init) Pre-supply existingSentry to eliminate roundtrip by betegon in #755

Bug Fixes 🐛

• (arg-parsing) Normalize spaces in slugs and trim whitespace in issue IDs (CLI-14M, CLI-16M) by BYK in #757
• (search) Rewrite OR queries to in-list syntax across all --query commands (CLI-16J) by BYK in #758
• (upgrade) Retry spawn on EBUSY for Windows Defender file locking (CLI-16E) by BYK in #756

Internal Changes 🔧

• (time-range) Parse --period at flag level via parsePeriod by BYK in #760
• Regenerate docs by github-actions[bot] in 34bf056d

---

_{🤖 This preview updates automatically when you update the PR.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8daba02. Configure here.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-761/
Built to branch gh-pages at 2026-04-15 22:38 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Codecov Results 📊

✅ 134 passed | Total: 134 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric	Change
Total Tests	—
Passed Tests	—
Failed Tests	—
Skipped Tests	—

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 96.10%. Project has 1639 uncovered lines.
✅ Project coverage is 95.45%. Comparing base (base) to head (head).

Files with missing lines (2)

File	Patch %	Lines
src/lib/oauth.ts	54.55%	⚠️ 5 Missing
src/lib/db/defaults.ts	92.31%	⚠️ 1 Missing

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.45%    95.45%        —%
==========================================
  Files          236       237        +1
  Lines        35923     36049      +126
  Branches         0         0         —
==========================================
+ Hits         34290     34410      +120
- Misses        1633      1639        +6
- Partials         0         0         —

---

Generated by Codecov Action