Getting Started with Rational Lifecycle Integration Adapter for GIT

I recently had the opportunity to help some of our client technical professionals overseas get familiar with the Rational Lifecycle Integration Adapters (RLIA) – Standard Edition.  This included some install and configuration sessions and some exercises to help them understand the key features.  But, I was missing some information on how to install and configure the GIT Adapter.  It is documented in the RLIA v1.0 infocenter, but sometimes it’s better to see it broken down into some simple steps with notes and then run through it oneself.  So, that’s what I did when I got back to the office.  I just had to see how to get to the point where RTC and GitWeb were integrated.

I’ll take you through what I did to get RTC 4.0.1 and GitWeb integrated such that I could link Git commits with RTC workitems.

Environment

Windows 7 64-bit

CLM 4.0.1 deployed on Tomcat with a Derby database and the Money that Matters sample.

CLM 4.0.1 public URI is set to https://clm.jkebanking.net:9443/jts

GitWeb 1.7.1 running on a Linux VM image

DB2 Workgroup Server Edition, v9.7

Note:

  • Administrator privileges are required to install the adapter.
  • If your CLM 4.0.1 public URI does not contain a port, please contact IBM support to obtain a hotfix for the Rational Adapter for Git that will work in your environment.

Installation and Configuration

The Git adapter needs to be installed into the same location as Jazz Team Server (JTS).  For example, if you want to integrate with a specific instance of the RTC 4.0.1 application, you need to figure out what JTS that RTC 4.0.1 application is registered with.

I started by running the Interactive Installation guide located here:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/roadmapgit_form.html

  1. Create a DB2 database using the instructions here:  http://pic.dhe.ibm.com/infocenter/clmhelp/v4r0/topic/com.ibm.jazz.install.doc/topics/t_s_server_installation_setup_db2.html
  2. Stop the CLM 4.0.1 server.
  3. Locate the Rational Lifecycle Integration GIT Adapter install directory, GIT\disk1, of the installation media.  Run launchpad.exe to install the adapter into the same application server instance as the JTS.
  4. After adapter install completes, start the CLM 4.0.1 server.

What we have done so far is (1) installed the adapter to the same application server as the Jazz Team Server, and (2) set up the database to use with the adapter.  Now, we want to register the Rational Adapter for Git application with the JTS.  This part is pretty straightforward if you have configured CLM before.  Here’s a link that covers this next step:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_register_git.html

When I ran through this part, I got a message during Step 7 regarding having to upgrade the data warehouse. I skipped this step by selecting the checkbox, ‘I do not want to configure a data warehouse at this time’.  Development said it was ok to do this and that this was not the expected behavior. It should have just worked.  In Step 5, I also let it create a default functional user, gitAdapter_user.

After the adapter application is registered, we can proceed to configure linking between the RTC application and the Rational Adapter for Git.

The next part consists of the following areas:

  • Establishing cross-server communication
  • Approving the access request
  • Deploying the Gitweb additions
  • Registering the Gitweb server
  • Registering the Gitweb project

Establishing cross-server communication

This part is pretty straightforward. It involves establishing a friend relationship between the Rational Adapter for Git and RTC.

  1. Follow the process described in this topic:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_servertoserverestablish_gittojazz.html  HINT: Use a meaningful name for the friend relationship so that you can identify it easily later on in this process.  I used this name: GIT clm.jkebanking.net
  2. Open the JTS Admin page in a browser.
    1. Create a user called ‘githook’.
    2. Apply a RTC Contributor Client Access License (CAL).
    3. Add this user as a member of the RTC projects that you want to integrate with Git using this adapter.

Approving an access request

This part can be automatic if you are logged in as a CLM Administrator like I was.  You get the option to grant provisional access.  However, there is a part that is not quite documented well and is mentioned in passing in Step 7.  It discusses a functional user ID that needs user privileges to update workitems and permissions in the RTC project area that will be used by this integration. But, it is the first time this is mentioned.  That is the reason I had you create a user, ‘githook’ in the previous section.

http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_approve_consumer_keys_git.html

  1. Open the CCM Admin page in a browser, for example, using a URL such as :  https://clm.jkebanking.net:9443/ccm/admin using an account with administrator privileges.
  2. Navigate to the Consumers (Inbound) page.
  3. Locate the consumer relationship in the Authorized Keys section.
  4. Follow steps 6 and 7 of the infocenter topic listed above to add the githook user to this consumer key.  Note: There is no functional user associated with this inbound consumer. This is where we want to add the ‘githook’ user we created earlier.

Deploying GitWeb additions

This part is done where GitWeb is installed.  The GitWeb additions add a banner to the GitWeb interface that supports: (1) the creation of links between commits and RTC workitems, (2) traversal of existing links and (3) rich hover support of existing links.

http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_deploy_gitweb_additions_git.html

  1. Follow the instructions in the topic above.
  2. In Step 4, follow the suggestion to copy/paste the contents of gitweb.conf.README to the gitweb.conf file for your installation.

Once this section is complete, you should see the following banner when opening GitWeb.

Image

Registering the Gitweb server

Now that we have the Rational Adapter for Git banner installed, we will use it to register the Gitweb server with the adapter.  This step will allow to the Gitweb server to be recognized by Gitweb objects.

Follow the steps in this topic:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/index.jsp?topic=%2Fcom.ibm.rational.rlia.git.install.doc%2Ftopics%2Ft_deploy_gitweb_additions_git.html

Make sure to follow Step 6 which further updates the ./static/oslcConfig.js file.

Registering the Gitweb project

We can now finish the configuration by registering one or more Git projects with the Rational Adapter for Git.

Follow the steps in this topic:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_register_git_project_git.html

Take a note of Step 8.  If you want to configure the ‘commit hook’ piece of the integration, you will need to record the Gitweb project URI.  You can retrieve this Gitweb project URI at a later time however by going to the Git Adapter Appication Administration page (https://<publicURI>/gitAdapter/admin) and selecting the Git Server connection entry ID hyperlink.

Image

Image

Validate the Gitweb integration

Once the above steps are complete, we can validate the Gitweb integration by following the usage in this topic:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.doc/topics/c_git_use_gitweb_ovw.html

Conclusion

We have now completed one part of the Rational Adapter for Git installation and configuration.  With this integration, we can link existing commits to either existing Rational Team Concert change requests or new change requests.  There is another integration that is supported by the Rational Adapter for Git.  It uses the Git command line to create links between a Git commit and a change request in RTC via the command line.  I will be looking at this next.  If there is anything tricky, I will create another blog post.  In the meanwhile, you can access the deploy instructions in this topic:  http://pic.dhe.ibm.com/infocenter/rliahelp/v1/topic/com.ibm.rational.rlia.git.install.doc/topics/t_deploy_git_receive_hook_git.html