Git Integration features in Rational Team Concert
Rational Team Concert is a team collaboration tool offering source control, builds, tracking and planning capabilities, and integration and traceability across these capabilities.
Where does Git fit in here? In the RTC 5.x timeframe, some of our customers indicated that there were pockets of Git usage in their companies – and they wanted to know if there was a way we could work with Git as an alternative SCM in RTC. Just like Rational Team Concert’s source control integrates with other capabilities, one can imagine similar integration points between Git and Rational Team Concert (like linking Git commits with work items, for example).Through follow-up discussions, we came up with the following use cases as the highest priority ones.
- Linking and traceability between Git commits and RTC work items
- Process Governance
Table of Contents
- Context
- Registering a Git Repository with Rational Team Concert
- Ref Mapping
- Process Governance for push command
- Linking Git Commits with work items
- Authorizating Git Requets
Context
The picture above captures the overall context of this integration. In essence:
- Rational Team Concert Server does NOT host the Git Repositories; they are to be hosted by Apache HTTP Smart Server
- A common user base between Rational Team Concert and Git, authenticated by a common LDAP server
- Rational Team Concert (server-side) hooks for Git is deployed and configured in the Git Repositories on the server. (Hooks are not part of Rational Team Concert downloads, they are to be downloaded from jazz.net downloads page separately)
- 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.
- Please note that the integration is with the Git Repository on the server (to which many users are pushing their changes to), and NOT the local Git Repositories cloned into their local file-system.
Registering a Git Repository with Rational Team Concert
In the world of Rational Team Concert, the process enforcement is effected by the process runtime as defined in process specification of the given process area (project area or team area). As an example, the Deliver operation to a stream is controlled by the permissions defined in the process area associated with the stream.
As noted above, Rational Team Concert server does NOT host Git Repositories. Therefore, to enable features like process enforcement for Push operation etc, we need to create an association between the Git Repository and a process area in Rational Team Concert. This ‘ritual’ is what is referred to as Registering the Git Repository with Rational Team Concert. In other words, without registering a Git Repository with Rational Team Concert, it is not possible to leverage the Git Integration features that Rational Team Concert has to offer.
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, retrieve the corresponding process area for process enforcement.
Help: For detailed steps, please refer to Registering Git Repositories
Unregistering a Git Repository
Unregistering a Git Repository with Rational Team Concert removes the Git Repository related information from Rational Team Concert database. Consequently, the association with the process area is also removed.
Ref Mapping
Sometimes, it is desirable to have branch-specific permissions – say, for example, only Deployment Engineers (identified by ‘Deployment Engineer’ role) are allowed to push to ‘master’ branch, while developers (identified by ‘Developer’ role) are allowed only to push to ‘dev’.
Rational Team Concert also allows for branch-specific process enforcement. This can be achieved by creating a Git Ref Mapping in Rational Team Concert within an already registered Git Repository. Like registering, this operation associates a process area to a Git Reference (like branches). In order to realize the above-mentioned use-case, one can create 2 Ref Mappings – one for ‘refs/heads/master’ branch, and other for ‘refs/heads/dev’ branch, where in the roles ‘Deployment Engineer’ and ‘Developer’ roles have the permission to push commits, respectively.
Caveat: The process area mapped to a Git Ref should be the child of the process area associated with the corresponding Git Repository while Registering. This enables process customization (or overriding) at branch level.
Wildcard Support
It is perfectly valid to use wildcards in the Ref names while creating the Ref Mapping. Defining such a mapping enables same process to be enforced for a similar group of branches. For example, a mapping with the Ref Name ‘refs/heads/feature*’ enforces same process for all feature branches (‘refs/heads/feature1’, ‘refs/heads/featureX’).
Help: For detailed steps, please refer to Creating a Ref Mapping
Process Governance for push command
Permissions
In Rational Team Concert’s role-based process governance, permissions (conferred to a role in a process area) determines whether an action is allowed for that role or not. Rational Team Concert allows these permissions to be customized (overridden) inside a child process area.
For the Git’s push operation, we have added the following permissions:
- ‘Create Branch’: Governs permission to create new branches in the remote Git Repository on the server via the push command
- ‘Delete Branch’: Governs permission to delete branches in the remote Git repository on the server via the push command.
- ‘Create Tag’: Governs permission to create new tags in the remote Git Repository via the push command
- ‘Delete Tag’: Governs permission to delete tags in the remote Git Repository via the push command
- ‘Push New Commits’: Governs permission to push new commits to a branch (fast-forward update)
- ‘Delete Commits’: Governs permission to alter history by push command (by modifying already delivered commits, or rewinding the reference to older commit etc). Recommended NOT to allow this to all roles.
NOTE: Registering and Unregistering a Git Repository with Rational Team Concert is also governed by permissions (as can be seen in the picture above), as defined in the selected process area.
Pre Conditions
As the name suggests, the Rational Team Concert allows pre-conditions to be applied for a certain operation. The pre-conditions are operation-specific. The pre-conditions that are applied for a given operation are executed by the process runtime before the operation itself. The operation is executed only none of the applied pre-conditions fail; else, the operation fails.
While permissions offer a boolean type of validation (allow or deny), pre-conditions can provide more choice. For Git’s push operation, two new pre-conditions have been added.
- ‘Push Own Commits’: Allows push operation to go through only if the committer name matches with that of the logged in user running the push operation. In other words, user is allowed to push commits created by him, not others.
- ‘Require work item hint in Commit Comment’: Allows push operation to go through only if the commits mention work item numbers in the comment.
Usage:Refer to the product documentation page for pattern and syntax for specifying work item numbers in commit comments.
Help: For detailed steps, please refer to Defining Git-related permissions and preconditions
Process Area Selection Logic
When the user performs a push operation, s/he is usually modifying branches (or References). Rational Team Concert has to make sure that it enforces the intended process specification, by selecting the appropriate Ref mapping, and picking the associated process area – i.e., if a Ref mapping for the branch ‘refs/heads/master’ is created by associating it to the process area ‘P1’, then for pushing commits onto this branch, Rational Team Concert’s process runtime would use the process area ‘P1’ for process enforcement.
As mentioned above, the wildcard characters can also be used for Ref names while creating Ref mappings. As a generic thumbrule, an exact match takes precedence over wildcard candidates. Therefore, if there exist two Ref mappings — say, ‘refs/heads/feature?’ and ‘refs/heads/feature1’, then for push operation (pushing commits) onto ‘refs/heads/feature1’ branch, the latter mapping is considered.
Similarly, suppose there exists two Ref mappings ‘refs/heads/*/feature1’ and ‘refs/heads/dev/feature*’, then for push operation (pushing commits) onto ‘refs/heads/dev/feature1’ branch, the latter mapping is considered, as ‘dev’ is an exact match compared to ‘*’, and hence takes precedence.
For push operations on branches that do not have a Ref mapping, the behavior depends on the setting defined in the Git Repository Editor (see picture below). If this setting is enabled (default), the process area associated with the Git Repository is selected. On the other hand, if this is disabled, no process is enforced – i.e., the push operation is allowed to pass through.
Linking Git Commits with Work Items
To allow traceability between work items and Git Commits, Rational Team Concert allows them to be linked (similar to how work items can be linked to a change set). This linking is performed by the post-receive hook in the Git Repository on the server.
The work item to be linked to can be mentioned in the commit’s comment (for example, see the picture below). A Git commit can be linked to multiple work items.
Once link is created successfully, the work item has the link to the Git Commit. And, the Commit information can be viewed from the work item UI in Rational Team Concert.
The link between Git commit and work items can be removed or modified (link a commit to another work item).
Help: For detailed steps, please refer to Associating work items with Git commits, Removing associated work items, Modifying associated work items
Authorizing Git Requests
What is Authorization?
As is evident from the setup above, the Git server-side hooks interact with the Rational Team Concert server by invoking its services. The Authorization process ensures that these requests are honoured by Rational Team Concert server.
Why is it required?
These services are required to be executed in the context of an authenticated user so that the appropriate roles and permissions apply. Which means that the user has to login to avail these services. A straight-forward (and naive) way to do this is to store the user credentials somewhere on the Git server-side, and use them to login while invoking Rational Team Concert services. For obvious (security) reasons, this is not practical.
Another alternative is to have a functional user, in whose context, the services are invoked. However, that does not ensure that the right roles and permissions are applied.
Therefore, Rational Team Concert requires the user to explicitly authorize these incoming requests. The user can revoke this access anytime, of course.
NOTE: For the first time (after server restart) a user with JazzAdmin privileges should perform Authorization. During the process, he might choose to authorize all users or only himself.
Help: For detailed steps, please refer to Authorizing Git Requests
About the author
Kiran M N is a member of the Rational Team Concert Development organization, and has been part of the Git Integration team since its inception.
Copyright © 2014 – IBM Corporation