Integrating Rational Team Concert 5.0 with GIT
This page describes a usage or software configuration that may not be supported by IBM. Git is a distributed version control system with an emphasis on speed, data integrity, and support for distributed, non-linear workflows. Git was initially designed and developed by Linus Torvalds for the Linux kernel developed in 2005. It has since become the most widely adopted version control system for software development. Dedicated Git server software helps to add access control and display the contents of a Git repository via the web. It is also used in managing multiple repositories. Git also puts an emphasis on speed, data integrity, and support for distributed, non-linear workflows. A Git repository can be cloned to a shared file system and accessed by other users. It can also be accessed via remote shell if the Git software is installed and the user is logged in.
As with most other distributed version control systems, and unlike most client-server systems, every Git working directory is a full-fledged repository with complete history and full version-tracking capabilities, independent of network access or a central server. Like the Linux kernel, Git is free software distributed under the terms of the GNU General Public License version 2.
The IBM Rational Adapter for Git integrates Git or Gerrit with work items created in Rational Team Concert (RTC). Git developers can work as usual when utilizing this integration, but will also be able to annotate their commit messages with comments, such as “bug 1234” or “bug: 1234”. That way, when they push to a configured shared repository, a link to the work item is created. A commit or change can reference more than one work item, and the same work item can be referenced in multiple commits or changes.
Links are visible in Rational Team Concert as well as in Gitweb or Gerrit. Links can be followed in either direction and can be deleted from the RTC work item. In addition, links can be added between commits to new or existing work items from Gitweb or between changes to new or existing work items from Gerrit.
Network topology and user authentication
A Git server is expected to be part of the Project hosting environment, rather than AMT hosting. This means, GIT and RTC may be pointing to different user directories, with the only restriction being that the IDs of the users who are using this GIT/RTC integration should be same across these user directories. The reason for these IDs being the same is that the Push/Pull operations on the Git repository basically make use of the user ID for executing RTC’s process enforcements and other integration activities.
Linking a Git change to a work item from the eGit client
A Rational Team Concert work item and a Git Commit from eGit can be linked.
Note: Git repositories must be registered and configured on the RTC server. You may associate one or more Git repositories with an RTC project area.
From the eGit client, links between Git changes and existing RTC work items can be created. Git changes can be linked to multiple work items and a work item can be linked to multiple Git changes.
Checkout the files from eGit Client
If the user wants to update/add any files in to Git repository, eGit may be used. eGit is an Eclipse Client tool that allows you to update and add any files into a Git repository.
How to register and integrate a Git repository with RTC 5.0
As part of the registration process, information pertaining to the Git repository (on the server) is captured and persisted within Rational Team Concert. Once registered, a unique key is generated for the Git repository. This key helps the Rational Team Concert identify the Git repository (when there is an incoming request from the hooks) with which the user is working on, and therefore, retrieves the corresponding process area for process enforcement.
Follow these steps to register and set up the integration:
- Login into RTC PA https://<servername.accenture.com>/ccm/web using your credentials.
- Click on Source control > Work with Git.
- Click on Register a Git repository.
- Enter a name for the repository connect, along with the necessary details into their respective fields (URL, Owner, and Description). Click Save:
- After you’ve saved, a key should be generated.
- Copy this key and save it to a file somewhere on your local machine. This key will be used to communicate with Git administrator as the same key would be configured into Hooks. It is important for recognizing the RTC PA when changes are associated with RTC work item type.
Note: One RTC PA can be associated with any number of Git repositories, but only one Git repository can be mapped with only one RTC PA. - Incoming requests from Git require authorization. Click on Grant Access to allow the access. This step is user specific and should be performed by each end user.
For example, for a user named John to integrate his Git changes with RTC work items, he has to log into RTC and specifically authorize his Git requests. After doing this, he would be able to map his Git changes with RTC work items.
Note: The Git server-side hooks interact with the Rational Team Concert server by invoking its services. The authorization process ensures that these requests are honored by Rational Team Concert server.
How to configure Hooks on Git server
Note: This section needs to be performed by the Git administrator.
Rational Team Concert (server-side) hooks for Git are deployed and configured in the Git repositories on the Git server. Hooks are not part of Rational Team Concert downloads and hence, have to be downloaded from jazz.net.You must have Python 3.3.5 installed.
To complete the configuration of the Hooks on the Git server, we need to deploy two hooks on each Git repository as mentioned below:
- Leverage the pre-receive hook (a.k.a. ‘validation hook’) to enforce process for push operation by invoking the services of Rational Team Concert.
- Leverage the post-receive hook (a.k.a. ‘association hook’) to perform Commit and work item linking, again by invoking the services of Rational Team Concert.
Process governance for push command
Note: This section is performed by the CLM project administrator.
It must be noted that the RTC-Git integration enforces who can execute specific push operation(s) into the Git repository. This permission, which is associated with specific set of roles, allows the execution of various push operations configured within the RTC project area as shown below. If you are not part of the role that has this permission, you will not be able to execute the push operation.
For this reason, a project may require creating a support ticket to enable the required permissions in RTC.
Execution of CLM-Git Integration use case
- Run eclipse.exe and create Git workspace on local system.
- By default, the perspective is Java, change it to Git Repository Exploring.
- Open Perspective > Other.
- Select Git Repository Exploring and click OK.
- Click on Clone a Git Repository shown on left side panel in Git repository.
- Provide inputs as detailed below on Clone Git Repository window.
Note: Below details is different per engagement. Contact your Git administrator for more details.
- URI: Enter Gerrit server repository
- Host: Git server name
- Repository Path: Entered Repository path
Note: Host & Repository Path will get auto populated once user will provide the URI
- Protocol: select default http
- Provide username and password
- Click Next.
- Choose the branches that you want to clone/reference in your local Git repository.
- Select the Master branches as your initial branch and Click Finish to initiate the clone.
- Enter Initial branch then Click Finish.
Note: Branch name is case sensitive.
- Import Git Repository on the local repository in Eclipse.
- Either use ‘Import of existing projects’, if the repository already contains pre-configured projects, or use ‘import as general project’ if that seems appropriate.
- Click Next.
- Provide a project name.
- Click Finish.
- The project is now imported into your local repository. Re-set perspective Java and Add/Edit files into the repository.
- After updating the file, right click on Team > Commit the changes.
- Provide comments.
Note: That the comment contains “task 129” which means that this specific change set will be linked to RTC work item 129.
You may link as many RTC work items as you feel appropriate by adding the IDs of that many no. of work items (defect, bug etc.) in the commit message.
- Click on Commit button to push the changes at the project level.
- Push the changes into Git repository. Right-click on the Git Repository > Push.
- Keep the default “Configured Remote Repository” selected and verify your Git repository is selected
- Click Next.
- Add Source ref from drop-down.
- Click on Add Spec. Click Next.
- Click on Finish.
- Click OK.
- To verify that the changes have been pushed to the remote repository, you may check if there’s no arrow mark pointing upwards beside the name of the repository (as shown in the below UI). If you still find an arrow mark pointing upwards that implies your changes weren’t pushed successfully to the remote repository.
Verification Steps
How to verify, whether Git changes have been successfully integrated with the RTC work item.
- Login into your RTC PA
- Search work item that you have used in the comments while committing changes in Git.
- Click on Links Tab and verify Change Sets. If you get same Git comments under RTC change set, it means Use Case was successfully executed.
- Git comments should be added into the RTC change set.
- Click on the change set, and you should see all details of the Git repository.
Unregistering a Git repository
Note: This section is performed by the CLM Project Administrator.
Unregistering a Git repository with Rational Team Concert removes the related Git repository information from Rational Team Concert database. Consequently, the association with the process area is also removed. Due to this fact, you may need to create a support ticket within your organization to unregistration a Git repository from RTC server.
Resources
Copyright © 2015 Accenture