This topic discusses the mappings between TeamForge and Gerrit, Gerrit access rights, directory structure, connectivity, logs and configuration properties, and differences compared to vanilla Gerrit.

Git Integration Blog Posts

You can read the CollabNet blog posts on Git integration and follow the latest developments in the CollabNet TeamForge-Git integration space.

Here’s a list of few useful blog posts:

Mappings Between TeamForge and Gerrit

These tables shows how objects and relationships are mapped between TeamForge and Gerrit.

TeamForge Object Gerrit Object
TeamForge project Project
SCM repository in TeamForge project (containing project roles with SCM permissions) Project
Project Role Group
User Group Group
User User
Site-wide role (TeamForge 8.0 and later) Group
TeamForge Relationship Gerrit Relationship
Git repository is part of a TeamForge project. Gerrit project corresponding to the Git repository inherits from the Gerrit project corresponding to the TeamForge project (TeamForge-Projects/<TeamForge project id>).
TeamForge project <child> has a parent TeamForge project <parent>. Gerrit project <child> inherits from the Gerrit project <parent>.
TeamForge project top is a top-level project. Gerrit project <top> inherits from Gerrit project. TeamForge-Projects which in turn inherits from All-Projects.
User has a TeamForge Project Role. User is part of the Group which corresponds to the TeamForge Project Role.
User is part of a User Group that is assigned a Project Role. User is part of a Group (which corresponds to a TeamForge Project Role).
User is part of a User Group. User is part of a Group (which corresponds to a TeamForge User Group.
Project Role is assigned an SCM permission (such as Admin, Delete and View, View and Commit, View Only, None). Corresponding group is assigned Gerrit access rights matching the assigned TeamForge SCM permissions. Those access rights are determined by the code review policy of the corresponding TeamForge repository.
Site-wide role is assigned an SCM permission. (TeamForge 8.0 and later only). Corresponding Gerrit groups are assigned Gerrit access rights matching the assigned TeamForge SCM permissions. Those access rights are determined by the code review policy of the TeamForge repository and hence may vary between repositories.
Guests, All Site Users, All Logged in Users, All Non-Restricted Users or Project Members have SCM permissions associated using TeamForge’s Default Access Permissions (TeamForge 8.0 and later only). Corresponding Gerrit groups are assigned Gerrit access rights matching the assigned TeamForge SCM permissions. Those access rights are determined by the code review policy of the TeamForge repository and hence may vary between repositories.
User is a site admin in TeamForge. User is part of Gerrit groups.
TeamForge: Site Admins.
TeamForge: Site-wide Project Admin Access.
Private Project - Site-wide Admin Access.
Public Project - Site-wide Admin Access.
Gated Project - Site-wide Admin Access.
Site admins have OWN and READ permissions for all Gerrit projects and the rights granted by the SCM Admin permission (depends on the code review policy of the Git repository in question).
User is a project admin in TeamForge. User is part of Gerrit group.
TeamForge: Project Admin for <TF project id>, which has OWN and READ permissions for all Git repositories of the corresponding TeamForge project.
User is non restricted in TeamForge (TeamForge 8.0 and later only). User belongs to Gerrit group.
TeamForge: Non-restricted Users.
User is a member of a TeamForge project (TeamForge 8.0 and later only). User belongs to Gerrit group.
TeamForge: Direct Project Member of <TF project id>.
User is member of a user group associated to a TeamForge project role (TeamForge 8.0 and later only). User belongs to Gerrit group.
TeamForge: Project Member of <TF project id>.
User has a site-wide role that has SCM permissions or a site-wide project admin permissions (TeamForge 8.0 and later only). User is part of Gerrit group.
TeamForge : Site-wide Role: <name of TeamForge Site-wide role>
and
- depending on the prevent inheritance to private projects flag, SCM permissions and project admin permissions -
TeamForge - Site-wide Project Admin Access
Public Project - Site-wide Admin Access
Gated Project - Site-wide Admin Access
Private Project - Site-wide Admin Access
Public Project - Site-wide Delete Access
Gated Project - Site-wide Delete Access
Private Project - Site-wide Delete Access
Public Project - Site-wide Commit Access
Gated Project - Site-wide Commit Access
Private Project - Site-wide Commit Access
Public Project - Site-wide View Access
Gated Project - Site-wide View Access
Private Project - Site-wide View Access
User has a TeamForge account. User belongs to the Gerrit group.
Registered Users.
User is not logged into TeamForge yet. User belongs to the Gerrit group.
Anonymous Users.
(as all logged in users do too).

Access Rights in Gerrit 2.13.x

The Git integration maps Gerrit access rights to TeamForge Role Based Access Control (RBAC) permissions.

With the current version of the integration, gerritforge.mappings (including custom changes you might have done) is automatically migrated to an XML file located at /opt/collabnet/gerrit/etc/TeamForgeGerritMappings.xml. The following table shows how TeamForge RBAC permissions are now mapped to Gerrit access rights by default.

Code Review Policy TeamForge Permission Cluster Gerrit Access Right
Default SCM None -
SCM View Only Read
SCM Commit/View Read
Push
Create Reference
Push Annotated Tag (refs/tags/*)
Push Signed Tag (refs/tags/*)
SCM Delete/View Read
Push (forcePush)
Create Reference
Forge Author Identity
Forge Committer Identity
Push Annotated Tag (refs/tags/*)
Push Signed Tag (refs/tags/*)
SCM Admin Read
Push (forcePush)
Create Reference
Forge Author Identity
Forge Committer Identity
Forge Server Identity
Owner
Abandon
Push Annotated Tag (refs/tags/*)
Push Signed Tag (refs/tags/*)
Optional Review SCM None -
SCM View Only Read
View Drafts
Publish Drafts
Code Review -1,1
Push (refs/for/refs/*)
Rebase(refs/for/refs/*)
SCM Commit/View Read
View Drafts
Publish Drafts
Code Review -2,2
Verify -1,1
Submit
Push
Create Reference
Rebase (refs/for/refs/*)
Push Annotated Tag(refs/tags/*)
Push Signed Tag (refs/tags/*)
SCM Delete/View Read
View Drafts
Publish Drafts
Code Review -2,2
Verify -1,1
Submit
Push (forcePush)
Create Reference
Rebase (refs/for/refs/*)
Create References
Push Signed Tag (refs/tags/*)
Push Annotated Tag (refs/tags/*)
Push Merges(refs/for/refs/*)
Forge Author Identity
Forge Committer Identity
SCM Admin Read
View Drafts
Publish Drafts
Delete Drafts
Code Review -2,2
Verify -1,1
Submit
Push (forcePush)
Create Reference
Owner
Abandon
Rebase (refs/for/refs/*)
Create References
Push Signed Tag (refs/tags/*)
Push Annotated Tag (refs/tags/*)
Push Merges(refs/for/refs/*)
Forge Author Identity
Forge Committer Identity
Forge Server Identity
Mandatory Review SCM None -
SCM View Only Read
View Drafts
Publish Drafts
Code Review -2,2
Push (refs/for/refs/*)
Rebase (refs/for/refs/*)
SCM Commit/View Read
View Drafts
Publish Drafts
Code Review -2,2
Verify -1,1
Submit
Push(refs/for/refs/*)
Rebase (refs/for/refs/*)
SCM Delete/View Read
View Drafts
Publish Drafts
Code Review -2,2
Verify -1,1
Submit
Push(refs/for/refs/*)
Rebase (refs/for/refs/*)
SCM Admin Read
View Drafts
Publish Drafts
Delete Drafts
Code Review -2,2
Verify -1,1
Submit
Push (forcePush)
Create Reference
Owner
Abandon
Rebase (refs/for/refs/*)
Push Annotated Tag(refs/tags/*)
Push Signed Tag (refs/tags/*)
Create References
Push Merges(refs/for/refs/*)
Forge Author Identity
Forge Committer Identity
Forge Server Identity

To make changes to the mappings, modify the /opt/collabnet/gerrit/etc/TeamForgeGerritMappings.xml file on the server where your Git integration is hosted. Make sure that the resulting XML structure complies with this schema: https://forge.collab.net/gerrit/static/TeamForgeGerritMappings-8.0.0.xsd.

Gerrit Configuration Options

Gerrit provides many configuration options. In addition, CollabNet Gerrit plugins also have configuration options.

For more information on Gerrit’s configuration options, see Gerrit Code Review - Configuration. In addition, see Gerrit Performance Cheat Sheet to know more about tuning Gerrit for optimal performance.

CollabNet Gerrit plugins have these configuration options:

Section.teamforge

Options Description
teamforge.cache-path

Location where Gerrit and CollabNet Gerrit plugin store caches. By default, this is at /opt/collabnet/gerrit/cache. We advise that it not be changed.

teamforge.cache-ttl Time-to-live for Gerrit caches in seconds. The default value is 300.
teamforge.apiPort Port over which TeamForge communicates with the Git integration. The default value is 9081.
teamforge.refreshTimeOut Interval in seconds after which the Git integration synchronizes with TeamForge. The default value is 3600.
teamforge.jumboPushThreshold The number of commits in one Git push beyond which the Git integration creates only a single commit object in TeamForge. The default value is 30.
teamforge.externalSystemId ID of the TeamForge external integration system. The value of this property is set by the post-installation script when the Git integration is first installed.
teamforge.url Host URL of the TeamForge site with which Git is integrated. The value of this property is set by the post-installation script when the Git integration is first installed.
teamforge.allowPushIfTeamForgeConnectionIsDown

TeamForge commit objects are validated prior to creation. When the value of this property is false and connection to TeamForge is down, validation fails. When the value of this property is true, validation and creation of commit objects are postponed until the connection to TeamForge is restored. The default value is false.

teamforge.parallelRemoteCallLimit TeamForge is able to handle a certain number of parallel connections. This parameter was introduced in order to avoid TeamForge "is out of service" issues. The default value is 9.
teamforge.maxRemoteCallRetry This parameter was introduced in order to specify the number of retry attempts for calls to TeamForge before connection failure is returned. The default value is 3.
teamforge.credentialsCache

When the value of this property is set to true, users’ credentials are cached for the teamforge.credentialsCacheTimeOut amount of time and used to authorize actions in case of TeamForge connection outage. The default value is true.

teamforge.credentialsCacheTimeOut Interval (in Seconds) after which the credentials cache expires. The default value is 3600.
teamforge.reconnectInterval When the "TeamForge connection is down" state is detected, and the number of seconds exceeds the value of this parameter, attempts to restore connection are performed periodically. The default value is 30.
teamforge.repositoryroot

Location where all Git repositories are stored physically. The default value is set to the value of the Gerrit configuration property gerrit.basePath, which is set to /gitroot by default.

teamforge.maxFilesListedInTFCommitObject Restricts the number of entries in the SCM files list view for a particular TeamForge commit object. This is especially useful for repository initial commit objects as they could contain a thousand entries that get processed by TeamForge. The default value is 250.
teamforge.notificationMaxSize

Number of bytes in notification message that will be sent out by git-multimail–part of the notification plugin. If message is larger than specified limit, it will be truncated. The default value is 25000.

teamforge.notificationMaxPythonExecutors

Number of Python processes used to create git-multimail notification. Each process will create one notification at a time. The default value is 2.

teamforge.syncTeamForgeProjectHierarchy

Turns the Project Hierarchy feature on. New Gerrit installs will have this value set to true, existing ones to false.

teamforge.supportSiteWideRoles

Enables TeamForgesite-wide role support. New Gerrit installs will have this value set to true, existing ones to false. This feature requires at least TeamForge 8.0 (will be ignored before).

teamforge.supportDefaultAccessPermissions

Enables TeamForge Default Access Permission support. New Gerrit installs will have this value set to true, existing ones to false. This feature requires at least TeamForge 8.0 (will be ignored before).

teamforge.commitProcessingTimeOut Maximum time allocated to process each Git commit to create a TeamForge commit object. If processing takes longer, processing of this commit is canceled, no corresponding TeamForge commit object will be created and the next commit will be processed. The default time is 15 min.
teamforge.createTFProjectLinkedApps If enabled creates Project linked application with target to Gerrit Dashboard for that TeamForge project given project contains at least one Git repository. This feature requires at least TeamForge 8.0 (will be ignored before). The default value is true.
teamforge.teamForgeMenuHeader Specifies the name of the menu that contains the links back to TeamForge user's Workspace and repositories list for a given TeamForge project. The default value is TeamForge.
teamforge.ensureStreamEventsForRegisteredUsers

If set to true, the RegisteredUsers group will have the StreamEvents global capability assigned during Gerrit startup. The default value is true.

teamforge.ensureAdminRightsForSiteAdmins

If set to true, the TF: Site Admins group will have Administrate Server global capability assigned during Gerrit startup. The default value is true.

Replication Configuration

This feature requires TeamForge 8.1 or later. These options are ignored if you have TeamForge 8.0 or earlier.

Options Description
teamforge.replicationMode Sets the server mode (replication master or slave) of the Git integration server. This property is set by the TeamForge installer depending on the value specified in the site-options.conf file's GERRIT_REPLICATION_MODE token. Therefore, this property should not be edited manually within the gerrit.config file. The default value set by the TeamForge installer is master.

Relication Master Configuration

Options Description
plugin.teamforge-replication.replicationDelay The delay (in seconds) between a push to the source repository and the actual replication attempt to the replica server. If further push activities happen between this delay, those will be bundled into the same replication attempt, avoiding bursts of replication attempts in case of repository mass updates. The default value is 15s and should not be set below 3s.
plugin.teamforge-replication.threads The number of threads that are used to push changes for each replica server. The default value is 4.
plugin.teamforge-replication.replicationRetry The maximum wait time before the next replication attempt is performed (upon previous connection failure). It is increased progressively (after each failure per mirror) starting with 1m to the power of 2 and up to the parameter value. For example, if the value is 5m, replication will be reattempted (considering that connection failure still occurs) after 1m then after 2m then after 4m and then after 5m and further attempts will be performed at 5m intervals. The default is 5m.
plugin.teamforge-replication.sshConnectionTimeout The timeout duration for establishing SSH connections during a replication attempt or when an SSH command is performed. This prevents the SSH queue from being blocked while waiting to connect to a mirror that is not responding. The default value is 15s.
plugin.teamforge-replication.sshCommandTimeout The timeout duration for replication SSH command execution (for example, project creation, HEAD change, and so on), after which the command fails. This prevents the SSH queue from being blocked while waiting to connect to a mirror that is not responding. The default is 30s.
plugin.teamforge-replication.pushTimeout The timeout duration for a replication push (push time after SSH connection is established), after which the push fails. This prevents the SSH queue from being blocked while waiting to connect to a mirror that is not responding. The default is 30s.

Replication Mirror Configuration

Options Description
plugin.teamforge-slave.replicaId The replica ID of the replication slave created in TeamForge if GERRIT_REPLICATION_MODE is set as slave. This property is set automatically by Gerrit upon start up and hence should not be edited manually.
plugin.teamforge-slave.allowGroup The group or groups that are allowed to push directly to the replication mirror. By default, only Administrator groups can do this.

Log Files

From TeamForge 18.1, Gerrit’s internal log rotation and compression feature is disabled as it is handled automatically by the TeamForge runtime environment.

Appendix