TeamForge-Git Integration Reference

Git Integration Blog Posts

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

Here's a list of few useful blog posts:

• Bulletproof, Military Grade Security – Visualizing the Access Control Mechanisms of Your SCM Solution
• You shall not pass – Control your code quality gates with a wizard – Part I
• You shall not pass – Control your code quality gates with a wizard – Part II
• Migrating from Subversion to Git: What Your PCI-DSS Guy Will Not Tell You, Part I
• Migrating from Subversion to Git: What Your PCI-DSS Guy Will Not Tell You, Part II
• Seamlessly navigate between TeamForge projects and related Gerrit reviews
• TeamForge Git /Gerrit Integration with Jenkins CI
• CollabNet Gerrit Notifications – For all who miss the good ol’ git push notifications
• TeamForge Just Got Even Better with Git Pull Request Feature!
• Gerrit Rebranding – The missing Guide to a customized Look & Feel
• Easy guide to mappings between Gerrit Access Control and TeamForge Source Code Permissions

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

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

The mappings file TeamForgeGerritMappings.xml is located in the refs/meta/config branch of TF-Projects project.

How to view/access the TeamForgeGerritMappings.xml file?

1. Log on to TeamForge as a Site Administrator.

2. Select My Workspace > More > Git <hostname>.

   note

hostname refers to the server where your Git integration is hosted. :::

3. Select Projects > List.

   

4. Select TF-Projects from the list of projects.

   

5. Select the Branches tab.

   

6. Click Browse against the refs/meta/config branch name.

   

   The TeamForgeGerritMappings.xml file can be found here.

   

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
No Review	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 TeamForgeGerritMappings.xml file in the refs/meta/config branch of TF-Projects project on the server where your Git integration is hosted. For instance, if you want to add a user-defined category to your repository, first you need to add the user-defined category to the TeamForgeGerritMappings.xml file. For instructions, see [Create a User-defined Repository Category][codereviewpolicy.html#adduserdefinedrepocat].

note

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.

Replication 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

• History Protection FAQs
• History Protection Slide Deck
• Git reflog vs History Protection
• Gerrit Performance Cheat Sheet