Setting up Rational Team Concert Git integration using Apache Smart HTTP Server
Rational Team Concert Development Team
Last updated: April 28, 2017
Build basis: Rational Team Concert 6.0.3
Rational Team Concert (RTC) 6.0.3 release provides the following integration points with Git:
- Process governance for Git operations.
- Linking Git commits to work items in Rational Team Concert.
RTC server uses the Change and Configuration Management (CCM) application to provide features. This article describes the setup that is required for this integration.
Table of Contents
Setup
Prerequisites
You downloaded and installed the following software:
- Git. (http://git-scm.com/download)
- Apache Smart HTTP Server (https://httpd.apache.org/download.cgi)
- LDAP Server. For an example, see https://directory.apache.org/.
Note: Setting up an LDAP server for authentication is beyond the scope of this article. We assume that the server is set up. - Python 3.3.5 (https://www.python.org/download/releases/3.3.5)
- RTC Git Integration Toolkit zip (https://jazz.net/downloads/rational-team-concert/releases/6.0.3?p=allDownloads)
Context
The figure below 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 in the figure above, it is hosted by Apache HTTP server. To perform process enforcement for Git operations by Rational Team Concert, the identity of the Git user must be known to Rational Team Concert. Therefore, you must have a common user base across Rational Team Concert and Git server (Apache HTTP server) through 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 by invoking the services of Rational Team Concert.
Setting up the Git repositories
- Select a path to create the Git repositories. For this example, use
c:/gitrepos
. - Navigate to the folder
c:/gitrepos
. - Create a new Git repository called
MyDemo
:- Create a directory with the name
MyDemo.git
underc:/gitrepos
. - Navigate to the directory
c:/gitrepos/MyDemo.git
and run the commandgit init --bare
C:\gitrepos>mkdir MyDemo.git C:\gitrepos>cd MyDemo.git C:\gitrepos\MyDemo.git>git init --bare Initialized empty Git repository in C:/gitrepos/MyDemo.git/ C:\gitrepos\MyDemo.git>dir HEAD config description hooks info objects refs C:\gitrepos\MyDemo.git>
- Create a directory with the name
Setting up the Apache Smart HTTP Server
To setup the Apache Smart HTTP Server follow the instruction provided at https://httpd.apache.org/docs/2.4/install.html
Server-side configurations
Configuring Apache Smart HTTP Server
Use the following place-holder names as examples to identify the respective items:
- <Apache_Install_Dir> to specify the location where Apache is installed, such as
C:\Program Files (x86)\Apache Software Foundation\Apache2.2
on Microsoft® Windows®. - <Document_Root> to specify the root directory on the server where the documents are fetched.
- <Port_Number> to specify the port number on which the server listens for requests. For example, 8113.
- <Git_HTTP_Backend_Path> to specify 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 specify the directory where Git core binaries are stored. For example,
C:/Program Files (x86)/Git/libexec/git-core/
on Microsoft® Windows®.
- Open the Apache configuration directory
<Apache_Install_Dir>/conf
. - Create a file
git.conf
and add the content that is provided below. Replace appropriate values for value-holders.#Port number on which the server listens for requests Listen 8888; #Web DAV modules 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 cgi_module modules/mod_cgi.so LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule ldap_module modules/mod_ldap.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so <VirtualHost *:8888> # The location of git repositories root directory (ex: D:/gitrepo) DocumentRoot <Document_Root> 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 # For debug logs SetEnv DEBUG_PYT false # Maps the URL path "\git\" to rtc hooks to enable rtc features ScriptAlias "/git" "<RTC_Hooks_Directory>\rtc-git-http-interceptor.pl" # Following entry enables execution of CGI scripts in mentioned directory #Git 1.9.5 <Directory "C:/Program File/Git/mingw64/libexec/git-core"> Options +ExecCGI Allow From All </Directory> #Following entry enables execution permission to rtc hooks (ex: D:\toolkit\hooks.py) <Directory <RTC_Hooks_Directory>> Options +ExecCGI Allow from all </Directory> # Following entry enables directory read\write for mentioned location <Directory <Document_Root>> DAV On Order allow,deny 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" AuthType Basic AuthBasicProvider ldap AuthLDAPURL "ldap://localhost:389/ou=people,dc=maxcrc,dc=com?uid" AuthzLDAPAuthoritative off Require valid-user Order allow,deny Allow from all </LocationMatch> </VirtualHost>
- Include git.conf in
<apache-install-dir>/conf/httpd.conf
.#Include the git configuration file Include git.conf
- Restart the Apache HTTP server. Ensure that there are no errors during startup.
With this setup, when performing any Git operation from the client, the user is prompted for credentials and authenticated with the LDAP server. For more information about how to set up Rational Team Concert with LDAP view this video.
Configuring RTC Git interceptor
To enable RTC features, configure values for attributes in /rtc-git-http-interceptor.pl
. For Linux versions, use the /rtc-git-http-interceptor
shell script that is provided.
PYTHON_PATH=C:/python33/python RTC_SCRIPTS_PATH= <RTC_Git_Hooks_Dir> GIT_HTTP_BACKEND_PATH="<Git-install-dir>/libexec/git-core/git-httpbackend.exe LIBGIT2_PATH="<LIBGIT2_DIR>/build/git2.dll"
Configuring the RTC server
- Log in to the RTC server
https://everest:9663/ccm
by using a web browser. In this example use the login clm, which has administrator permissions and a developer license assigned to it. - Create a new project area with the name GitProjects and apply the SCRUM template to it.
- Create a user named gituser and assign the user a contributor license. Add the user to the project area with the role Team Member.
- Go to the Permissions page of the project area and grant everyone access to all Git-related permissions. This action is for simplicity. After the integration is set up, you can change the permissions according to your requirements.
Git Permissions page:
- Authorise the Git requests by using the administrator user clm. Log in to the RTC server
https://everest:9663/ccm
and open the project area GitProjects. Under the source control menu, click Git Requests. - In the Authorize Incoming Git requests dialog, click Yes.
Registering a Git repository in RTC
- Register the Git repository, so that the RTC server can start managing it. Using the administator user clm, log in to the RTC server
https://everest:9663/ccm
and open the project area GitProjects. - Click Registered Git Repositories under the Source Control menu.
- After the Browse Registered Git Repositories page opens, click the Register Git Repository button in the top-right corner. A blank editor opens.
- On this page, add the details for the Git repository URL and the process area. The values are shown below.
- Click Save, which saves the registry information and generates a unique key. Note the key value, which is used for configuring the Git side of the integration.
- To display the Git commit details, RTC needs to access the Git repository. On the Git repository page, go to Git Server Authentication Details and provide user authentication information.
Configuring the Git repository
Configure the git repositoryMyDemo.git
to link to the RTC server https://everest:9663/ccm.
- Navigate to the Git repository folder. In this example, the path is
c:\gitrepos\MyDemo.git
. - Open the file
config
c:\gitrepos\MyDemo.git>ls HEAD config description hooks info objects refs
- In the config file, add RTC-specific parameters. These parameters provide details about the RTC server and the Git repository item that you created earlier. These two configuration variables are added under the
rtc
section, as shown below:[rtc] repourl = https://everest:9663/ccm repokey = 9f35952a70224411859a29f10cead2e3
Note: The value of therepokey
is the one generated by RTC when the Git repository mapping was created.
The final contents of the config file look something like the following:
[core] repositoryformatversion = 0 filemode = false bare = true symlinks = false ignorecase = true hideDotFiles = dotGitOnly [rtc] repourl = https://everest:9663/ccm repokey = 9f35952a70224411859a29f10cead2e3
Configuring the hooks
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:
- Extract the hooks form RTC Git Integration Toolkit zip into a directory, such as
C:\GIT_Server_Toolkit_6.0.3\hooks.py\examples
. - Copy the pre-receive and post-receive hook scripts in the examples directory under
C:\GIT_Server_Toolkit_6.0.3\hooks.py\examples
into the hooks directory of the Git Repository.
If you already deployed pre-receive and post-receive hooks, copy the contents of the example scripts into the respective script (that is deployed) at an appropriate location. - Open the hook scripts (copied into the Git Repository in step 3) into an editor and update values for pythonPath, hooksPath.
# pythonPath # Absolute path to python 3.3.5 executable pythonPath="C:\bin\python3.3" # hooksPath # Absolute path of the directory where RTC Git hooks are stored hooksPath="C:\GIT_Server_Toolkit_6.0.3\hooks.py"
- On Unix systems, ensure that the copied files have executable permissions.
Testing the integration
For testing and using the integration, use a client machine to connect to the Git repository and execute Git operations. This machine must access the machine that is running the RTC server and the Apache server.Initial checklist:
- For testing purposes, use the user gituser. This user has the required permissions in RTC to create and save work items, and read and write into Git repositories.
- A sample work item
54: Test Git Integration
is used. Log in to RTC and create a work item in the project area GitProjects. - On the client machine, ensure that Git is installed.
Smoke testing the integration:
- From the client machine, clone the Git repository by executing the Git command
git clone http://ceres:8888/git/MyDemo.git
, whereceres
is the name of the machine that is running the apache server.workspace:git kk$ git clone http://ceres:8888/git/MyDemo.git Cloning into 'MyDemo'... Username for 'http://ceres:8888': gituser Password for 'http://gituser@ceres:8888': warning: You appear to have cloned an empty repository. Checking connectivity... done.
Note: If this command succeeds, the folder MyDemo is created on your machine. This folder is the clone of the Git repository that you created earlier. - Create a new file in the local Git repository. Add the file to a new commit, link it with an RTC work item, and push the commit to the remote Git repository.
workspace:MyDemo kk$ echo test >> foo.txt workspace:MyDemo kk$ git add foo.txt krishna s-mbp:MyDemo kk$ git commit -a -m "for task 54" [master (root-commit) 3aaf683] for task 54 1 file changed, 1 insertion(+) create mode 100644 foo.txt workspace:MyDemo kk$ git push origin master Username for 'http://ceres:8888': gituser Password for 'http://gituser@ceres:8888': Counting objects: 3, done. Writing objects: 100% (3/3), 210 bytes | 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) To http://ceres:8888/git/MyDemo.git * [new branch] master -> master workspace:MyDemo kk$
A new filefoo.txt
is added to the Git repository and pushed to the remote Git repository. You also linked the commit to the RTC work item that has the id 54. - Verify that the commit has been pushed to the remote Git repository by cloning the same repository at a different location. The cloned repository has
foo.txt
. - Verify that the work item linking works. Open the work item (provided in the commit comment) in a web browser. Under the Links tab, you can see a link of type
remote change sets.
- Hover over the link to display a pop-up with Git commit information. Click the link to open a page with commit details.
Copyright © – 2017 IBM Corporation