Gerrit PR Integration
=====================

CodeScene's Pull Request integration supports Gerrit for on-prem CodeScene installations.
Once configured, CodeScene automatically reviews changes posted to Gerrit and reports the
results back, the same way it does for the other supported Git hosting platforms.

For an overview of how the PR integration works, the available quality profiles, and
configuration as code, see :doc:`/guides/pr-integration/integrate-into-ci-cd`.

Configuration
-------------

The Gerrit PR integration is configured per project. You will need the following details
from your Gerrit installation:

* **Gerrit API URL** — Specify the Gerrit API URL. If left blank, a default API URL is
  constructed from the repository paths.
* **Gerrit Host URL** — The external webhooks will call CodeScene using this Host URL.
  If left blank, the global Host URL is used.
* **Gerrit Username** — The Gerrit user account CodeScene will authenticate as.
* **Gerrit HTTP Password** — The HTTP password (token) generated for the Gerrit user.
* **Gerrit Origin URL** *(optional)* — The Gerrit Origin URL to use for fetching changes,
  if different from the configured repository origin URL.

The user account used for the integration needs sufficient permissions to read changes
and to post review messages on the projects you want to analyze.

Required Permissions
~~~~~~~~~~~~~~~~~~~~

CodeScene manages webhooks on Gerrit on your behalf, so the user account used for the
integration must have permission to read and modify webhooks. In Gerrit, webhook
configuration lives under the special ``refs/meta/config`` reference, so the user's group
needs both ``Read`` (to fetch existing webhooks) and ``Push`` (to add, update, and delete
webhooks) on that reference:

.. code-block:: text

    Reference: refs/meta/config
    Permission: Read   # fetch/get webhook
    Permission: Push   # add/update/delete webhook
    Group: <user's group>

In addition, to post review comments the user must have ``Read`` permission on
``refs/heads/*`` for the projects being analyzed:

.. code-block:: text

    Reference: refs/heads/*
    Permission: Read
    Group: <user's group>

.. note::

    If **Manage your own webhook** option is selected under **Advanced Settings**, the integration user
    does not need the webhook-related permissions; only the ``Read`` permission on ``refs/heads/*`` is required.
