# Test a Gerrit sign-in code

[Read this guide on KeySigner](https://keysigner.io/integrations/guides/test-a-gerrit-sign-in-code/)

Check that a Keycloak-backed Gerrit test site accepts a code from KeySigner and opens the intended Gerrit reviewer account.

## Before you start

**KeySigner on iPhone or Mac and a browser**

- Use a Gerrit test site with its OAuth provider configured for Keycloak, a reviewer with test repository access, and a separately available administrator.
- [Check the Gerrit version](https://keysigner.io/integrations/setup-requirements/#check-versions-gerrit)

## Data and access

- **Shared or checked**. Keycloak checks the code. Gerrit uses the resulting identity to open the intended reviewer account.
- **Check separately**. Project visibility and permission to vote or submit changes come from Gerrit’s access rules.

## 1. Confirm the Gerrit site and test account

Use a test Gerrit site with the OAuth provider plugin configured for Keycloak. Confirm which realm and client the site uses. Use a test reviewer with access to an existing test repository and keep an independent administrator available. Ask the realm administrator to require Configure OTP for the reviewer if enrollment has not been set up.

**Check.** You have the expected Gerrit instance, test repository, Keycloak realm and recovery contact.

## 2. Add the reviewer’s code to KeySigner

In Gerrit, choose Sign In and check that you are redirected to the expected Keycloak realm. Sign in as the test reviewer. When Keycloak shows the setup QR code, open Accounts in KeySigner, choose Add (+), then Sign-in codes and backup. Unlock Sign-in codes, choose Add account, and scan the QR code.

**Check.** The KeySigner entry names the Keycloak reviewer account.

## 3. Confirm enrollment and note the Gerrit account

Select Show code in KeySigner and complete the required approvals. Enter the displayed code in Keycloak and label the authenticator. After returning to Gerrit, check the account under Settings and open the test repository. If your team uses the account API, record the numeric account ID from /accounts/self/detail.

**Check.** Keycloak accepts the enrollment code and returns to the expected Gerrit account.

## 4. Retest sign-in and the same repository

Wait for the code to change. Open Gerrit in a private browser, choose Sign In, and use the same reviewer. In the disposable test account, try an invalid code and confirm Keycloak keeps you at the prompt. Enter the fresh KeySigner code, then confirm the same Gerrit account and repository open. Check that the separate administrator can still sign in.

![Keycloak rejects an invalid authenticator code during a Gerrit test. The code field is empty.](https://keysigner.io/integrations/guides/test-a-gerrit-sign-in-code/gerrit-reviewer-code-rejected.png)

In the local Gerrit test, Keycloak rejected an invalid code and stayed at the prompt.

**Check.** An invalid code keeps the reviewer at the challenge. A fresh code returns to the same reviewer and the repository is visible.

## Check your result

The code is checked by Keycloak. Record the Gerrit account and which repository opened after that check. Review label permissions, submit requirements and automation credentials separately.

### What we tested

**Tested on November 18, 2026.** On local Gerrit 3.13.11 with the OAuth provider plugin at 5c230cddba and Keycloak 26.8.2, Keycloak accepted a KeySigner code during enrollment, rejected an invalid code in a new browser session, and accepted a fresh one. The same reviewer account and test repository opened. The separate administrator retained access.

[How to verify your setup](https://keysigner.io/integrations/verify-a-setup/)

## If you get stuck

### Gerrit opens a new account or the expected review is missing

Compare the site URL, Keycloak realm and Gerrit account ID with your original test. Ask the Gerrit administrator to check the account link and project permissions before changing any review rules. If a new code is rejected while the account and realm match, check your device clock and the realm’s OTP settings.

## Tools in this guide

- [Gerrit](https://keysigner.io/integrations/gerrit/)
  - [Review repository access and submit permissions](https://gerrit-review.googlesource.com/Documentation/access-control.html)
  - [Setup requirements](https://keysigner.io/integrations/setup-requirements/#gerrit)

## Setup instructions

- [Configure the Keycloak provider in the Gerrit OAuth plugin](https://gerrit.googlesource.com/plugins/oauth/+/5c230cddba/src/main/resources/Documentation/config.md#keycloak)
- [Check Gerrit authentication settings](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#auth.type)
- [Read the Gerrit account details endpoint](https://gerrit-review.googlesource.com/Documentation/rest-api-accounts.html#details)
- [Set up a Keycloak one-time code](https://keysigner.io/integrations/guides/set-up-a-keycloak-one-time-code/)
- [Replace a Keycloak code and check sessions](https://keysigner.io/integrations/guides/replace-a-keycloak-one-time-code/)
- [Check votes and submit requirements in Gerrit](https://keysigner.io/integrations/guides/check-code-merge-approvals/#compare-approval-rules)

[More guides for this task](https://keysigner.io/integrations/tasks/set-up-sign-in-codes/)
