Tuleap integrates with Gerrit, an advanced Git-based code review tool. This integration allows you to migrate Git repositories from Tuleap to Gerrit while maintaining automatic synchronization of branches and tags. Tuleap user groups are also replicated, simplifying permission management.
Info
This feature relies on LDAP authentication. Tuleap and Gerrit must share the same LDAP directory. The integration requires Gerrit 2.8 minimum (recommended version: 2.12.x).
Prerequisites
A Gerrit server must be installed, configured, and connected to your Tuleap instance by a platform administrator.
The LDAP plugin must be active on both Tuleap and Gerrit.
You must be a project administrator in Tuleap to migrate a repository.
Installation note
Installing and configuring the Gerrit server are system administration operations. Refer to the Setup section of the technical documentation for detailed instructions.
Information
A platform administrator can configure a Gerrit server as restricted, limiting its use to specific projects. If the Gerrit server does not appear in the migration options, contact your administrator.
Overview
The integration is designed to be as lightweight as possible: Tuleap simplifies the creation and management of repositories, users, and groups, but does not restrict any Gerrit functionality.
Key points:
Multiple Gerrit instances can be connected to the same Tuleap server.
A Gerrit instance can be connected to multiple Tuleap servers.
A Gerrit instance connected to Tuleap can also be used independently.
Migrate a repository to Gerrit
Procedure
Navigate to the settings of the Git repository you want to migrate.
In the "Gerrit" panel, select the destination Gerrit server.
Choose the desired permission scheme (see the Permissions section below).
Start the migration.
What happens after the migration
The migration is processed asynchronously. The migration status is displayed in the repository settings: pending, completed, or error.
Once completed:
The sources are replicated to the Gerrit server.
On the Tuleap side, the repository becomes read-only. Users can still browse the repository, clone it, or fork it, but all write operations are blocked.
Permanent changes (branches and tags) made on Gerrit are automatically replicated to Tuleap (with a delay of a few seconds).
Review-specific elements (patchsets, reviews, etc.) are not replicated. Only
refs/heads/*andrefs/tags/*are.All user groups from the Tuleap project are replicated to Gerrit.
Gerrit project structure
After migrating a firefox repository from the Tuleap project mozilla:
A parent Gerrit project
mozillais created (permissions only, no sources).A sub-project
mozilla/firefoxis created with the sources.
The parent project allows you to define permissions common to all repositories from the same Tuleap project.
Permissions
Three permission options are available during migration:
Default permissions
Gerrit permissions are generated from the permissions defined on the Git repository in Tuleap at the time of migration:
Tuleap permission | Gerrit rights (on branches) |
|---|---|
READ | Read, Code-Review -1..+1 |
WRITE | Read, Create, Code-Review -2..+2, Verified -1..+1, Submit, Push, Push Merge |
REWIND | Push +force |
Information
These permissions are applied only at the time of migration. Subsequent permission changes are made directly in Gerrit.
No permissions
If you are an advanced Gerrit user, you can start with an empty permission scheme. Select the "No predefined permissions" option in the permission configuration dropdown during migration.
From a template
You can apply a predefined permission template, defined in the Git plugin administration. Templates are Gerrit configuration files (refs/meta/config). The %projectname% variable is replaced with the project name during migration.
Permission inheritance (Umbrella Projects)
For complex organizations with many repositories, you can leverage Gerrit project inheritance.
By defining a parent project in the Tuleap project administration, all permissions from the parent Gerrit project automatically apply to sub-projects (migrated repositories).
Example: the parent project mozilla can define that any member of the organization has the right to propose a contribution on any repository, and that the QA team can give a -2.
User group management
User group synchronization is automatic. For a Tuleap project mozilla with a Developers group:
The created Gerrit groups are:
mozilla/project_membersmozilla/project_adminsmozilla/Developers
Any change to Tuleap project members is replicated to Gerrit:
Adding/removing members from a group.
Creating a new user group.
Group bindings.
Warning
Do not directly modify the members of replicated groups in Gerrit. Tuleap may overwrite these changes without notice. If you need a custom group, create a dedicated group directly in Gerrit.
SSH key management
To facilitate getting started with Gerrit, SSH keys stored in Tuleap are automatically synchronized to the corresponding Gerrit account.
Adding or removing an SSH key in Tuleap is propagated to Gerrit.
This synchronization does not remove keys managed only by Gerrit.
Information
The initial connection between the Tuleap account and the Gerrit account is not automatic. Each user must go to the Gerrit page in their user preferences (accessible via My Account > Gerrit) and click "Manually push SSH keys" to initiate the synchronization. From this page, you can also view the configured Gerrit servers and manage your keys for each server.
Disconnect or delete a Gerrit project
From the Git repository settings, "Gerrit" panel, a "Disconnect" button is available. Before confirming the disconnection, three options are offered:
Also Delete project on Gerrit : Permanently deletes the Gerrit project (sources, reviews, changesets). The Tuleap repository becomes writable again. After deletion, it is possible to re-migrate the repository.
Information
This option requires the
deleteprojectplugin to be installed on the Gerrit server. If this plugin is not available, this option does not appear.
Make project on Gerrit Read-Only : The Gerrit project is kept but set to read-only. Replication stops. The Tuleap repository becomes writable again. Useful for archiving.
Leave project on Gerrit : The Gerrit project is kept as-is but replication stops. The Tuleap repository becomes writable again. The two repositories evolve independently (risk of divergence).
Warning
After a simple disconnection ("Leave" or "Read-Only"), you cannot re-migrate the repository. You must first delete the Gerrit project.