teamforge git integration - gerrit 2.8.x (for teamforge 7...

TeamForge Git integration - Gerrit2.8.x (for TeamForge 7.1/7.2)

| Contents | 2

Contents

TeamForge Git integration...................................................................................... 4

Set up the TeamForge Git integration................................................................... 6Install the TeamForge Git integration..................................................................................................................6Migrate to version 8.2.x from an earlier version of the TeamForge Git integration........................................... 6Upgrade version 8.2.x of the TeamForge Git integration to the latest release.................................................... 7

Add Gerrit as a linked application.........................................................................9

Set up Code Search for the TeamForge Git integration.....................................10

Control the code review policy for Git repositories............................................ 12Mandatory code reviews for Git repositories.....................................................................................................12Optional code review for Git repositories..........................................................................................................13Default code review for Git repositories............................................................................................................14Custom code review for Git repositories........................................................................................................... 15

Update Git repository access rights in Gerrit..................................................... 17

TeamForge Git integration: History protection.................................................. 18TeamForge Git integration: Enable history protection...................................................................................... 18History protection reports...................................................................................................................................19TeamForge Git integration: History protection FAQ........................................................................................ 21GERRIT_FORCE_HISTORY_PROTECTION................................................................................................. 22

TeamForge Git integration: FAQ......................................................................... 24TeamForge Git integration: Install FAQ............................................................................................................24TeamForge Git integration: Upgrade and Uninstall FAQ................................................................................. 24TeamForge Git integration: General usage FAQ...............................................................................................25TeamForge Git integration: Post-install FAQ....................................................................................................29TeamForge Git integration: Technical concepts FAQ....................................................................................... 30

TeamForge Git integration reference...................................................................34Mappings between TeamForge and Gerrit.........................................................................................................34Access rights in Gerrit 2.8.x.............................................................................................................................. 35Gerrit directory structure, connectivity and more..............................................................................................38Gerrit configuration properties........................................................................................................................... 40Technical differences compared to vanilla Gerrit..............................................................................................41

TeamForge Git integration release notes............................................................42

| Contents | 3

TeamForge Git integration 8.2.x release notes.................................................................................................. 42Highlights: TeamForge Git integration 8.2.0-2......................................................................................42Highlights: TeamForge Git integration 8.2.1-1......................................................................................43Highlights: TeamForge Git integration 8.2.2-1......................................................................................43Highlights: TeamForge Git integration 8.2.4-1......................................................................................44Highlights: TeamForge Git integration 8.2.5-1......................................................................................44

| TeamForge Git integration | 4

TeamForge Git integration

TeamForge 7.1/7.2 supports an integration with the Git distributed version control tool powered by Gerrit.

Although Git is the world’s leading distributed version control system, the enterprise has been slow and tentative inits adoption. Concerned with security breaches, compliance violations and lack of governance, many organizationshave chosen to take a "wait and see" approach. With TeamForge, Git is ready for the enterprise. TeamForge lets yourealize all the benefits of Git while ensuring the security, governance and manageability your business demands. WithTeamForge, you can even manage Git and Subversion together, within each individual project.

Gerrit is an open source code review system designed to work with Git. Gerrit supports various access controlmechanisms. The TeamForge Git integration uses Gerrit as a vehicle to bring TeamForge project roles andpermissions into Git.

Highlights

• Easy Git repository management from TeamForge using TeamForge’s role based access control• Authentication using SSH keys stored in TeamForge and http using Gerrit’s http passwords• TeamForge artifact association with Git commits• Git source code browsing and code search• Single sign-on between TeamForge and the Gerrit web console• Full support of Gerrit’s APIs to connect with Continuous Integration systems like Jenkins

Note:

• TeamForge 7.1 supports two versions of the Git integration — one based on Gerrit 2.1.10 (version 7.1.x ofthe integration) and the other based on Gerrit 2.8.x (version 8.2.x of the integration).

• TeamForge 7.2 supports Gerrit 2.8.x (version 8.2.x of the integration).

Using this guideUse this guide for version 8.2.x of the Git integration which is based on Gerrit 2.8.x and supported by TeamForge7.1/7.2:

• Release notes• Install the Git integration

For the Git integration based on Gerrit 2.1.x and supported by TeamForge 7.1, see the TeamForge Git integration -Gerrit 2.1.x guide.

http://help.collab.net/topic/teamforge71-git-gerrit21x/action/setup-teamforge-git-integration.html

http://help.collab.net/topic/teamforge71-git-gerrit21x/action/setup-teamforge-git-integration.html

| TeamForge Git integration | 5

For releases of the Git integration supported by earlier versions of TeamForge, see these guides:

• TeamForge 7.0• TeamForge 6.2.x

Related LinksGitGerrit

http://help.collab.net/topic/teamforge7x-git-integration/faq/teamforge_git_integration_overview.html

http://help.collab.net/topic/teamforge-git-integration/faq/teamforge_git_integration_overview.html

http://git-scm.com/

http://code.google.com/p/gerrit/

| Set up the TeamForge Git integration | 6

Set up the TeamForge Git integration

Version 8.2.x of the TeamForge Git integration is based on Gerrit 2.8.x and is available with TeamForge 7.1/7.2.

Install the TeamForge Git integrationVersion 8.2.x of the TeamForge Git integration is provided in an RPM package called ctf-git-integration-NG.rpm. This package is available as a separate download or as part of a CollabNet YUM repository.

• Automated installation of version 8.2.x of the Git integration is only supported on CentOS and RHEL incombination with TeamForge 7.1/7.2. If you are using SuSE or an older version of TeamForge, automatedinstallation is available for version 7.1.x of the Git integration; contact your sales representative for manualinstructions on running version 8.2.x.

• For platform information, see

• 7.1: Specifications for TeamForge 7.1• 7.2: Specifications for TeamForge 7.2

1. Follow the TeamForge 7.1 installation process or TeamForge 7.2 installation process for your scenario up to thestep on configuring your TeamForge installation repository.For example, if you are performing a dedicated install of TeamForge 7.1 with all services (including the Gitintegration) on one server, this is Step 4: "Configure your TeamForge 7.1 installation repository".

2. When you have configured the TeamForge 7.1/7.2 installation repository, install the following additional RPMpackages for the Git integration.

• If you downloaded the RPMs, run these commands:

yum install ctf-git-integration.rpm --nogpgcheckyum install ctf-git-integration-NG-migration.rpm -–nogpgcheckyum install ctf-git-integration-NG.rpm –nogpgcheck

• If you are using CollabNet's YUM repository, run this command:

yum install ctf-git-integration-NG –nogpgcheck

Note: As part of the installation process, we install and configure Gerrit 2.1.10 first; immediately afterthat, we run multiple automated upgrade steps until we get to Gerrit 2.8.x. So don't worry if you seemigration RPMs getting installed or migration steps running even though you are performing a newinstall.

3. Continue with the rest of the TeamForge install process.

Related LinksTeamForge Git integration: Install FAQ on page 24Questions about installing version 8.2.x of the TeamForge Git integration.

Install the Git integration based on Gerrit 2.1.10 for TeamForge 7.1.

Migrate to version 8.2.x from an earlier version of the TeamForge Gitintegration

If you are already running a version of the Git integration older than 8.0, you can migrate to version 8.2.x.

Note: Version 8.2.x of the TeamForge Git integration is provided in an RPM package called ctf-git-integration-NG.rpm. This package is available as a separate download or as part of a CollabNet YUMrepository.

http://help.collab.net/topic/sysadmin-710/reference/teamforgeplatform.html


http://help.collab.net/topic/sysadmin-710/action/teamforge-setup.html


http://help.collab.net/topic/sysadmin-710/action/redhat_teamforge-install-dedicated.html

http://help.collab.net/topic/sysadmin-710/action/redhat_teamforge-install-dedicated.html

http://help.collab.net/topic/teamforge71-git-gerrit21x/action/teamforge-git-install.html


• Depending on how you got the integration package, do one of the following:

• If you downloaded the RPM, run these commands:

yum install ctf-git-integration.rpm --nogpgcheckyum install ctf-git-integration-NG-migration.rpm -–nogpgcheckyum install ctf-git-integration-NG.rpm -–nogpgcheck

• If you are using CollabNet's YUM repository, run this command:

yum install ctf-git-integration-NG -–nogpgcheck• Run the following commands on the server where the Git integration is hosted:

a) Stop gerrit.

cd /tmpservice gerrit stop

b) Back up the Gerrit-related database.

su postgres -c "pg_dump reviewdb > /tmp/reviewdb_beforemigration.dump"Copy /tmp/reviewdb_beforemigration.dump to a safe location.

c) Run the post-install.py script.

sudo /opt/collabnet/gerrit/scripts/post-install.py

Upgrade version 8.2.x of the TeamForge Git integration to the latestrelease

If you have version 8.2.x of the TeamForge Git integration installed, and a newer release is now available, you caneasily upgrade to it.

Note: Version 8.2.x of the TeamForge Git integration is provided in an RPM package called ctf-git-integration-NG.rpm. This package is available as a separate download or as part of a CollabNet YUMrepository.

• Depending on how you got the integration package, do one of the following:

• If you downloaded the RPM, run this command:

yum update ctf-git-integration-NG.rpm –nogpgcheck• If you are using CollabNet's YUM repository, run this command:

yum update ctf-git-integration-NG -–nogpgcheck• If you initially configured the Git integration while using TeamForge 6.2.x, run the following commands on the

server where the Git integration is hosted:a) Stop gerrit.

cd /tmpservice gerrit stop

b) Run the ctf-git-integration-setup.sh script.

sudo /usr/sbin/ctf-git-integration-setup.sh

Note: Starting from Gerrit 2.6.x, we do not run Gerrit init in the interactive mode any longer.If you want to change the configuration parameters, you need to modify gerrit.config andsecure.config directly before you run this script.

c) Start gerrit.

service gerrit start• If you did not initially configure your Git integration with TeamForge 6.2.x, run the following commands on the

server where the Git integration is hosted:

cd /tmp


sudo /opt/collabnet/gerrit/scripts/post-install.py

Related LinksTeamForge Git integration: Upgrade and Uninstall FAQ on page 24Questions on upgrading and uninstalling the TeamForge Git integration.

| Add Gerrit as a linked application | 9

Add Gerrit as a linked application

You can set up Gerrit as a linked application to your TeamForge site.

• Set up the URL http://<TEAMFORGEHOSTNAME>/gerrit/sso/.

Note: The last "/" matters. Make sure you have it.

• For instructions on setting up a site-wide linked application in TeamForge, see Create a site-wide linkedapplication in TeamForge.Here's an example for Gerrit:

A link for Gerrit is added to the More menu in your TeamForge navigation bar.

Clicking Gerrit displays the Gerrit console in the main TeamForge window.

http://help.collab.net/topic/teamforge710/action/siteadmin-creatingasitewidelinkedapplication.html

http://help.collab.net/topic/teamforge710/action/siteadmin-creatingasitewidelinkedapplication.html

| Set up Code Search for the TeamForge Git integration | 10

Set up Code Search for the TeamForge Git integration

To use TeamForge Code Search functionality with Git, manually grant the TeamForge Code Search userscmviewer permissions to access all Git repositories.

In TeamForge 6.2 (and later versions), Code Search functionality is available through integration with Black DuckCode Sight.

Note: If you have integrated Code Search functionality already while installing an older version of theTeamForge Git integration, you can skip the following instructions because the installer would have migratedyour settings.

1. Make sure that a Unix system user with the name scmviewer exists. If not, create this user by running thefollowing command:

useradd scmviewer

2. Before you can set up Code Search for the Git integration, import the Code Search public key into TeamForge.a) On the Code Search box, check whether the key is present at /root/.ssh/id_rsa.pub. If not, generate it

by running the ssh-keygen command.b) Copy it to a temporary location (/tmp) on the TeamForge application server.c) Run the set_auth_key.py script for the scmviewer user on the TeamForge application server.

Note: This script requires TeamForge site administrator credentials.

cd /opt/collabnet/teamforge/runtime/scripts/codesearch/

./set_auth_key.py --authkey-file=/tmp/id_rsa.pub

3. Sync the scmviewer user to Gerrit by running the following command in a shell on the host where you installedthe Git integration.

curl http://localhost:9081/api/gerrit/users/scmviewer/sshkeys

Once the scmviewer user is present in Gerrit, you must grant this user read permissions for all Gerrit projects. Loginto Gerrit’s Web interface as a Gerrit super user and so the following:4. On the People tab, click Create New Group” and create an internal Gerrit group.5. Add the scmviewer user to the group.6. On the Projects tab, click All-Projects.7. On the Access tab, click Edit.

Here's an example:

| Set up Code Search for the TeamForge Git integration | 11

You will see Reference display ref/*.8. For Group Name in the Read section, enter the name of the internal group you created.9. Select ALLOW for the users you want to grant read access.10. Click Save Changes.11. Log out from Gerrit.

After the initial re-indexing, you should be able to use Code Search with Git.

| Control the code review policy for Git repositories | 12

Control the code review policy for Git repositories

With versions of the TeamForge Git integration greater than 6.2, you can control all Gerrit Code Review featuresdirectly from TeamForge by specifying a code review policy as part of the TeamForge Git repository's descriptionfield.

For more information on Gerrit Code Review, see the Gerrit documentation.

By default, the following code review policy options are provided:

• Default (no code review): All Gerrit review features are turned off and read/write access is enforced.• Mandatory review: All code changes must be reviewed and read/write access is enforced.• Optional review: The review feature is turned on but can be bypassed if necessary; read/write access is enforced.• Custom: Access rights must be set manually in the Gerrit web interface; they will not be overridden by

TeamForge. This specification is intended for advanced users who are familiar with Gerrit access rights and wantto turn off “auto pilot”.

If you have access to the TeamForgeGerritMappings.xml file, you can add your own categories.

Mandatory code reviews for Git repositoriesWhen a mandatory review is specified, every change pushed to the repository must pass through a review processbefore it can get committed (merged) to the repository.

Only TeamForge users with the Source Code Admin permission can bypass reviews.

http://code.google.com/p/gerrit/


Here's a list of permissions and what users with these permissions can do:

• No access: Users with no permissions cannot do anything.• View only: Users with read permissions can read branches and push for reviews, and have -1 and +1 for reviews.• Commit/View: Users with commit permissions can do everything read permissions would grant and in addition

have -2, +2 for reviews. They can verify and submit permissions but have no right to bypass reviews.• Delete/View: Users with delete permissions can do everything commit permissions would grant.• Source Code Admin: Users with admin permissions can do everything delete permissions would grant and in

addition push to and create any branch (bypassing review). They can rewrite history, forge the identity of theGerrit server, and have the right to push tags, the right to upload merges, and the right to fine tune access rights inGerrit for the Gerrit project involved.

Note: In TeamForge 6.2, the code review policy for a Git repository is defined in the Description field. Ifyou had specified the code review policy in TeamForge 6.2 and have now upgraded TeamForge to version7.1, you will see the appropriate code review option selected in the TeamForge 7.1 user interface. TheDescription field will still display the [RepoCategory:<Category_name>], but you can remove it since it doesnot have any effect in TeamForge 7.1.

Related LinksSet up a code review process for TeamForge Git repositories

Optional code review for Git repositoriesWhen an optional review is specified, every change submitted to the repository can be pushed for code review ordirectly pushed to the repository bypassing review. This depends on the TeamForge user having the appropriatepermissions — source code Delete/View or Commit/View permission for the former, or Source Code Adminpermission for the latter.



• No access: Users with no permissions cannot do anything.• View only: Users with read permissions can read branches and push for reviews, and have -1 and +1 for reviews.• Commit/View: Users with commit permissions can do everything read permissions would grant and in addition

have -2, +2 for reviews. They can verify and submit permissions, push to/create any branch (bypassing review)and push tags.

• Delete/View: Users with delete permissions can do everything commit permissions would grant and in addition,have the right to rewrite history, upload merges and forge identity.

• Source Code Admin: Users with admin permissions can do everything delete permissions would grant and inaddition push to/create any branch (bypassing review). They can rewrite history, forge the identity of the Gerritserver, and have the right to push tags, the right to upload merges, and the right to fine tune access rights in Gerritfor the Gerrit project involved.



Default code review for Git repositoriesIn TeamForge 7.x, the default code review policy — no code review required — is selected unless you choose someother policy.



• No access: Users with no permissions cannot do anything.• View only: Users with read permissions can only read branches.• Commit/View: Users with commit permissions can do everything read permissions would grant and in addition,

push to/create any branch and push tags.• Delete/View: Users with delete permissions can do everything commit permissions would grant and in addition,

have the right to rewrite history, upload merges and forge identity.• Source Code Admin: Users with admin permissions can do everything delete permissions would grant. In

addition, they can forge the identity of the Gerrit server, and have the right to fine tune access rights in Gerrit forthe Gerrit project involved.



Custom code review for Git repositoriesWhen a custom code review is specified, users with the TeamForge Source Code Admin permission can directly finetune permissions (access rights) in Gerrit’s web interface. Those changes will not be overridden by TeamForge.


For information on manually defining access rights in the Gerrit web interface, see Update Git repository accesspermissions in Gerrit.


• No access: Users with no permissions cannot do anything.• View only: Users with read permissions cannot do anything unless added in Gerrit.• Commit/View: Users with commit permissions cannot do anything unless added in Gerrit.• Delete/View: Users with delete permissions cannot do anything unless added in Gerrit.• Source Code Admin: Users with admin permissions have the right to fine tune access rights in Gerrit for the Gerrit

project involved.


| Update Git repository access rights in Gerrit | 17

Update Git repository access rights in Gerrit

By default, Gerrit projects (TeamForge Git repositories) are only visible to TeamForge users assigned a project rolewith SCM permissions. To grant additional rights (for example, read access) to all registered users, or to TeamForgeglobal groups, or to a custom subset of users (a Gerrit internal group), log directly into the Gerrit console and makethose changes.

1. In your browser, bring up http://<GITSCMSERVERHOSTNAME>/gerrit/.2. Log into Gerrit using the TeamForge site administrator username and password you provided while running the

Git installer's configuration script.3. Select the Projects tab and click Lists.4. In the All Projects page, click Access.

You will see a list of all default access rights.5. To change an access right, click Edit and select a reference.

If you want to add a new reference, click Add Reference, select a permission from the Add Permission drop-down list and add it.

Here's an example where the group "AdminPlus" is assigned "Read" access for the reference "refs/heads/*".

6. Click Save Changes.

Related LinksTeamForge Git integration: Technical concepts FAQ on page 30Questions on some of the TeamForge Git integration's more technical aspects.

Mappings between TeamForge and Gerrit on page 34These tables shows how objects and relationships are mapped between TeamForge and Gerrit.

Access rights in Gerrit 2.8.x on page 35Earlier versions (pre-8.1.x) of the Git integration with TeamForge were based on Gerrit Code Review 2.1.x. Version8.2.x of the Git integration is based on Gerrit Code Review 2.8.x. This brings significant changes to Gerrit accessrights.

| TeamForge Git integration: History protection | 18

TeamForge Git integration: History protection

History rewrites are non-fast-forward updates of remote refs and associated objects. History rewrites happen whena branch in a remote repository gets deleted, previously pushed commits get amended or filtered and forcefully re-pushed, or a remote branch/tag is pointed to an entirely different commit history.

History may get rewritten without leaving any trace of the previous state. Sometimes this behavior may be wanted— for example, in the case of removing code violating intellectual property, removing mistakenly committed largebinary files or removing merged feature branches. The TeamForge Git integration therefore does not disable thehistory rewrite feature, but instead enables it for SCM Administrators alone. However, since rewriting history mightbe easily abused and result in accidental data loss, we've introduced the History Protection feature as a safety net andnecessity for ensuring proper audit compliance.

History protection archives rewritten changes and keeps backups of deleted branches. If history changes occur, animmutable backup ref is created in the remote repository, notification emails are sent to all members of the GerritAdministrators group, and an event is logged in the audit log. The backed up ref can be restored into a new branchwith any Git client (without needing physical file access to the Gerrit server). Gerrit site administrators can still decideto remove selected backup refs permanently.

TeamForge Git integration: Enable history protectionYou can turn on history protection for the entire integration server or for an individual Git repository.

• To turn on history protection server-wide (for all the repositories hosted on the Git integration server), do thefollowing:a) Set GERRIT_FORCE_HISTORY_PROTECTION=true in /opt/collabnet/teamforge/runtime/

conf/runtime-options.conf.b) Restart the gerrit service.

/etc/init.d/collabnet restart gerrit

Note: If you enable history protection server–wide, it cannot be overridden (turned off) for an individualGit repository. It will remain in effect for all Git repositories on the integration server.

• To turn on history protection for an individual Git repository in a TeamForge project, select the Protect Historyoption while creating the repository. For an existing repository, do the following:a) On the Source Code page, select the Git repository and click Editb) Select the Protect History option.


c) Click Save.

You can turn history protection on or off any time. However, your change will not be reflected in Gerrit immediately.It will be effective after the time that you defined as the regular refresh interval while installing the Git integration.

If you want your change to take effect immediately, do this right after you select or de-select the Protect Historyoption: as a user with the Source Code Admin permission, temporarily remove any user having a project role withany SCM permission, and then add that user back. This will trigger an immediate sync which will enable historyprotection. After that, the Gerrit Administrator will be able to see History Protection enabled in the Gerrit webinterface (by logging in as a Gerrit Administrator and clicking the General link for the project with the name of theGit repository).

Note: In TeamForge 6.2, history protection for a Git repository is turned on from the Description field.If you had turned on history protection in TeamForge 6.2, and have now upgraded TeamForge to version7.1/7.2, you will see the History Protect option selected in the TeamForge 7.1/7.2 user interface. TheDescription field will still contain [Repo:ProtectHistory], but you can remove it since it does not have anyeffect in TeamForge 7.1/7.2.

History protection reportsOnce history protection is turned on, any non-fast-forward push to a remote repository or deletion of a branch or tagon a remote repository is recorded and reported.

Email notificationsWhen history is rewritten, an email is sent to the Administrator group members in Gerrit.


Gerrit web interfaceEvery history rewrite event is logged and stored in the Gerrit database and visible in the Gerrit web interface. AsGerrit Administrator, you can —

• See rewritten history from Project > Rewritten History.

• Restore history by clicking Resurrect and providing a name for the new branch.

• Permanently remove a branch by clicking Delete Permanently.

Git command lineYou can use a standard Git client and run git fetch && git ls-remote for information on rewritten anddeleted branches.


You can view entries in refs/rewrite (for non-fast-forward pushes) and refs/delete using the Git ls-remote command only if read access is granted to refs/*. Gerrit will prevent any other action such as delete/force-update on those special refs for all users including administrators.

Audit log entriesThe following events are logged in /opt/collabnet/gerrit/logs/gerrit.audit.log:

• Remote branches are deleted• History is rewritten (non-fast-forward push)• Backup branches are resurrected• Backup branches are permanently deleted• History Protection is turned on or off

TeamForge Git integration: History protection FAQQuestions on history protection for Git repositories in TeamForge.

What is history protection? History rewrites are non-fast-forward updates of remoterefs and associated objects. History rewrites happenwhen a branch in a remote repository gets deleted,previously pushed commits get amended/tree filteredand forcefully re-pushed, or a remote branch/tag ispointed to an entirely different commit history. For moreinformation, see History Protection.

Is it possible to turn on history protection for all Gitrepositories hosted on a Git integration server? If yes,how?

Yes, a user with file system access to the Unixmachine where the Git integration is hosted canturn on history protection. First set the propertyforceHistoryProtection = true in /opt/collabnet/gerrit/etc/gerrit.config in the[gerrit] section. Then restart the gerrit service byrunning $ service gerrit restart on a shell.

With TeamForge 7.1, do the following:

• SetGERRIT_FORCE_HISTORY_PROTECTION=truein /opt/collabnet/teamforge/runtime/conf/runtime-options.conf.

• Restart the gerrit service.

/etc/init.d/collabnet restart gerrit

I've enabled Protect History for my TeamForgeproject's Git repository. Will this be effectiveimmediately?

To enable history protection immediately, a TeamForgeuser with the Source Code Admin permission must dothis right after enabling Protect History: temporarilyremove any user with a project role with any SCMpermission, and then add that user back. This will triggeran immediate sync after which history will be protectedfor the Git repository. Otherwise, history protection willbe enabled after a periodical sync.

Can I turn off history protection for any particularGit repository when it is enabled server-wide?

No, when history protection is enabled server-wide forthe Git integration server, it cannot be turned off for aparticular Git repository.

http://help.collab.net/topic/teamforge71-git-gerrit21x/reference/History_rewrite.pptx


Where can I see the backup branches generated byhistory protection?

Backup branches are generated based on the type ofHistory Rewrite. For a remote branch that is deleted,this is under refs/delete. For a non-fast-forwardpush, this is under refs/rewrite with the branchname containing the timestamp, original branch andthe user who rewrote history, for example, refs/delete/20121112042512-test--david.

Who can resurrect or permanently delete backupbranches?

A user who is a member of the Gerrit Administratorgroup can resurrect or permanently delete backupbranches. By default, the TeamForge site administratorwhose credentials are used for running the post-installation script is part of the Gerrit Administratorgroup.

Who can see backup branches? By default, a TeamForge user with SCM View (or more)permission can see all backup branches by executinggit fetch && git ls-remote origin. InGerrit, the user must be part of a group which has at leastread access for refs/delete and refs/rewritefor the given Gerrit project (TeamForge Git repository).

Are the backup branches under refs/rewrite andrefs/delete protected from Git garbage collectionwhich removes unreferenced objects?

Yes, objects in backup branches under refs/rewriteand refs/deleted are referenced and cannot becleaned up by Git's garbage collection.

Do backup branches take up a lot of disk space on theGit server?

The backup branches on the Git server are mainlyGit objects that are compressed deltas of original fileversions. Git regularly compresses these objects to savedisk space.

What is the difference between Git reflog and HistoryProtect?

In Git, reflog records all activity on a branch, whileHistory Protect only reports deleted branches/tags andhistory rewrites (non-fast-forward pushes) For detailsof all the differences, see Git reflog vs TeamForge Gitintegration History Protect.

GERRIT_FORCE_HISTORY_PROTECTIONThe GERRIT_FORCE_HISTORY_PROTECTION token determines whether the history protection feature of theTeamForge Git integration is enabled. If it is set to TRUE, history protection is turned on for all repositories hosted onthe Git integration server.

Values

TRUE or FALSE

DefaultFALSE

Comments

In TeamForge 7.0 (and later versions), this token is defined in the runtime-option.conf file to support thenon-interactive installation of the Git integration. After Gerrit's post-install script is run, the value of this token isused to set the configuration property forceHistoryProtection in the /opt/collabnet/gerrit/etc/gerrit.config file.

http://git-scm.com/book/en/Git-Internals-Git-Objects

http://www.kernel.org/pub/software/scm/git/docs/git-reflog.html

http://help.collab.net/topic/teamforge71-git-gerrit21x/reference/Git%20reflog%20vs%20TF%20History%20Protect.docx

http://help.collab.net/topic/teamforge71-git-gerrit21x/reference/Git%20reflog%20vs%20TF%20History%20Protect.docx


For more information on enabling history protection, see TeamForge Git integration: Enable history protection onpage 18.

| TeamForge Git integration: FAQ | 24

TeamForge Git integration: FAQ

Use this background information to set up, maintain, support and work with the TeamForge Git integration.

TeamForge Git integration: Install FAQQuestions about installing version 8.2.x of the TeamForge Git integration.

What are the requirements for running the installer? • For the required software, see:

• TeamForge 7.1 platform specifications• TeamForge 7.2 platform specifications

• You need to install and configure TeamForge 7.1/7.2to work with the Git integration. Before you proceedto install version 8.2.x, see Install TeamForge 7.1 orInstall TeamForge 7.2.

Note: In addition, you will need a non-expiring,non-lockable TeamForge user account with siteadministrator permissions

Do I need to shut down any TeamForge services torun the Git integration installer?

As long as you don't change any of the TeamForge siteoptions, you don't need to stop any TeamForge services.If you change TeamForge site options, you will needto rebuild the TeamForge runtime which will require arestart of all TeamForge services.

How do I disable Gravatar support from theTeamForge Git integration?

If you have installed version 7.0.2 (or later) ofCollabNet's customized Gitweb-caching, Gravatarsupport is enabled by default. To disable this supportsite-wide, comment out the following lines (by includinga # at the beginning of each line) in the file /var/www/gitweb-caching/gitweb_defaults.pl:

'avatar' => { 'sub' => \&feature_avatar, 'override' => 0, 'default' => ['gravatar']},

Related LinksInstall the TeamForge Git integration on page 6Version 8.2.x of the TeamForge Git integration is provided in an RPM package called ctf-git-integration-NG.rpm. This package is available as a separate download or as part of a CollabNet YUM repository.

TeamForge Git integration: Upgrade and Uninstall FAQQuestions on upgrading and uninstalling the TeamForge Git integration.

How do I migrate the current version of my Gitintegration to version 8.2.x?

If you are running a version of the Git integration olderthan 8.2.x, you can migrate to version 8.2.x. For details,






see Migrate to version 8.2.x of the TeamForge Gitintegration.

My Git integration is already on version 8.2.x. Howcan update it to latest available version?

If you already have version 8.2.x, see Upgrade version8.2.x of the TeamForge Git integration to update it to thelatest available version.

Is there any downtime during the upgrade? Only the amount of time it will take to upgrade thebinary and change the configuration (if required).TeamForge itself does not have to be rebooted.

How do I uninstall the Git integration? To uninstall the integration, do the following:

1. yum remove ctf-git-integration

2. As the TeamForge site administrator, log intothe TeamForge web interface and remove thecorresponding external integration.

Note: When you remove the integration, allGit repositories created with the integrationare removed from TeamForge. Subsequently,you will not be able to see associationsrelated to those repositories (commitobjects). However, bare Git repositories arenot removed from the server where the Gitintegration is hosted and will exist on the filesystem in the /gitroot directory.

Related LinksUpgrade version 8.2.x of the TeamForge Git integration to the latest release on page 7If you have version 8.2.x of the TeamForge Git integration installed, and a newer release is now available, you caneasily upgrade to it.

TeamForge Git integration: General usage FAQGeneral usage questions about the TeamForge Git integration.

What are the next steps after the post-installationscript runs?

After running the post-installation script, first create anSCM repository of type Git in your TeamForge project.Then add at least one project role with SCM permissionsto access that repository and assign that role to one ormore users. With the appropriate credentials (uploadedauthorized keys) and the clone URL provided in theSource Code page, users will be able to clone the Gitrepository.

I am a site admin (or project admin or have globalSCM permissions) and am looking at a public project.Why can't I access a newly created repository fromthe TeamForge web interface or clone it using my Gitclient?

A new project role with source code permissions mustexist. A user needs this role to access the repositoryfrom the TeamForge web interface. Project administratorrights, site administrator rights, global roles, and defaultaccess permissions for project membership are currentlyignored by the Git integration.

I've created a Git repository but it does not show upin Gerrit. Why might this happen?

TeamForge repositories are synched only if there isat least one project role with SCM permissions in thecorresponding TeamForge project. Once you createsuch a project role, the synch should happen, and therepository should appear as a project in Gerrit.


How can I log into Gerrit? If your administrator has set up Gerrit as a linkedapplication to TeamForge, you will automatically belogged into Gerrit (SSO) when you click its link. If not,access the URL http(s)://<yourtfinstance>/scm integration server>/gerrit/ andprovide your TeamForge credentials.

What are the Git protocols that work with the Gitrepositories managed by TeamForge?

The Git integration currently allows you to access aGit repository using SSH. That said, you must havegenerated an SSH key pair and uploaded the SSH publickey to TeamForge in My Settings > Authorized keys.

Alternatively, you can use http(s) to clone and push toGit repositories. In this case, you can authenticate usingyour TeamForge user name and password or Gerrit’sgenerated http password.

How can I use http(s) for accessing Git repositories? With version 8.2.x of the TeamForge Git integration,there are two possibilities for accessing Git repositoriesover http(s).

The clone URL for http(s) access followsthis convention: git clone https://$USERNAME@<yourtfinstance/scmintegration server>/gerrit/p/<TFreponame>.

When you run the above command on your Git client,you will be asked to provide your credentials. You canchoose between the following two methods to do so:

• Standard TeamForge credentials: Use the samecredentials you use to log into TeamForge’s webinterface

• Gerrit http credentials: Gerrit provides an option togenerate a separate HTTP password that you can useexclusively for Git-related operations.

To enable http(s) access, log into Gerrit’s Web interfaceand generate an HTTP password (Settings > HTTPPassword > Generate Password). This password willnot match your TeamForge password; you will need toprovide it to your Git client whenever you perform anoperation that requires accessing the Git server.

How do I generate an SSH key pair? You can generate an SSH key pair on a Unix machine byrunning the following shell command:

$ ssh-keygen -t rsa

(You will be asked to provide the location to store thekey pair. The default is the home directory of the logged-in user.)

After installing a Git client, I am able to clone a Gitrepository into my local work directory. However,I am not able to "push" anything to the remoterepository in spite of having view and commitpermissions. What should I do ?

Right after you clone, but before you commit anychanges locally, you will need to configure Git if youhaven't already.

$ git config --global user.name"<TeamForge username>"


$ git config --global user.email"<email used in TeamForge for theuser>"

You should now be able to push your changes.

Is a commit association created in TeamForge after Ipush my commit to a remote Git repository?

Yes, when you push a local commit to the remoterepository, an association will get created if the commitmessage contains a reference to a TeamForge item suchas a tracker artifact, wiki or document in square brackets,for example [artf1234].

Note: A commit association will not be createdif you push your commit to Gerrit's "reviewbranch" (push for review). It will be createdonce the change is merged into the real branch.

What happens if the TeamForge site is down orthere are some network problems — will the Gitintegration still work?

The Git integration will still work, but with the followinglimitations:

• If the TeamForge site is down, users will not be ableto see commit associations created in TeamForge, butstill be able to push commits to a Git repository.

• If the Git integration is hosted in LOCAL mode,network-related problems would definitely preventchanges being pushed to a Git repository.

• If the Git integration is hosted in REMOTE mode,the synchronization of roles and permissions will becached during the period when TeamForge is down;Git will function with the roles and permissionssynched already.

What is a "Jumbo Push"? In contrast to Subversion, Git has the concept of localcommits that stay in the local environment of a user,and at some point, get pushed to a remote repository allat once. This push checks in changes from all commitsinto the remote repository. For each of those commits, acommit object appears in the TeamForge (Source Codecomponent). So, one push can have an unlimited numberof commits and thus commit objects in TeamForge. Youcan, however, define the threshold for a single pushbased on how many commits should generate a commitobject. A push' containing commits beyond that thresholdis called a "Jumbo Push"'. You can configure the JumboPush threshold by running the post-installation script.

What objects and relationships are mapped betweenTeamForge and the Git integration?

See the README (APPENDIX, Relationship and Objectmapping section) or Mappings between TeamForge andGerrit on page 34.

When are the objects and relationships synchronizedbetween TeamForge and the Git Integration?

TeamForge project roles, project role SCM permissions,global groups, SCM repositories, and global group/project role membership are synched in two ways:

• Synchronously: after a regular interval (configurableusing the post-installation script)

• Asynchronously: whenever there is a change relatedto roles or permissions within TeamForge, it triggersthe sync between TeamForge and the Git integration.


TeamForge repositories are only synched if there is atleast one project role with SCM permissions present inthe corresponding TeamForge project.

TeamForge users are provisioned in Gerrit whenever you—

• Change their authorized keys in TeamForge• Log into Gerrit by clicking the linked application link

or using TeamForge username and password• Access GitWeb (web interface for a Git repository)

by clicking a Git repository link in the TeamForgeSource Code page

Note: Changes in Gerrit are not synched backto TeamForge.

Where can I find system logs for the Git integration? You can find the logs under /opt/collabnet/gerrit/logs/. For more on log files, refer to theREADME or Gerrit directory structure, connectivity andmore on page 38.

Can I bypass Gerrit and access a Git repositorydirectly?

No, Gerrit is used to enforce TeamForge accesspermissions.

TeamForge 6.2 supports an integration with BlackDuck Code Sight. Does this work with Git?

Yes. See Set up Code Search for the TeamForge Gitintegration on page 10 for more information.

I deleted a TeamForge Git SCM repository but thecorresponding Gerrit project does not get deleted.What's wrong?

Currently, Gerrit does not allow removing projectsthat are created already (so that you don't easily losesource code). One implication of this behavior is thateven though you deleted the corresponding TeamForgerepository, you will not be able to create a new one withthe same directory name.

How can I import an existing Git repository intoGerrit?

Create a new repository and configure your account sothat it has at least Delete/View SCM permissions forthe one in TeamForge. Clone your existing repositoryand force push its content to the empty TeamForgerepository:

git clone --mirror [url of repo to be imported]git gcgit remote add dest [url_to empty TeamForge Git repository]git push -f --tags dest refs/heads/*:refs/heads/*

Note: When importing a repository previouslyhosted on a different Gerrit server, do not pushthe review branches as Gerrit numerical changenumbers are not globally unique and duplicationwill result in wrong email notifications andproblems submitting open reviews.

In the TeamForge web interface, I see the repositoryroot parameter for Git set to "/tmp". Can I changethat?

For backward compatibility reasons, this parameterhas to be set to "/tmp". It does not affect where Gerritactually stores its Git repositories — this is at /gitroot.


Do we have default hook scripts available for Git inTeamForge?

Associating artifacts based on commit messages andblocking commits without a commit message is a coreTeamForge mechanism that is supported by Git as well.

To add hook scripts, see Gerrit Code Review - Hooks.

Do we have email alerts for Git in TeamForge? If yes,where do we configure it?

Email alerts based on TeamForge commits is a coreTeamForge feature, independent of the SCM involved.In addition, Gerrit sends out review emails using theSMTP server specified during installation (it defaultsto the TeamForge SMTP server). The mail template isexplained in Gerrit Code Review - Mail Templates.

Do we have Role Based Access Control and PathBased Permissions for Git in TeamForge?

We support all SCM permission cluster options forTeamForge project roles. Only TeamForge projectroles are considered; default access permissions, globalroles, project membership, site admin and project adminpermissions are ignored. Path-based permissions are notrelevant in Git since a Git commit always contains allfiles. If we did not ship certain files this would resultin a checksum error. Gerrit supports branch-basedpermissions though. For more information on branch-based permissions, see CollabNet’s blog post.

TeamForge Git integration: Post-install FAQPost-install questions on the TeamForge Git integration.

Where can I locate the post-installation script? After the installation finishes successfully, you will findthe post-installation script at either of these locationsdepending on your setup:

• If you initially configured your Git integration whilestill using TeamForge 6.2.x, you'll find the scriptat /usr/sbin/ctf-git-integration-setup.sh

• If you did not initially configure your Git integrationwith TeamForge 6.2.x, you'll find the script at /opt/collabnet/gerrit/scripts/post-install.py.

Where can I find logs for installation errors? • If you ran the /usr/sbin/ctf-git-integration-setup.sh script, you'll find theerror log at /tmp/ctf-git-integration-setup.log.

• If you ran the /opt/collabnet/gerrit/scripts/post-install.py script, you'llfind the error log at opt/collabnet/gerrit/logs/post-install.log.

Why does the post-installation script ask for theTeamForge username and password? Is it safe toprovide these values?

The TeamForge user credentials you supply are used tosynchronize TeamForge project roles and permissions.The credentials are encrypted — so it is safe to providethem.

How can I start and stop Git? After you successfully run the post-installation script,you can start (and stop) the Git service by running the

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/config-hooks.html

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/config-mail.html

http://blogs.collab.net/teamforge/managing-git-branch-level-permissions-with-teamforge-and-gerrit


following commands on a shell as the root or sudouser:

$ service gerrit start$ service gerrit stop

I provided some incorrect values while running thepost-installation script. Can I change them?

If you want to change configuration parameters thatwere provided already, modify /opt/collabnet/gerrit/etc/gerrit.config and /opt/collabnet/gerrit/etc/secure.configdirectly. After that, restart Gerrit. Gerrit willautomatically encrypt the plain text values you entered insecure.config.

I'm using CollabNet's VMware image for TeamForgewith the Git integration pre-configured. I want tochange certain parameters of the Git SCM adapter,for example, the hostname of the server. How can I dothat?

CollabNet's VMware image has standard configurationsfor the Git integration. If you want to reconfigurea property (change the hostname from the default"localhost" to the FQDN), log in as the TeamForgesite administrator and edit the property for the Gitintegration.

TeamForge Git integration: Technical concepts FAQQuestions on some of the TeamForge Git integration's more technical aspects.

How are TeamForge SCM permissions mapped toGerrit Access Rights?

See the APPENDIX section of the README or Accessrights in Gerrit 2.8.x on page 35 for information onhow relationships (including permissions) are mappedbetween TeamForge and Gerrit. The mapping fromTeamForge SCM permissions to Gerrit Access Rightsis defined in /opt/collabnet/gerrit/etc/TeamForgeGerritMappings.xml. While youcan modify this file as you see fit, CollabNet officiallysupports only the default configuration.

How can I fine tune access rights (read, write, review,submit) for certain users/groups in Gerrit?

Have a look at the README or the help at Update Gitrepository access rights in Gerrit on page 17.

What does the directory structure look like for a Gitintegration?

See the README or Gerrit directory structure,connectivity and more on page 38.

Where can I find more information about Gerrit? For more information on Gerrit, see the GerritCommunity Documentation page.

Which ports does the Git Integration use? Myorganization has a strict firewall policy, and I needto know which ports to make available for the Gitintegration.

The Git integration uses 3 ports: 9080,9081, and29418. See the README or Gerrit directory structure,connectivity and more on page 38 for moreinformation. For the integration, Git integration uses3 ports(9080,9081,29418 follow details in README)Only port 29418 should be exposed by the firewall.

I get a delay whenever I do a Git push, but not when Ido a Git fetch. What is wrong?

When you do a Git push, Gerrit tries to do a reverselookup of your IP address. If the nameserver configuredfor your Git integration server cannot do this reverselookup, it will result in a timeout. You need to configureyour nameserver list (/etc/resolv.conf) correctly.For further information, see this core Java bug.

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/index.html

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/index.html

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5092063


I ran Gerrit manually (without the service script; nowmy secure config file is gone and Gerrit does notstart up. What happened and how can I fix this?

If Gerrit is run with a different Unix user than gerrit,newly created and modified files may not belong tothe gerrit user any longer. As a consequence, whenyou try to restart Gerrit using its services script (whichswitches to the gerrit user), Gerrit might not startup due to wrong file permissions. If Gerrit detectsthat the permissions of its secure config file havebeen tampered with, it even removes this file. Youshould, therefore, only run Gerrit using the servicescript provide, and reconfigure it by running the post-install script again. You can fix incorrect permissions byrunning the following (as sudo or root):

chown -R gerrit.gerrit /opt/collabnet/gerrit

I deleted the dedicated TeamForge Gerrit useraccount in TeamForge, and SCM permission synchis no longer working. How can I recover from thissituation?

• The easy, and recommended, approach is to askCollabNet's Professional Services to undelete theTeamForge user in question.

• Otherwise, you would have to create a new dedicatedsite admin user in TeamForge, shut down Gerrit, re-run the post-install script and provide the credentialsof that user. Then, you would have to start Gerritagain, and log in with as that new user via the webinterface. You will see that the user does not haveany special admin permissions. If you still have aworking user in Gerrit's administrator group, youcould add the dedicated Gerrit user to that groupusing Gerrit's web interface. If not, you would have tomanually add the new user to the Gerrit administratorgroup by shutting down Gerrit, removing all filesfrom its caching directory, inserting the user idof the new user into Gerrit's Postgres reviewdbDB group/user membership table, and startingGerrit again. Since this probably requires you toconsult CollabNet's Professional Services as well, westrongly recommend the previous option (undeletingthe previously removed user).

Why does the Registered Users group hasStreamEvents capability in Git Integration v8.1.x bydefault?

• As Gerrit 2.7 Stream Events capability is requiredfor user whose account has been used to monitorGerrit Events on repositories hosted on Gerrit.

• As Jenkins Gerrit Trigger plug-in uses such acapability to monitor Gerrit events.

• If you have been using Jenkins CI with GerritTrigger plug-in to automatically verify code reviewrequest and already upgraded to Git Integrationv8.1.x, the Registered Users group has been giventhis capability by default. Therefore, you do not needadd this capability manually and your Jenkins CI withGerrit Trigger continues to function as usual.

• In case you’re using Jenkins CI with GerritTrigger plug-in, you may remove the StreamEvents capability as a user who is part of the GerritAdministrators group.

https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger


• To remove Stream Events:

1. Log on to Gerrit web UI.2. Select the Projects tab.3. Select All Projects > Access.4. Click Edit.5. Delete the Stream Events drop-down list.6. Click Save Changes

Related LinksUpdate Git repository access rights in Gerrit on page 17By default, Gerrit projects (TeamForge Git repositories) are only visible to TeamForge users assigned a project rolewith SCM permissions. To grant additional rights (for example, read access) to all registered users, or to TeamForgeglobal groups, or to a custom subset of users (a Gerrit internal group), log directly into the Gerrit console and makethose changes.

Mappings between TeamForge and Gerrit on page 34


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

Access rights in Gerrit 2.8.x on page 35Earlier versions (pre-8.1.x) of the Git integration with TeamForge were based on Gerrit Code Review 2.1.x. Version8.2.x of the Git integration is based on Gerrit Code Review 2.8.x. This brings significant changes to Gerrit accessrights.

| TeamForge Git integration reference | 34

TeamForge Git integration reference

Look here for information on the mappings between TeamForge and Gerrit, Gerrit access rights, directory structure,connectivity, logs and configuration properties, and differences compared to vanilla Gerrit.

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

TeamForge Object Gerrit Object

SCM repository in TeamForge project (containingproject roles with SCM permissions)

Project

Project Role Group

User Group Group

Project Role with SCM permission Access right

User User

Note: In this release, project administrator rights, site administrator rights, global roles, project groups,project group roles and default access permissions for project membership are ignored.

TeamForge Relationship Gerrit Relationship

User has a TeamForge Project Role User is part of the Group which corresponds to theTeamForge Project Role

User is part of a User Group that is assigned a ProjectRole

User is part of a Group (which corresponds to aTeamForge Project Role)

User is part of a User Group User is part of a Group (which corresponds to aTeamForge User Group

Project Role is assigned an SCM permission (such asAdmin, Delete and View, View and Commit, ViewOnly, None)

Corresponding group is assigned Gerrit access rightsmatching the assigned TeamForge SCM permissions.Those access rights are determined by the code reviewpolicy of the corresponding TeamForge repository


Update Git repository access rights in Gerrit on page 17By default, Gerrit projects (TeamForge Git repositories) are only visible to TeamForge users assigned a project rolewith SCM permissions. To grant additional rights (for example, read access) to all registered users, or to TeamForgeglobal groups, or to a custom subset of users (a Gerrit internal group), log directly into the Gerrit console and makethose changes.


Access rights in Gerrit 2.8.xEarlier versions (pre-8.1.x) of the Git integration with TeamForge were based on Gerrit Code Review 2.1.x. Version8.2.x of the Git integration is based on Gerrit Code Review 2.8.x. This brings significant changes to Gerrit accessrights.

For information on mappings between access rights in Gerrit 2.1.x and Gerrit 2.2.x (or later) see http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#conversion_table.

The Git integration maps Gerrit access rights to TeamForge Role Based Access Control (RBAC) permissions. Inearlier versions (pre-8.1.x) of the Git integration, mappings were established using the gerritforge.mappingsproperties file. For more information, see Mappings between TeamForge and Gerrit (archives). With thecurrent version of the integration, gerritforge.mappings (including custom changes you mighthave done) is automatically migrated to an XML file located at /opt/collabnet/gerrit/etc/TeamForgeGerritMappings.xml. The following tables shows how TeamForge RBAC permissions are nowmapped to Gerrit access rights by default.

Code review policy TeamForge permission cluster Gerrit access right

SCM None -

SCM View Only Read

SCM Commit/View ReadPushCreate ReferencePush Annotated Tag (refs/tags/*)Push Signed Tag (refs/tags/*)

SCM Delete/View ReadPush (forcePush)Create ReferenceForge Author IdentityForge Committer IdentityPush Annotated Tag (refs/tags/*)Push Signed Tag (refs/tags/*)

Default

SCM Admin ReadPush (forcePush)Create ReferenceForge Author IdentityForge Committer IdentityForge Server IdentityOwnerAbandonPush Annotated Tag (refs/tags/*)Push Signed Tag (refs/tags/*)

SCM None -Optional Review

SCM View Only ReadView DraftsPublish DraftsCode Review -1,1Push (refs/for/refs/*)Rebase(refs/for/refs/*)

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#conversion_table

http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#conversion_table

http://help.collab.net/topic/teamforge71-git-gerrit21x/reference/teamforge-git-archives-tfgerritrelationship.html


Code review policy TeamForge permission cluster Gerrit access right

SCM Commit/View ReadView DraftsPublish DraftsCode Review -2,2Verify -1,1SubmitPushCreate ReferenceRebase (refs/for/refs/*)Push Annotated Tag(refs/tags/*)Push Signed Tag (refs/tags/*)

SCM Delete/View ReadView DraftsPublish DraftsCode Review -2,2Verify -1,1SubmitPush (forcePush)Create ReferenceRebase (refs/for/refs/*)Create ReferencesPush Signed Tag (refs/tags/*)Push Annotated Tag (refs/tags/*)Push Merges(refs/for/refs/*)Forge Author IdentityForge Committer Identity

SCM Admin ReadView DraftsPublish DraftsDelete DraftsCode Review -2,2Verify -1,1SubmitPush (forcePush)Create ReferenceOwnerAbandonRebase (refs/for/refs/*)Create ReferencesPush Signed Tag (refs/tags/*)Push Annotated Tag (refs/tags/*)Push Merges(refs/for/refs/*)Forge Author IdentityForge Committer IdentityForge Server Identity

SCM None -Mandatory Review

SCM View Only ReadView DraftsPublish Drafts


Code review policy TeamForge permission cluster Gerrit access rightCode Review -2,2Push (refs/for/refs/*)Rebase (refs/for/refs/*)

SCM Commit/View ReadView DraftsPublish DraftsCode Review -2,2Verify -1,1SubmitPush(refs/for/refs/*)Rebase (refs/for/refs/*)

SCM Delete/View ReadView DraftsPublish DraftsCode Review -2,2Verify -1,1SubmitPush(refs/for/refs/*)Rebase (refs/for/refs/*)

SCM Admin ReadView DraftsPublish DraftsDelete DraftsCode Review -2,2Verify -1,1SubmitPush (forcePush)Create ReferenceOwnerAbandonRebase (refs/for/refs/*)Push Annotated Tag(refs/tags/*)Push Signed Tag (refs/tags/*)Create ReferencesPush Merges(refs/for/refs/*)Forge Author IdentityForge Committer IdentityForge 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. Makesure that the resulting XML structure complies with this schema: https://forge.collab.net/gerrit/static/TeamForgeGerritMappings-8.0.0.xsd.


Update Git repository access rights in Gerrit on page 17By default, Gerrit projects (TeamForge Git repositories) are only visible to TeamForge users assigned a project rolewith SCM permissions. To grant additional rights (for example, read access) to all registered users, or to TeamForge

https://forge.collab.net/gerrit/static/TeamForgeGerritMappings-8.0.0.xsd

https://forge.collab.net/gerrit/static/TeamForgeGerritMappings-8.0.0.xsd


global groups, or to a custom subset of users (a Gerrit internal group), log directly into the Gerrit console and makethose changes.

Mappings between Gerrit Access Control and TeamForge source code permissions: blog post

Gerrit directory structure, connectivity and moreHere's some reference information on Gerrit's scalability and hardware requirements, file/directory structure,database, ports and connectivity.

Scalability and hardware requirements

• For estimated requirements and availability assumptions, see https://gerrit-documentation.storage.googleapis.com/Documentation/2.6/dev-design.html#scalability.

• For hardware considerations, see http://code.google.com/p/gerrit/wiki/Scaling.• For a detailed description of performance-related settings, see https://gerrit-

documentation.storage.googleapis.com/Documentation/2.6/config-gerrit.html.

Gerrit directory structureGerrit expects a standardized directory structure under the GERRIT_SITE directory: /opt/collabnet/gerrit,the gerrit user's home directory. The /etc/default/gerritcodereview file contains the GERRIT_SITEvariable and points to /opt/collabnet/gerrit.

Sub-directories of GERRIT_SITE (/opt/collabnet/gerrit):

- GERRIT_SITE

- .ssh: contains the SSH key for the gerrit user; generated during installation and needs to be backed up.- bin: binaries, startup script- gerrit.war: the main Gerrit service- gerrit-sync.jar: the Gerrit-TeamForge synchronization service- gerrit.sh: SYSV-style init script; launches and shuts down; linked to /etc/init.d/gerrit- cache: disk cache; does not need to be backed up; can always be re-generated on the fly.

- etc: contains all configuration information; needs to be backed up.- gerrit.config: Gerrit's main configuration file- secure.config: contains obfuscated passwords and secrets- log4j-ng.properties: contains logging settings in log4j format- TeamForgeGerritMappings.xml: defines how TeamForge access permissions are mapped to Gerrit accessrights- GerritSite.css: .css file for Gerrit Web interface branding- GerritSiteFooter.html: renders the customized footer in the Gerrit Web interface- lib: libraries, potentially customer-specific extensions, treat like the bin directory

- logs: Gerrit log files; default configuration rotates logs daily, gzips old logs; debug files are rotated after theyreach 10 MB; we keep 10 copies. You can make changes in Gerrit’s log4j-ng.properties file in /opt/collabnet/gerrit/etc.- audit.log: audit events- system.log: INFO-level logging- sshd.log: logs connections to Gerrit's SSH port (not system shell SSH)- *.gc.log: information on garbage collector usageNote: In co-hosted mode, TeamForge log rotation behavior will be used as default.- plugins: The Gerrit plugins directory includes jar files for all CollabNet plugins — TeamForge-Sync,TeamForge-History Protection and so on.

http://blogs.collab.net/teamforge/easy-guide-to-mappings-between-gerrit-access-control-and-teamforge-source-code-permissions

https://gerrit-documentation.storage.googleapis.com/Documentation/2.6/dev-design.html#scalability

https://gerrit-documentation.storage.googleapis.com/Documentation/2.6/dev-design.html#scalability

http://code.google.com/p/gerrit/wiki/Scaling

https://gerrit-documentation.storage.googleapis.com/Documentation/2.6/config-gerrit.html



- static: The content of this directory is served as gerrit/static/ to http clients. You can include logosand other custom content you refer to in your branding here. By default, it contains the schema for the TeamForge-to-Gerrit access right mapping file which can be accessed from a browser at http://<Git Integrationserver>/gerrit/static/TeamForgeGerritMappings-8.0.0.xsdYou need to back up this directory if it includes custom content.

- doc: contains README-NG.pdf, gerrit.config and log4j-ng properties templates.

- /gitroot: default location for Git repositories. The default location can be changed using the setting ingerrit.config or by symlinking the directory. You need to back up this directory.

DatabaseGerrit stores runtime information about users, groups, code reviews and commits in a PostgreSQL database calledreviewdb by default. You need to back up this database. If the Git integration is installed on the TeamForge server,it will use the same PostgreSQL install as TeamForge. If the integration is on a separate server, it will use a localPostgreSQL installation on that server. During installation, a new gerrit role and reviewdb schema get created.Note that Git does not, at any point, access TeamForge schema within the Postgres database.

To access reviewdb from Gerrit, the following line will be added by the installer to /var/lib/pgsql/9.0/pg_hba.conf:

host reviewdb gerrit samehost md5

In the "free-form" mode, we do not have full control over the Postgres installation and hb_pga.conf may containthe following conflicting line:

host all all 127.0.0.1/32 ident

If it exists, you need to comment it out (using #) to avoid clashing with this line inserted by installer:

host reviewdb gerrit samehost md5

Ports and connectivityGerrit opens three (TCP) ports: 9080, 9081 and 29418. You should expose only port 29418 outside localhost.

9080: the Gerrit Web interface This port will be proxied by Apache conf (prefix /gerrit) and doesn't need to be externally accessible.Do not expose this port to the outside.

9081: Gerrit-sync web service (REST) In the Local (or co-hosted mode), TeamForge talksto the Gerrit REST API over localhost. Gerrit talks toTeamForge over its default SOAP URL.

The Git integration needs bidirectional connectivityto the TeamForge host. In the Remote (or distributed)mode, TeamForge talks to the Gerrit REST API overan Apache proxy rule (SSL-enabled if Apache isSSL-enabled on the integration server where Gerrit isrunning). Gerrit talks to TeamForge over its defaultSOAP URL.

Do not expose this port to the outside.

29418: Gerrit SSH access Developers use the SSH protocol to push and pull sourcecode to and from Gerrit. This port needs to be open tousers.


Note: Gerrit ships its own SSH implementationand offers no shell access over this port.

Gerrit configuration propertiesGerrit 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.

CollabNet Gerrit plugins have these configuration options:

Section.teamforge

teamforge.cache-path Location where Gerrit and CollabNet Gerrit plugin storecaches. 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 defaultvalue is 300.

teamforge.apiPort Port over which TeamForge communicates with the Gitintegration. The default value is 9081

teamforge.refreshTimeOut Interval in seconds after which the Git integrationsynchronizes with TeamForge. The default value is 3600.

teamforge.jumboPushThreshold The number of commits in one Git push beyond whichthe Git integration creates only a single commit object inTeamForge. The default value is 30.

teamforge.externalSystemId ID of the TeamForge external integration system. Thevalue of this property is set by the post-installation scriptwhen the Git integration is first installed.

teamforge.url Host URL of the TeamForge site with which Git isintegrated. The value of this property is set by thepost-installation script when the Git integration is firstinstalled.

teamforge.allowPushIfTeamForgeConnectionIsDown TeamForge commit objects are validated prior tocreation. When the value of this property is "false" andconnection to TeamForge is down, validation fails.When the value of this property is "true", validationand creation of commit objects are postponed until theconnection to TeamForge is restored. The default value is"false".

teamforge.parallelRemoteCallLimit TeamForge is able to handle a certain number of parallelconnections. This parameter was introduced in order toavoid TeamForge "is out of service" issues. The defaultvalue is 9.

teamforge.maxRemoteCallRetry This parameter was introduced in order to specify thenumber of retry attempts for calls to TeamForge beforeconnection 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 theteamforge.credentialsCacheTimeOutamount 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 cacheexpires. The default value is 3600.

teamforge.reconnectInterval When the "TeamForge connection is down" state isdetected, and the number of seconds exceeds the valueof this parameter, attempts to restore connection areperformed 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 Gerritconfiguration property gerrit.basePath, which isset to /gitroot by default.

teamforge.maxFilesListedInTFCommitObject Restricts the number of entries in the SCM files listview for a particular TeamForge commit object. This isespecially useful for repository initial commit objects asthey could contain a thousand entries that get processedby TeamForge. The default value is 250.

Technical differences compared to vanilla GerritVersion 8.2.x of the TeamForge Git integration is based on a slightly modified version of Gerrit 2.8.x. Here's how thisversion is different from vanilla Gerrit.

• Possible ways of authentication:

• TeamForge account / password (for ssh and http Git operations, Gerrit Web interface)• TeamForge SSO (Gerrit Web interface)• TeamForge account / public key is stored in TeamForge Authorized Key settings (ssh Git operations)• TeamForge account / Gerrit http password (http Git operations)• Basic Auth using TeamForge account / password for Gerrit REST/RPC API (Digest is not supported)

• User data (email addresses, full names, ssh keys) is managed from TeamForge account settings• A Gerrit project is created by creating a Git repository in TeamForge• Gerrit ACLs are based on TeamForge project role memberships• Gerrit ACLs are determined based on TeamForge SCM access permissions for the project role in question• TeamForge project roles of logged-in users show up in Gerrit > Settings > Groups but do not show up in

Gerrit > People > List Groups (only internal groups show up here)• Gerrit project names must follow TeamForge repository conventions (Unix conventions, no spaces, / or capital

letters)• Additional features: History Protection, TeamForge code review policies, TeamForge commit object creation,

TeamForge artifact associations, TeamForge SOAP API to script repository, user and RBAC operations, enhancedbranding support

| TeamForge Git integration release notes | 42

TeamForge Git integration release notes

Look here for information about releases of the Git integration supported by TeamForge 7.1/7.2.

TeamForge Git integration 8.2.x release notes

Highlights: TeamForge Git integration 8.2.0-2Release date: 21 August, 2014.

TeamForge Git Integration : 8.2.0-2

Based on Gerrit: 2.8.7-3-gac4aa3f.

• Code Quality Gate wizard plug-in support.• Huge performance improvements reviewing changes in Gerrit’s Web UI and pushing large Git repositories.

Bug fixes

• Gerrit no longer truncates messages from TeamForge when it blocked a commit.• Better synchronization in the SOAP layer eliminates race conditions even in overload situations.

Gerrit approve command has been removed from Gerrit 2.8

Important: If you're using the Jenkins Gerrit Trigger plug-in to verify your changes, you may need tochange Jenkins’ behavior to approve changes as the gerrit approve command has been removed from Gerrit2.8 in favor of the more generic gerrit review command.

1. Once you upgrade your TeamForge with Git Integration v 8.2.0-2 go to your Jenkins server's Gerrit Trigger pluginconfiguration pages http://YOUR_JENKINS_HOST/gerrit-trigger/.

2. Click Advanced.

3. Change every "gerrit approve" token with "gerrit review" as shown in the following illustration.

http://gerrit-documentation.googlecode.com/svn/ReleaseNotes/ReleaseNotes-2.8.html

http://blogs.collab.net/teamforge/you-shall-not-pass-control-your-code-quality-gates-with-a-wizard-part-i

https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger


4. Save the changes.

Highlights: TeamForge Git integration 8.2.1-1Release date: 07 October, 2014.


Based on Gerrit: 2.8.7-6-gac4aa3f .

• TeamForge Site Admin support.• TeamForge Projects Hierarchy implementation without one level limitation but still restricted to 1h accuracy as

necessary. TeamForge events implementation is to be delivered later.• Extended capabilities for handling and exposing (verbose trace which email/change is affected) issue when

multiple Gerrit accounts share the same email address and Gerrit is not able to identify change author/committer,which is necessary for 'user must not approve own change' kind of Quality Gates.

• download-commands plug-in is installed by default.

Highlights: TeamForge Git integration 8.2.2-1Release date: 30 October, 2014.


Based on Gerrit: 2.8.7-10-g08a11da .

• TeamForge CommitObject creation timeout set by default for 15m. When repository is not regularly maintained(tips for scaling/maintenance are available here) underlying JGit library may develop performance issue



https://code.google.com/p/gerrit/wiki/Scaling

https://bugs.eclipse.org/bugs/show_bug.cgi?id=394078


with large files especially in large repositories when there is a lot of pushing/merging operations. As a resultTeamForge commit object creation queue could have been blocked.

• CollabNet Gerrit Core extension for customizable HTTP page header was introduced. It is available throughhttp.meta configuration parameter in gerrit.config file.

• Delete Project Plugin is part of default plugins installed with Git/Gerrit integration. It avoids unnecessary hassle toobtain plugin version corresponding to the integration.

• Fix for race condition for re-building TeamForge project hierarchy in Gerrit. In rare case of simultaneous updateof multiple projects in TeamForge, some access rights might not be applied until the following FullSync isperformed (usually after an hour). Issue is specific to Projects Hierarchy and Team Forge Site Admin Git/GerritIntegration features.

Highlights: TeamForge Git integration 8.2.4-1Release date: 11 December, 2014.

TeamForge Git Integration: 8.2.4-1

Based on Gerrit: 2.8.7-13-g8178075.

• Security fix for Gerrit 2.8.6.1 core issue that did not properly implement DENY/BLOCK for Owner permission.• Provide Site Wide Roles support for CN Git/Gerrit Integration with TeamForge 8.0 and later. Controlled by

teamforge.supportSiteWideRoles property of gerrit.config (enabled by default for new installations).• Create Project Wide Linked App in TeamForge 8.0 and later for every project with Git repositories that navigates

to the dashboards of the particular TeamForge project. Controlled by teamforge.createTFProjectLinkedAppsproperty of gerrit.config (enabled by default).

• TeamForge project hierarchy changes are now reflected immediately for CN Git/Gerrit Integration withTeamForge 8.0 and later.

• Improve suggest group performance by getting available data from cache.• Improve authentication performance by getting available data from cache.• Fix issue resulting in Gerrit Internal Server Error while user suggestion is performed for changes in repositories

that have been deleted (from TeamForge and additionally by Gerrit’s delete plug-in) and recreated while Gerritwas not restarted.

Highlights: TeamForge Git integration 8.2.5-1Release date: 14 January, 2015.

TeamForge Git Integration: 8.2.5-1

Based on Gerrit: 2.8.7-13-g8178075.

• Provide Default Access Permissions support for Git/Gerrit Integration with TeamForge 8.0 and later. Controlledby teamforge.supportDefaultAccessPermissions of gerrit.config (enabled by default for new installations).

• Add 'Site Wide Project Admin' and 'Source Code Admin' capabilities to Site Admins for Git/Gerrit Integrationwith TeamForge 8.0 and later when Site Wide Roles support is enabled. Note that Site Wide Roles support iscontrolled by teamforge.supportSiteWideRoles property of gerrit.config (enabled by default for new installations).

• Authenticate anonymous TeamForge SSO login requests for public projects for Git/Gerrit Integration.• In case Gerrit session expires or bookmark is used to access a page, after successful login there will be a redirect

back to previously visited page.• Fix for an issue that caused failures in sending Git ref update notifications.• Fix for ORM stack trace in gerrit.system.log when a user with an alternative email address clones multiple

repositories in parallel.

https://bugs.eclipse.org/bugs/show_bug.cgi?id=394078



teamforge git integration - gerrit 2.8.x (for teamforge 7...

Documents