New forge: Gerrit Code Review

[QuentinBtd]

📝 Provide a description of the new feature

Summary

Following the multi-forge support policy, I'd like to propose adding Gerrit Code Review (minimum supported server version: 3.12) as a new supported forge, and volunteer as its designated maintainer.

Gerrit is already listed as "💭 Considering" in the Supported forges table. I use Gerrit daily and have a working ForgeAdapter implementation I'd like to contribute.

Proposed maintainer

@QuentinBtd

Why Gerrit

Gerrit Code Review is a widely used self-hosted code review tool (Android, Chromium, Eclipse, LibreOffice, OpenStack, Wikimedia, and many companies run it internally). It has no built-in "notifications" concept comparable to GitHub/Gitea, which is presumably why it's been sitting in "Considering" — this proposal includes a concrete mapping of Gerrit's own primitives onto Gitify's notification model.

Design summary

• Notification source: Gerrit's Attention Set (GET /a/changes/?q=attention:self) — the only Gerrit mechanism with genuine per-user, per-change server-side "needs your action" state, and the closest analogue to an unread notification. It's also the mechanism Gerrit's own dashboard ("Your turn") is built on.
• Mark as read: removes the account from the change's attention set (POST /changes/{id}/attention/self/delete) — a real server call, not a client-side flag.
• Mark as done / unsubscribe / issues: not supported — Gerrit has no distinct "done" state beyond attention-set removal, no per-thread unsubscribe, and no built-in issue tracker. These capabilities are gated off so the UI hides them rather than no-op silently.
• Auth: HTTP Basic (username + HTTP password / authentication token) against the /a/-prefixed API, which also sidesteps XSRF requirements for writes — same auth shape as the existing Bitbucket adapter.
• Subject type reuse: Gerrit changes map onto the existing PullRequest subject type and OPEN/MERGED/CLOSED/DRAFT state vocabulary (same precedent as Gitea's Pull → PullRequest mapping), so the shared type/state filters and icon dispatch work with zero changes to shared code outside the adapter.
• Version floor: hard-gated at 3.12 (checked against GET /config/server/version); older servers are not blocked if the version can't be determined, to avoid false-positive lockouts. 3.12 is not a technical requirement — Gerrit's Attention Set has existed since 3.3 (2020) — it's the oldest version Gerrit itself still actively supports. Per Gerrit's own support policy, "the community actively supports the last 3 releases"; as of writing that's 3.12, 3.13, and 3.14, with 3.11 and earlier already end-of-life. Picking the oldest non-EOL release seemed like the right balance between inclusiveness and not asking users to run something the Gerrit project itself no longer maintains. Happy to revisit this threshold as Gerrit's support window moves forward.

Compliance with the multi-forge policy

• Adapter-based: implemented entirely behind ForgeAdapter in src/renderer/utils/forges/gerrit/ (types, client, transform, adapter + tests).
• Designated maintainer: proposing myself, @QuentinBtd, for triage/review/CI of this adapter.
• Capability-honest UI: mark-as-done, unsubscribe, and "my issues" are all gated off — the corresponding UI hides rather than no-ops.
• No core-platform churn: no Octokit dependency; uses plain fetch like Gitea/Bitbucket. Existing Octicons/Primer usage untouched (a small custom brand SVG icon is added for Gerrit, following the same pattern as the existing BitbucketIcon).

Proposed capability matrix

Notifications	Mark read	Mark done	Unsubscribe	Enriched details
✅	✅	—	—	—

Known, disclosed limitation

Because "mark as read" is implemented as a real attention-set removal (rather than a synthesized local flag), a change you've already reviewed — and are therefore no longer in the attention set for — will not resurface in Gitify if someone else later merges or abandons it, even though Gerrit still emails you about it (Gerrit's email notifications follow participation/watch settings, not attention-set membership; see the "Rules" section of Gerrit's own docs). This is a deliberate trade-off to keep every notification's "mark as read" action a real, honest server call rather than inventing client-side read state — happy to discuss alternatives if maintainers feel differently.

Current status

• Adapter implemented behind ForgeAdapter (src/renderer/utils/forges/gerrit/)
• Registered in registry.ts
• Unit tests for client/transform/adapter/login route; pnpm check and pnpm test green
• Validated against a real, self-hosted Gerrit 3.13.6 instance (auth, listing, mark-as-read)
• MAINTAINERS.md / CODEOWNERS entry (pending green light on this proposal)
• Open the PR

Happy to open the PR for review as soon as maintainers are open to this addition, and to adjust the design based on feedback.

➕ Additional Information

No response

[afonsojramos]

Thanks @QuentinBtd. The Attention Set indeed seems to be the right primitive to build on.

From my side this is a yes, feel free to open the PR (include the MAINTAINERS.md entry in it). A few discussion points, none blocking:

1. Mark-as-read has team-visible side effects. Removing yourself from the attention set isn't private the way GitHub's "mark as read" is: the uploader and reviewers can see you've left the attention set, and Gerrit's own nudge mechanics react to it. I think the honest-server-call approach is still right (and Gerrit auto-re-adds you on new patchsets or replies, so legitimate resurfacing works), but it's worth a sentence in the docs and/or the account setup screen so nobody is surprised that clearing a notification is a visible workflow action. Or maybe not? Because that is already an expected behaviour for Gerrit users?

2. Version floor: consider soft-warn instead of hard gate. Since 3.12 is a support-policy choice rather than a technical requirement (Attention Set has been there since 3.3), and you already let unknown-version servers through, a hard block on a detected 3.11 feels inconsistent: the one case you can detect is treated more harshly than the one you can't. Either warn-but-allow on known-old versions, or gate everything consistently. Mild preference for warn-but-allow, but your call as adapter maintainer.

3. The merged/abandoned limitation is acceptable as disclosed. It matches Gerrit's own semantics (submits and abandons clear the attention set rather than setting it), so Gitify staying consistent with Gerrit's model beats inventing client-side read state.

4. Enrichment can be a cheap follow-up. The changes query already returns rich data with o= options (labels, submit state, WIP), so a later "detailed notifications" pass may be mostly transform work.

One request for the PR: include the validation evidence from your 3.13.6 instance (redacted request/response samples are fine). I have no Gerrit instance to test against, so the initial review will lean on that plus unit tests. Probably not worth having dockerized smoke tests.