ibm rational team concert integration with git source control

© 2016 IBM Corporation1

RTC-Git Integration Team

Rational Team Concert Integration with Git


Outline Why Git? The Rational Team Concert (RTC) value proposition Setting up the Git integration Using Git with RTC Git and Jenkins Git flavors supported Backup: supporting GitHub and GitLab


Outline Why Git?

About Git

The Rational Team Concert (RTC) value proposition Setting up the Git integration Using Git with RTC Git and Jenkins Git flavors supported Backup: supporting GitHub and GitLab


And of course there’s GitOpen source version control toolSmall, fast, lightweight, easy to installDifferent kind of version control: “Distributed version control” (DVCS) as opposed to Centralized (CVCS)

Each user has a complete standalone copy of the repository

Changes can be pushed and pulled between different repositories

No centralized server and no controls over who can make changes… that’s all controlled by a team’s working methodology they put in place (or by a vendor’s implementation of Git)


And of course … (cont’d)Basic Git is pretty much just bare bones SCM

Command line only, no graphical interface

No authentication – user ID is stored in a file on the user’s desktop and can change any time

There are many open source extensions and an active open source community enhancing Git

Multiple vendors are building solutions on top of Git


Is Git for everyone? It depends on “which Git”

Hosted Git offerings from different vendors provide different feature sets and workflows

Free Git is not much more than basic version control – no authentication, no workflow• A team needs to set up their own process and controls

Most Git offerings are focused on simpler workflows Git (especially hosted) is a great fit for small teams, quick start projects,

open source projects, “born on the web” projects…

Free or cheap

No startup cost


Is Git for everyone? Companies or markets where Git cannot solve their needs

Complex development

Highly regulated development: governance, traceability

May not be a fit for a company who is worried about protecting IP or needs to prove compliance, or needs to be able to contain data spills


RTC integration with Git

RTC Tracking and Planning integrates with basic Git, GitHub, and GitLab RTC process can work with Git and GitLab


Why did we do this integration? For some enterprise teams, multiple SCM is a reality

• Native mobile application development using Xcode IDE

• Open Source Development Projects (Android / OS)

Incremental Adoption for teams new to RTC

• Corporate acquisitions

• New Customers

• How do I bring existing Git teams on board RTC faster?


Why would you care? How do I plan, track and report status for Git projects?

Traceability

How do I manage permissions on Git operations?

Governance

Can I have different teams using different source control systems but a common plan and process?

Multiple SCM


Use Cases As a Git/RTC user, I want to use Git as an alternative SCM from within RTC.

I want my Git commits linked with the RTC work items assigned to me

• Following a plan

I want to view my commits from RTC work items

I want to navigate to my commits to quickly fix defects

I want to resolve my tasks quickly and easily, right from Git

As a Git/Jenkins/RTC user, I want traceability from a Jenkins build to the

RTC work items that were resolved in the build


Use Cases As an IT administrator/ project lead, I need governance for my Git teams.

I want Git operations to be governed by a well-defined automated process

I want role based, controlled access to Git repository, Git repository branches

I want to be able to report project status across my teams irrespective of the SCM

being used

As a manager, I need to adopt agile processes across my teams

DevOps and SAFe across the enterprise of Git users

Common reporting, auditing, plans, flexible process


Setting up the Git integration The next few charts describe how to set up the Git integration for a

barebones Git repository

Set up the Node.js server that’s going to serve up your repositories

Set up RTC (process, permissions)

Register a Git repository

Configure the Git repository to work with RTC

Instruction for setup when you’re using GitLab or GitHub, can be found at https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/c_integ_git.html&scope=null

https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/c_integ_git.html&scope=null

https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/c_integ_git.html&scope=null


RTC setup

16

Authentication Server

Node.js serverAuthentication

(HTTPS)

Permission, process

RTC ServerGit Repository


Adding Git: registration

17

RTC Server

Node.js server

(HTTPS)

Registration

Git Repository

Registration (Project Area, Team Area)



Adding Git: process configuration

18

RTC Server

Node.js server

(HTTPS)

Process Configuration (Project Area/Team Area

Git Repository

Process and permissions



Adding Git: authorization

19


RTC Server

Node.js serverAuthentication Authentication

(HTTPS)

Off-cycle Authorization

Git Repository


Git operations

20


Node.js serverAuthentication Authentication

(HTTPS) (HTTP/HTTPS/ SSH)

Retrieve Commit details (Registered Functional ID)

Work item->commit Clone, Push(link with work item), Pull

RTC Server

Intercept

Git Repository

Process and Permissions (Authorized RTC users)


Setting up the RTC-Git integration Download the “RTC Git Integration Toolkit” from the “All Downloads” tab of

RTC downloads, on jazz.net. This contains

The node server and configuration files

Sample hooks for the Git repository

Instructions for setting up a Node server for the RTC Git integration are provided at https://jazz.net/help-dev/clm/topic/com.ibm.team.connector.cq.doc/topics/c_git_node_js.html describes

Alternatively, you could also use an Apache Https server to serve your Git repository. https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/t_git_install.html describes how to do that.

https://jazz.net/help-dev/clm/topic/com.ibm.team.connector.cq.doc/topics/c_git_node_js.html




https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/t_git_install.html

https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/t_git_install.html


Setting up Node Point your web server to where your Git repositories are

The root folder under which you have your remote repositories

Set up authentication for Git users

You could use RTC as your authentication provider

Or you could use a common authentication server that serves both RTC and Git servers.

Start the web server Once you’ve set up the RTC side of the integration, you’d need to come

back and configure Git server-side hooks, using the sample hooks that you downloaded.

These hooks are responsible for connecting to RTC for process and permissions validation, and work item linking.


Config.json


Setting up RTC Choose the Project Area/Team Area with which your Git repository will be

associated Set up Git specific permissions in the Project/Team area (Project

Area/Team Area editor) Set up Git specific process rules in the Project Area/Team Area (Project

Area/Team Area editor)

All Git repositories registered with a Project Area/Team Area will inherit the same set of process rules

Authorize the RTC server to execute process and permission checks for Git (Git landing page)


Setting up permissions

Define roles for Git operations, or use existing roles

Decide who can

Push commits

Clone a Git repository or pull changes

Create/delete branches or tags

…


Setting up operation behavior

Define preconditions around the push operation

Push goes through only if the preconditions are satisfied


Authorizing RTC

For a Git user, how are process and permission checks invoked in RTC?

Authorize Git requests in RTC• For yourself, as a regular user• For all users, as a project

admin

RTC and Git need to have a common authentication server for authorization to work.


Registering a Git repository Registration is associating the Git

repository with an RTC Project Area or Team Area

Repository branches can be associated with children team areas if they need customized process and permissions

The Git repository then inherits the process and permissions defined in the controlling Project Area/Team Area

You can set up user branches to be outside of process governance (more on this later)

Once you register the repository, you will get back a repository key, which you will need to configure the server side hooks


Additional Git repository settings in RTC Once registration is completed, you can edit the registered repository to

enter the functional user details. These credentials will be used when fetching commit details while traversing a commit link from

a work item.

The commit URI format is typically specified if you have your own web server serving up commit details – such as for example in GitHub or Gerrit. (more on that later)


References, user branches Git repository references may be mapped to child Team Areas of the top

level Project Area or Team Area

`You would do this when you need a custom process for the reference

Much of the process could be inherited from the parent repository or branch, but some permissions or operation behavior could be specific to the branch

User branches are special branches that are not governed by team processes

Specific namespace pattern such as refs/heads/users/$user

Only $user can push to the branch, and the push isn’t governed by a process

Other users cannot push to branches in such namespaces


Setting up the remote Git repository Edit the config file to

provide the URI of the RTC repository and the registration key for the repository

Copy over the sample hooks that you downloaded


Getting started with Git Clone the remote repository.

The Git repository is being served by a web server that shares authentication with RTC• Login with your credentials

RTC-Git integration checks the permissions defined for the Git repository in the RTC Project Area or Team Area

Permissions are checked against the role defined in that Project Area or Team Area for the RTC/Git user

If the user’s role does not have permissions, then the read operation errors out

The Git pull operation is similarly controlled by permissions defined in RTC


Sharing your changes Push your commits

You can add a link to an RTC work item by adding the work item number in the commit message like so

The RTC Git integration performs a number of checks with the RTC server under the hood• Does the user’s role in RTC have permission to push?• Is the user required to push her own commits?

– Is she pushing her own commits?• Is the user required to provide an RTC work item when he pushes?

– Does the commit message contain a valid keyword representing an RTC work item?


Sharing your changes (cont’d) If the permission and process checks are satisfied, the push goes through.

Otherwise it fails and an error message is displayed to the user.

If you forgot to add a work item number, you can amend your commit message and try pushing again

If a valid work item number is specified and the push goes through, commit links are created in the work item


Defining your own keywords You can define your own keywords for your own custom work item types Keywords are defined by using a Git configuration property

named rtc.wikeywords

The value for the property is a comma separated list of work item types

You can now use these new types in your commit messages

git config --global rtc.wikeywords "ticket,issue"

git commit –m “Fix for ticket 100”


Actionable commit messages You can use commit messages to resolve a work item or to specify the

time spent on the work item.

For example, a commit message ”Task 123 #resolve” would resolve task 123 if the commit was pushed successfully.

A commit message of “Task 123 time#1w2d5h30m” would update the time spent in task 123 to 1 week, 2 days, 5 hours and 30 minutes

You can combine the two keywords #resolve and time# : “Task 123 time#1w2d5h30m #resolve”


The RTC Git Jenkins extension The Team Concert Git Plugin integrates Jenkins with RTC, for Jenkins

Builds which use Git as source control

https://wiki.jenkins-ci.org/display/JENKINS/Team+Concert+Git+Plugin

Works for free-style software projects that use Git as source control and RTC for tracking and planning

Creates Jenkins build links in RTC work items Adds comments in RTC work items about the status of the build Annotates the changelog of a Jenkins build with RTC work item links




The RTC Git Jenkins extension


Git Flavors

Basic Git GitLab GitHub Enterprise GitHub (Public) GerritProcess Checks for Push

operationYes

Both HTTP and SSHHTTP : RTC 5.0 onwardsSSH: RTC 6.0 onwards

Yes, for HTTP.No, for SSH

RTC 6.0 onwards(with fix-pack)

No No Yes, for HTTPRTC 5.0 onwards

Process Checks for Read operations (Pull, Clone, etc.)

Yes Both HTTP and SSH

HTTP: RTC 5.0.2 onwardsSSH: RTC 6.0 onwards

No No No No

Work Item Linking Yes RTC 5.0 onwards

Yes RTC 6.0 onwards

Yes RTC 6.0.1 onwards

No, if RTC instance is behind a firewall. It is technically possible to setup the linking

using a proxy.This scenario will work with RTC SaaS

Yes RTC 5.0 onwards

Show Commit details Yes RTC 5.0.2 onwards

Yes RTC 6.0 onwards(with fix-pack)

Yes.RTC 6.0.1 onwards

Yes.RTC 6.0.1 onwards

YesRTC 5.0.2 onwards

Work item & Build Integration(via Jenkins Plugin)







Outline Why Git? The RTC value proposition Setting up the Git integration Using Git with RTC Git and Jenkins Git flavors supported Backup: supporting GitHub and GitLab

BACKUP


GitHub and RTC integration For GitHub, RTC supports work item linking However, RTC process or permissions are not applicable to GitHub

repositories

GitHub does not expose pre-receive hooks, so no validations are possible before commits are pushed.

There isn’t a mapping between GitHub public and RTC users either – no common authentication server

You don’t need to set up a Node.js server to serve up the commits

GitHub has its own server


Setting up GitHub and RTC for integration GitHub uses ‘webhooks’ for

triggering actions after commits are pushed

For the RTC integration, the webhook triggers work item linking with the commit(s) being pushed

Note that this is different from a process validation. If work item linking does not happen, RTC will throw up an error, but the push would have gone through regardless.

Instructions for setting up webhooks to do the work item linking are provided at https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/t_git_hub_ent_commit_linking.html

https://jazz.net/help-dev/clm/index.jsp?re=1&topic=/com.ibm.team.connector.cq.doc/topics/t_git_hub_ent_commit_linking.html





Setting up GitHub and RTC for integration (cont’d)

Some points of interest in the GitHub integration are

The secret key. This is specified in the Git repository registration page for RTC, as well as the settings page for a GitHub repository. RTC uses this to validate the digest of the payload sent from GitHub with what’s sent in the header.

Work items are linked using a functional user, which is specified as a part of the payload URL


Specifying the commit URL for GitHub GitHub serves up its own commits

To navigate to the commit details page from a work item link, you need to specify the URI format• $repo/commit/$sha1, where $repo would be substituted with the URI for the

GitHub repository and $sha1 with the commit sha1.

You’d be required to login to GitHub with valid credentials to be able to view the commit details


Future: advanced GitHub use cases Tracked by Improve GitHub integration in RTC (387171) Mostly investigative at this point Feedback welcome

https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/387171

https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/387171


Setting up GitLab for RTC Integration For GitLab, RTC supports work item linking However, RTC process or permissions are only applicable to push

operations, not read operations User mapping for process is done via a REST API offered by GitLab, which

retrieves the system user ID based on an environment variable. You don’t need to set up a Node.js server to serve up the commits

GitLab has its own server

THANK YOU

ibm rational team concert integration with git source control

Technology