Skip to content

feat(forge): add Gerrit support - #3705

Draft
QuentinBtd wants to merge 2 commits into
gitify-app:mainfrom
QuentinBtd:feat/gerrit-forge-adapter
Draft

QuentinBtd wants to merge 2 commits into
gitify-app:mainfrom
QuentinBtd:feat/gerrit-forge-adapter

Conversation

@QuentinBtd

@QuentinBtd QuentinBtd commented Nov 17, 2026 •

Copy link
Copy Markdown

Summary

Adds Gerrit Code Review support through the existing ForgeAdapter interface.

Related to #3106.

  • Authenticate with a Gerrit username and HTTP password/authentication token.
  • Fetch notifications from attention:self, including pagination, and map changes to the existing pull-request display and filters.
  • Mark notifications as read by removing the current user from the change's attention set.
  • Provide Gerrit-specific account, changes, and notification links; hide unsupported issues, mark-as-done, and unsubscribe actions.
  • Register @QuentinBtd as the Gerrit maintainer in MAINTAINERS.md and CODEOWNERS, and update the supported-forge documentation.

Implementation

The adapter owns Gerrit API parsing, timestamp conversion, state/reason mapping, and version checks. Authenticated requests run through a dedicated Electron main-process handler using net.fetch, so packaged builds do not depend on a Gerrit server allowing the renderer's origin through CORS. The handler restricts requests to HTTPS /a/ paths and GET/POST methods, and rejects redirects.

Shared changes let the login form distinguish Gerrit usernames from Bitbucket email addresses, allow account-specific profile links and unsupported issue links, and classify numeric HTTP errors so expired Gerrit credentials expose the existing re-authentication action. No new dependencies are added.

Behavior and discussion points from #3106

  • Mark-as-read is a team-visible workflow action. Removing yourself from the attention set is visible to the uploader and reviewers; it is not a private local read flag.
  • Notification scope follows Gerrit's attention-set semantics. Merged or abandoned changes do not reappear merely because Gerrit sends an email. No synthetic unread state is introduced.
  • Gerrit 3.12 or later is recommended, not required. Following the recommendation in New forge: Gerrit Code Review #3106, known older versions produce a log warning but are allowed to sign in. Unknown or unparseable versions are also allowed. Compatibility with older servers is not guaranteed.
  • Detailed enrichment is left for a follow-up.

Validation

  • Format, lint, and type checks: vp check.
  • Full unit test suite with coverage: vp run test --maxWorkers=2 — 2,267 tests passed across 224 files. The initial default-parallelism run hit a timeout in a Settings test; the reduced-parallelism rerun passed.
  • Translation checks: vp run i18n:check.
  • Container-based login visual tests: scripts/visual.sh 'Login' — 21 passed.
  • Updated screenshot baselines for the forge selector, login screen, and account add menu.

Gerrit 3.13.6 evidence

The proposal in #3106 reports successful authentication, notification listing, and mark-as-read against a self-hosted Gerrit 3.13.6 instance. This is previously reported validation, not a new end-to-end test of the final main-process request path.

  • Attach the redacted request/response samples requested in the issue discussion.
  • Verify authentication, listing, and mark-as-read in the final packaged app against that instance.

Opening as a draft so these remaining validation items stay explicit.

Adds a Gerrit Code Review adapter (min. supported version 3.12, the
oldest release Gerrit itself still actively supports — "the community
actively supports the last 3 releases" per
https://www.gerritcodereview.com/support.html#supported-versions)
behind the existing ForgeAdapter interface.

- Notifications are sourced from the Attention Set (`q=attention:self`),
  the only Gerrit mechanism with genuine per-user, per-change server-side
  state. Mark-as-read removes the account from the attention set via the
  real REST endpoint rather than a client-side read flag. Known, accepted
  scope limitation: per Gerrit's own attention-set rules, reviewing a
  change removes you from its attention set, and a subsequent merge/abandon
  by anyone clears it for everyone — so a change you reviewed that someone
  else later merges will not resurface here, even though Gerrit still
  emails you about it (email notifications follow participation/watch
  settings, not attention-set membership). Documented in `gerrit/client.ts`;
  broadening this would require a synthesized, non-server-backed 'unread'
  state, which was deliberately avoided to keep mark-as-read a real,
  honest server call for every notification this adapter returns.
- The notification reason is 'author' when the caller owns the change
  (a reviewer is waiting on them) and 'review_requested' otherwise.
- Mark-as-done and per-thread unsubscribe are not supported (no Gerrit
  equivalent) and are gated off via capabilities, consistent with the
  Gitea/Bitbucket adapters.
- Auth is HTTP Basic (username + HTTP password/token) against the `/a/`
  prefixed API, which also bypasses XSRF requirements for writes.
- Gerrit REST calls run in the main process (`net.fetch`) through a new
  `GERRIT_REQUEST` IPC event: Gerrit servers rarely allow the app's
  origin via CORS, which packaged builds enforce. The handler only
  accepts https `/a/` API URLs, GET/POST and Basic credentials, and
  refuses redirects; the renderer still checks the host against the
  account.
- Gerrit API errors carry their HTTP `status`, and `determineFailureType`
  now reads a numeric `status` from any error (not only Octokit's), so
  an expired or revoked Gerrit token shows as BAD_CREDENTIALS and the
  Accounts screen offers re-authentication.
- Handles Gerrit's `)]}'` XSSI JSON response prefix and its
  non-ISO-8601 timestamp format.
- The login forge selector fits five tabs; a visual test checks every tab
  stays inside it at 500px and at 465px (the 500px window at 120% zoom).
  Login and add-account screenshot baselines are regenerated.
- Reuses 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
  no changes to shared code outside the adapter.
- Generalises the PAT login form's username field (label and HTML input
  type, previously hardcoded to Bitbucket's 'Atlassian Email') into
  `usernameLabel`/`usernameInputType` props, now also used by Gerrit's
  plain HTTP Basic username. Gerrit requires the username in
  `validatePersonalAccessTokenForm`, like Bitbucket.
- Quick links: Gerrit implements the existing `getPullRequestsUrl`
  (`/q/status:open+owner:<user>`) and `getNotificationsUrl`
  (`/q/attention:<user>`). `getIssuesUrl` may now return `undefined`;
  Gerrit does so, and the sidebar button, account-header button and
  "i" shortcut are hidden in that case.
- Adds an optional `getAccountProfileUrl` to `ForgeAccountOperations`,
  implemented by Gerrit only (`/q/owner:<user>`, same convention as
  notification-author links). `openAccountProfile` uses it when present
  and otherwise keeps the previous `https://<host>/<login>` behaviour.
- `removeSelfFromAttentionSet` (used by mark-as-read) passes Gerrit's
  `ChangeInfo.id` through as-is: its project segment is already
  URL-encoded (e.g. `modules%2Fcache-infinispan~593701`), and
  re-encoding it would produce `%252F` and 404 for nested projects.
  Regression test added with a nested-project id.

Registers @QuentinBtd as the Gerrit adapter maintainer in
MAINTAINERS.md/CODEOWNERS per the multi-forge contribution policy, and
updates README/CONTRIBUTING accordingly. Also adds the pre-existing but
missing Bitbucket row to MAINTAINERS.md's maintainer table (it already
had a CODEOWNERS entry but no table row).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added the enhancement New feature or enhancement to existing functionality label Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or enhancement to existing functionality

Development

Successfully merging this pull request may close these issues.

1 participant