TeamForge-Git integration: General usage FAQ

General usage questions about the TeamForge-Git integration.

How can I log into Gerrit?

If your administrator has set up Gerrit as a linked application to Teamforge, you will automatically be logged into Gerrit (SSO) when you click its link. If not, access the URL http(s)://<yourtfinstance>/scm integration server>/gerrit/ and provide your TeamForge credentials.

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

The Git integration currently allows you to access a Git repository using SSH. That said, you must have generated an SSH key pair and uploaded the SSH public key to Teamforge in My Settings > Authorized keys.

Alternatively, you can use http(s) to clone and push to Git repositories. In this case, you can authenticate using your TeamForge user name and password.

How can I use http(s) for accessing Git repositories?

From 8.2.x of the TeamForge-Git integration, there are two possibilities for accessing Git repositories over http(s).

The clone URL for http(s) access follows this convention:

git clone https://$USERNAME@<yourtfinstance/scm integration server>/gerrit/p/<TFreponame>

When you run the above command on your Git client, you will be asked to provide your credentials. Use the same credentials you use to log into TeamForge’s web interface.

How do I generate an SSH key pair?

You can generate an SSH key pair on a Unix machine by running the following shell command:

• $ ssh-keygen -t rsa

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

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

Right after you clone, but before you commit any changes locally, you will need to configure Git if you haven't already.

• $ git config --global user.name "<TeamForge username>"
• $ git config --global user.email "<email used in TeamForge for the user>"

You should now be able to push your changes.

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

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

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

What happens if the TeamForge site is down or there are some network problems — will the Git integration still work?

The Git integration will still work, but with the following limitations:

• If the TeamForge site is down, users will not be able to see commit associations created in TeamForge, but still be able to push commits to a Git repository.
• If the Git integration is hosted in LOCAL mode, network-related problems would definitely prevent changes being pushed to a Git repository.
• If the Git integration is hosted in REMOTE mode, the synchronization of roles and permissions will be cached during the period when TeamForge is down; Git will function with the roles and permissions synched already.

What is a "Jumbo Push"?

In contrast to Subversion, Git has the concept of local commits that stay in the local environment of a user, and at some point, get pushed to a remote repository all at once. This push checks in changes from all commits into the remote repository. For each of those commits, a commit object appears in the TeamForge (Source Code component). So, one push can have an unlimited number of commits and thus commit objects in TeamForge. You can, however, define the threshold for a single push based on how many commits should generate a commit object. A push' containing commits beyond that threshold is called a "Jumbo Push"'.

You can configure the Jumbo Push threshold by updating the site option token, GERRIT_GIT_PUSH_THRESHOLD in the site-options.conf file. You have to run the post-installation script after rebuilding the runtime environment. When the Git and Teamforge are hosted on the same server, the runtime involves TeamForge downtime.

What objects and relationships are mapped between TeamForge and the Git integration?

See the README (APPENDIX, Relationship and Object mapping section) or Mappings between TeamForge and Gerrit.

When are the objects and relationships synchronized between 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 (configurable using the post-installation script)
• Asynchronously: whenever there is a change related to roles or permissions within Teamforge, it triggers the sync between TeamForge and the Git integration.

TeamForge repositories are only synched if there is at least one project role with SCM permissions present in the 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 user name and password
• Access GitWeb (web interface for a Git repository) by clicking a Git repository link in the TeamForge Source Code page

Note: Changes in Gerrit are not synched back to 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 the README or Gerrit directory structure, connectivity and more.

Can I bypass Gerrit and access a Git repository directly?

No, Gerrit is used to enforce TeamForge access permissions.

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

1. Delete the Git repository in TeamForge.
2. Go to the Git repository project in Gerrit.
3. Go to Projects > General and delete the Gerrit project.

You can delete the repository even if there are open changes (repository is permanently deleted) with an option to preserve the repository, if required. Select Preserve Repository if required.

How can I import an existing Git repository into Gerrit?

You can import an existing Git repository into Gerrit as a project admin from a local machine or as a System Admin from the server.

Option 1: If you are project admin, create a new repository and configure your account so that it has at least Delete/View SCM permissions for the one in TeamForge. Clone your existing repository and force push its content to the empty TeamForge repository:

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

Option 2: If you are site admin, create a new repository from the TeamForge UI and perform the following steps from the server as a Gerrit system user to import a repository from the source into TeamForge:

# su gerrit
$ cd /tmp
$ git clone --mirror [url of repo to be imported]
$ cd reponame.git
$ git gc
$ git remote add dest file:///gitroot/reponame.git/
$ git push -f --tags dest refs/heads/*:refs/heads/*

Note: When importing a repository previously hosted on a different Gerrit server, do not push the review branches as Gerrit numerical change numbers are not globally unique and duplication will result in wrong email notifications and problems submitting open reviews.

In the TeamForge web interface, I see the repository root parameter for Git set to "/tmp". Can I change that?

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

Do we have default hook scripts available for Git in TeamForge?

Associating artifacts based on commit messages and blocking commits without a commit message is a core TeamForge 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 core TeamForge feature, independent of the SCM involved. In addition, Gerrit sends out review emails using the SMTP server specified during installation (it defaults to the TeamForge SMTP server). The mail template is explained in Gerrit Code Review - Mail Templates.

The blog post http://blogs.collab.net/teamforge/collabnet-gerrit-notifications-for-all-who-miss-the-good-ol-git-push-notifications explains how to send information on Git pushes to TeamForge forums (which act as mailing lists too).

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

We support all SCM permission cluster options for TeamForge project roles, default access permissions, project admin permissions along with the site-wide roles and site admin permissions. However, path-based permissions are not relevant in Git since a Git commit always contains all files. If we did not ship certain files, this would result in a checksum error. Gerrit supports branch-based permissions though.

For more information on branch-based permissions, see CollabNet’s blog post.