Author name

Thu, 11 Dec 2014

5 min read

Rational Team Concert and Git Integration: Setup Guide

Rational Team Concert Development Team
Last updated: October 28, 2014
Build basis: Rational Team Concert 5.0

Starting with 5.0 release, Rational Team Concert comes with built-in support for integrating with Git, with the following salient features.

Feature	Available since
Process Governance for Git’s push command	5.0
Linking Git Commits to work items in Rational Team Concert	5.0
Process Governance for Repository Access (for commands like clone, pull etc)	5.0.2

This article touches upon the overall setup required for this integration to work; and, specifically describes the setup on the Git server-side.

Setup
- Pre Requisites
- Context
Server side Configurations

Setup

Pre Requisites

5.0:

Git (http://git-scm.com/download)
Apache Smart HTTP Server (https://httpd.apache.org/download.cgi)
LDAP Server (See https://directory.apache.org/, for example).
(Setting up a LDAP server for authentication is beyond the scope of this article. We assume its existence)
Python 3.3.5 (See https://www.python.org/download/releases/3.3.5)

5.0.2:
Apart from the above-mentioned pre-requisites, the 5.0.2 features require the following additional dependencies

LibGit2 v0.21.0
Strawberry Perl 5.18.2.2 (only for Microsoft® Windows® platform)

Context

The picture above describes the overall context for this integration.

Major Entities

Rational Team Concert Server
Apache HTTP Server hosting the Git Repositories
LDAP Server for authenticating Rational Team Concert and Git users

Common Authentication via LDAP
Rational Team Concert server does NOT host the Git repositories. As shown above, it is expected to be hosted by Apache HTTP server. In order to correctly perform process enforcement for Git operations by Rational Team Concert, it is imperative that the identity of the Git user be known to Rational Team Concert.

Therefore, the need to have a common user base across Rational Team Concert and Git server (Apache HTTP server) via an LDAP arrangement.

Rational Team Concert hooks for Git

Leverages the pre-receive hook to enforce process for push operation by invoking the services of Rational Team Concert
Leverages the post-receive hook to perform Commit and work item linking, again by invoking the services of Rational Team Concert.

Git Server-side Configuration

Configuring Apache Smart HTTP server

Following names are used as place-holders to represent the respective values.

<Apache_Install_Dir> to denote the location where Apache is installed (Something like "C:Program Files (x86)Apache Software FoundationApache2.2" on Microsoft® Windows®)
<Document_Root> to denote the root directory on the server from where the documents are to be fetched
<Port_Number> to denote the port number on which the server listens for requests (Say, 9090, for example)
<Git_HTTP_Backend_Path> to denote the path of the ‘git-http-backend’ executable (For example, "C:/Program Files (x86)/Git/libexec/git-core/git-http-backend.exe/" on Microsoft® Windows®)
<Git_Core_Path> to denote the directory where Git core binaries are stored (For example, "C:/Program Files (x86)/Git/libexec/git-core/" on Microsoft® Windows®)
<RTC_Git_Hooks_Dir> to denote the directory where the RTC’s Git hook scripts are saved (For example, "C:/rtc-git-hooks")

Instructions below are structured as a series of steps similar to a check list.

Setup Steps to integrate with Rational Team Concert 5.0

Step	Actions	Result
1	Open the Apache’s configuration file in a text editor (Usually it goes by the name httpd.conf or apache2.conf depending on the platform). Make sure the following modules are enabled and getting loaded; uncomment, if necessary. LoadModule dav_module modules/mod_dav.so LoadModule dav_fs_module modules/mod_dav_fs.so LoadModule dav_lock_module modules/mod_dav_lock.so LoadModule ldap_module modules/mod_ldap.so LoadModule cgi_module modules/mod_cgi.so LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so
2	Add a VirtualHost entry with a port number for Apache to listen onto incoming requests. <VirtualHost :<Port_Number>> </VirtualHost> Listen <Port_Number>*
3	Add the Document Root directory declaration within the virtual host. Also, make sure the Apache has read and write permissions to the document root directory. DocumentRoot <Document_Root> # Following entry enables directory read/write for mentioned location <Directory <Document_Root>> Dav on Order allow,deny Allow from all </Directory>
4	Set the required environment variables within the virtual host. SetEnv GIT_PROJECT_ROOT <Document_Root> SetEnv GIT_HTTP_EXPORT_ALL 1 # Following entry exports the user-id of the user (one that authenticates to LDAP) SetEnv REMOTE_USER=$REDIRECT_REMOTE_USER
5	Add the Script Alias directive to the virtual host entry. This maps the given URL path to a script. In other words, the script is invoked when the URL path starts with specified path. Also, make sure that the <Git_Core_Path> directory is setup to execute CGI programs. # Maps the URL path "/git/" to the git-http-backend script ScriptAlias /git/ <Git_HTTP_Backend_Path> # Following entry enables execution of CGI scripts in mentioned directory <Directory <Git_Core_Path>> Options +ExecCGI Allow From All </Directory>
6	Enable the (LDAP) authentication in the virtual host entry when the URL path contains “/git/”. The LDAP server URL given below is just an example. Make sure you change the values accordingly. # Following entry provides rules for all the URLs starting with 'git'. # Here the LDAP authentication rules are added. # Refer to http://httpd.apache.org/docs/2.0/en/mod/mod_auth_ldap.html for details. # Optional values are mentioned here AuthLDAPBindDN and AuthLDAPBindPassword # are not needed if your LDAP directory supports anonymous bind for searching entries <LocationMatch "^/git/.*"> Dav on AuthName "GIT Repo" AuthType Basic AuthBasicProvider ldap AuthLDAPURL "ldap://ldapserver:389/ou=people,dc=test,dc=lan?uid" AuthLDAPBindDN "uid=admin,ou=system" #Optional AuthLDAPBindPassword secret #Optional AuthzLDAPAuthoritative off Require valid-user Order allow,deny Allow from all </LocationMatch>
7	Restart the Apache HTTP server. Make sure there are no errors during startup. Once started, when the Git clients requests this server, the user is prompted for credentials, and authenticated with the LDAP server.

Finally, this is how the Apache configuration would look as follows:

    <VirtualHost *:<Port_Number>>      DocumentRoot <Document_Root>        # Following entry enables directory read/write for mentioned location      <Directory <Document_Root>>        Dav on        Order allow,deny        Allow from all      </Directory>        SetEnv GIT_PROJECT_ROOT <Document_Root>      SetEnv GIT_HTTP_EXPORT_ALL 1        # Following entry exports the user-id of the user (one that authenticates to LDAP)      SetEnv REMOTE_USER=$REDIRECT_REMOTE_USER        # Maps the URL path "/git/" to the git-http-backend script      ScriptAlias /git/ <Git_HTTP_Backend_Path>        # Following entry enables execution of CGI scripts in mentioned directory      <Directory <Git_Core_Path>>        Options +ExecCGI        Allow From All      </Directory>        # Following entry provides rules for all the URLs starting with 'git'.      # Here the LDAP authentication rules are added.      # Refer to http://httpd.apache.org/docs/2.0/en/mod/mod_auth_ldap.html for details.      # Optional values are mentioned here AuthLDAPBindDN and AuthLDAPBindPassword      # are not needed if your LDAP directory supports anonymous bind for searching entries      <LocationMatch "^/git/.*">        Dav on        AuthName "GIT Repo"        AuthType Basic        AuthBasicProvider ldap        AuthLDAPURL "ldap://ldapserver:389/ou=people,dc=test,dc=lan?uid"        AuthLDAPBindDN "uid=admin,ou=system"    #Optional        AuthLDAPBindPassword secret             #Optional        AuthzLDAPAuthoritative off               Require valid-user        Order allow,deny        Allow from all      </LocationMatch>    </VirtualHost>      Listen <Port_Number>

Additional Setup Steps to enable Process Governance for Repository access feature of Rational Team Concert 5.0.2

Step	Actions	Result
8	Replace the Script Alias directive in the virtual host entry, which was added in the Step 5 above as follows. For Linux platforms, # Maps the URL path "/git/" to the rtc-git-http-interceptor script ScriptAlias /git/ <RTC_Git_Hooks_Dir>/rtc-git-http-interceptor/ For Microsoft® Windows® platform, there exist a Perl equivalent. Hence, modify the line as follows. # Maps the URL path "/git/" to the rtc-git-http-interceptor script ScriptAlias /git/ <RTC_Git_Hooks_Dir>/rtc-git-http-interceptor.pl/ NOTE: Make sure the interceptor scripts have Execute permissions turned on. Also, within the Perl script, make sure the Perl interpreter (#! line) refers to the Strawberry Perl executable.

Step

Actions

Result

Replace the Script Alias directive in the virtual host entry, which was added in the Step 5 above as follows.
For Linux platforms,

      # Maps the URL path "/git/" to the rtc-git-http-interceptor script      ScriptAlias /git/ <RTC_Git_Hooks_Dir>/rtc-git-http-interceptor/

For Microsoft® Windows® platform, there exist a Perl equivalent. Hence, modify the line as follows.

      # Maps the URL path "/git/" to the rtc-git-http-interceptor script      ScriptAlias /git/ <RTC_Git_Hooks_Dir>/rtc-git-http-interceptor.pl/

NOTE:
Make sure the interceptor scripts have Execute permissions turned on.
Also, within the Perl script, make sure the Perl interpreter (#! line) refers to the Strawberry Perl executable.

Configuring Rational Team Concert for LDAP

Please refer to the documentation on how to setup the Rational Team Concert with LDAP. You might want to see to the video as well.

Configuring Git Repositories

This integration functionality requires Rational Team Concert (server-side) hooks for Git to be deployed and configured for every Git Repository on the server. The following steps describe the procedure in detail:

The Rational Team Concert hooks for Git is not part of the Rational Team Concert server, and has to be downloaded from jazz.net. (See https://jazz.net/downloads/rational-team-concert/releases/5.0?p=allDownloads)
Unzip the hooks into a directory, say "C:RTC_Git_Hooks_5.0"
Copy the pre-receive and post-receive hook scripts in the examples directory under "C:RTC_Git_Hooks_5.0" into the hooks directory of the Git Repository.
It is possible that you already have deployed pre-receive and post-receive hooks, in which case, you will have to copy the contents of the example scripts into the respective script (that is deployed) at an appropriate place.
Open the hook scripts (copied into the Git Repository in the above step) in an editor, and modify as described in C:RTC_Git_Hooks_5.0examplesReadMe.txt

Additional Configuration Steps to enable Process Governance for Repository access feature of Rational Team Concert 5.0.2

Define the following Git configuration parameters for every Git repository on the server. Since, it is required to be defined per-repository, it is better to keep it as a local configuration parameter. Therefore, make sure you run the following commands within the repository’s directory.

rtc.repokey:
git config rtc.repokey 12345678901234567890
rtc.repourl:
git config rtc.repourl https://myrtcserver:9443/ccm

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

3 people rated this as helpful.