Supported platforms

The connector supports running in a variety of platforms.
This software is written in Ruby and has been tested using
Ruby 1.9.2-p290, but should also work with Ruby 1.9.3-p194.
If this software is for use on a Linux/Unix/MacOSX system, then it must
be installed after you install the httpclient and rally_api gems.

There are two options for running the connector:

Option 1: In Windows as a packaged executable (recommended if you want the connector to run on a Windows machine)

Option 2: In any OS via Ruby as a packaged gem (on any OS with Ruby 1.9.2 or greater installed)

Prerequisites

Select a machine which will run the connector

Git must be installed on this machine

If the connector is on a different machine than the location of the Git server, note the server address and name

Know the paths to the repositories you will gather information from

Select the Rally workspace in which the information will be going

Download and install the connector

Installer and operator filesystem permissions

As this connector is intended to run on an ongoing basis initiated by
either cron or Windows Task Scheduler (WTS), it is important to consider the
identity of the user who installs the connector versus the identity of
the user when running through cron/WTS with regard to the permissioning and ACL
of the directories and files in the connector installation.
The user running the connector must be able to read all files and must be
able to write in the configs and logs subdirectories.

Install on Windows with the pre-built executable (simple)

If you are using the Windows executable-based connector, run the
installer .exe to install the connector to your desired location on your computer.

Install using the Ruby gem distribution (complex)

Prerequisites

Ruby version 2.0.0-p247 or greater (recommended via RVM or http://rubyinstaller.org)
httpclient version 2.4.0 (available at http://www.rubygems.org/gems/httpclient)
rally_api version 1.1.2 or better (available at http://www.rubygems.org/gems/rally_api)

Install the httpclient and rally_api gems before installing the connector,
using the gem install command.
Additional information about Ruby gems and their installation can be obtained from
http://www.ruby-lang.org/en/libraries and other websites related to the Ruby language and ecosystem.

Unpack and set up the source folder

Unpack the source distribution into a directory you want to use
as the operational home for this software.

Tip: The distribution unpacks into a git2rally-*-<version>-<build_ident> directory.

Create a symlink with a shorter name to point to that, either under the same
directory root or from somewhere else (/usr/local or /opt/local).

For example:

$ ln -s /opt/sw/git2rally-gemconn-0.8.7-cib22 /opt/local/gitr

Install the vcseif gem:

# using the above example of having created a symlink to the installation root...
$ cd /opt/local/gitr
$ gem install --local vcseif-[version].gem--no-ri --no-rdoc

Git server versus ssh

The primary use case is for this connector to be run on the platform that
the Git software and repository reside on.
While it is possible to run this connector on a platform that is not the
Git platform, that use case assumes the use of ssh and the proper
setup of public and private key information. Setting up ssh and key files is
beyond the scope of this document; consult the internet for documents regarding ssh and PKI.
If you are running the connector on Windows, you will need to have an executable
for ssh if you plan to connect to a remote box. Packages such as Cygwin and the
Git installer for Windows include an ssh.exe. You will then need to add the
location of that ssh.exe to your PATH environment variable to be able successfully
connect to a remote repository or server.

If you are using Option 1 (above) with the executable for Windows, there are no further prerequisites.
If you intend to run the Ruby source, Option 2, you will need to install Ruby version 1.9.2 or greater
on the machine which will run the connector. We recommend getting the Ruby installer for Windows
from rubyinstaller.org or using rvm from rvm.io for Linux/Unix users.

Set up Git

Consider how much Git history you want to have reflected in Rally

It is possible to operate the connector to catch-up with the complete
history of commits in Git. You should assemble a pro and con list of
considerations, reasons, and benefits to help you arrive at a strategy that
works for your organization with respect to whether you need a
complete commit history reflected in Rally or just reflected from some
particular point in time.

Note: The Git connector will search the Git repository for commits. However, these commits get into the repository via the 'git push' command. The 'git commit' command is merely a local 'save' of your current work.

Lookback setting

The connector stores a timefile with the commit time of the last commit it successfully processed.
Since Git is a distributed version control system, a certain number of days to lookback should be configured
for the connector. This should be the best guess and comfort level for the way your team uses git.
For example:
Two team members are working on code in Git.
One team member may push their commits up to the server every day.
The second team member may only push their commits up at the end of the week.
The connector will need to lookback to successfully find your second team member's commits. The Lookback setting
in the configuration will lookback that number of days since the last successful commit to find commits to reflect
in Rally. The default units are minutes, but you can use 5d, 5 Days, 24 hours, 24h as other values.
As a best practice, we recommend a regular push strategy in your use of git to get those commits on the
git server. The connector will check all refs in git for commit messages, so commits on a topic branch other
than master will be found and reflected in Rally.

Set up Rally

Verify that your target WorkspaceConfiguration has BuildandChangsetEnabled set. Your Rally workspace administrator needs to enable this for your target workspace.
If it is not enabled, the connector will work, but you won't be able to see
any of the changeset or change information that is associated with your Rally
work items (story, defect, task).

Configure the connector

Copy the sample.yml file in configs to a new name, for example, repo_one.yaml.
Edit the copied file and adjust some of the sample values for servers, credentials
workspaces, repository names, and paths to values appropriate for your environment.
The file is in YAML format. The YAML format uses indentation to represent structure
and colon character (:) and dash character (-) to denote name and value separation
and list elements. So, you'll need to be aware of preserving those syntactical
elements in your edited file.

Within the Rally section of your YAML configuration file, there is an entry where
you can name the SCMRepository in the Rally system to which changeset and change items
will be associated. This SCMRepository is a named container which need not exist
before running the connector; if it doesn't exist, the connector creates
the SCMRepository in the Rally user's target workspace.

There is an optional lookback configuration item that can appear on either or both of
the Rally and Git sections of the configuration file. The value for this parameter
is expressed in terms of minutes (default or with the use of the m character) or
hours using an h character or days by using a d character.
Examples:

Lookback:90
Lookback:120 m
Lookback:8 h
Lookback:10 d

If you do not explicitly provide a lookback value, the connector uses a default value of 1 hour.
Rally recommends that if you specify a value for lookback in either section that you also specify
a lookback in the counterpart section with the same value. If the lookback values
are not identical, there is the possibility under some circumstances that a changeset from
Git would not be reflected in Rally due to the nature of distributed version control systems
recording the original commit time and not the time the commits are pushed to a master repository;
the window of time consideration being too short for the connector to pick up such commits.

Assess how user names are alike or differ in your Git system and in your
Rally subscription. If the user names are universally identical in both systems,
then you can either comment out all author sub-items underneath the Transforms section
or you can set the value for the Author field in the Transforms section to Passthru.
If there is a deterministic mapping that can transform a Git
user value to the corresponding correct Rally user name value, you will need to
adjust the transformation value for Author to the appropriate classname.
Consult the User-Mapping-Strategies text document to determine which technique
fits your particular situation.

Once you have identified a suitable Author transformation technique, you will
need to edit the configuration to identify the Ruby class name that will implement
that transformation. The Ruby class name must exist in a file of Ruby source code
that is in a file in the plugin subdirectory.

RevURI and FileURI under Git config

This is meant to be the root URI if you are using
a web front-end for your system. The URI will be used as a base for the link to the changesets
and files. For example, if you have http://server:port/Git/rev/ as your root, a link
will be made in Rally for the changeset to http://server:port/Git/rev/12345 for changset 12345.
The strings {revnumber} and {filepath} are substituted in when the connector builds the link stored in Rally.

Note that the Proxy* items are commented out by using a # in front of the item.
Within a YAML file, any line beginning with a # character is ignored and any
content following a # character sequence is ignored (including the # sequence).

Create a Rally API key

A Rally API Key can be created to use to access your subscription data without using your username and password.

To use the API Key in a connector, edit the Rally section in the config .yml file and add an APIKey line. When the ApiKey configuration is specified, omit the Username and Password from the Rally config section. If an API Key is provided, the username and password are not used and a warning will appear in the log file if they are included in the config file. This is true even if the API Key value is invalid, blank, or nil. If your subscription administrator has configured your subscription to be SSO only, in order to use Basic Auth or API Key, your administrator must add your intended user to the white list.

The connector now uses rally_api version 1.1.2. Please note that the API Key must have full access, a read-only api key will not allow the connector to write to Rally.

Run the connector

Within the Services section of your config file (repo_one.yaml for example), is
an entry for Preview that is set to False. You may want to set this value to True
in the initial setup phase to see that the connector can successfully connect to Rally
with the credentials and information you provided, as well as proving out the
use of the git command. Your PATH environment variable must contain a filesystem
path where the git command can be found. See Linux / Unix / MacOSX / Windows
documentation on how to set environment variables for use within a *nix cron job
(or Windows Task Scheduler entry).
Once you have determined that a connector run in Preview mode operates as expected,
you can set the Preview value in your config to a False value.

On an ongoing basis, you can use cron or Windows Task Scheduler
(or any other job or task scheduling software) to run the connector periodically.
Initially, Rally recommends the connector to be run every 15 minutes during normal
business hours and less frequently during non-business hours.

You can have numerous configuration files in the configs subdirectory and specify them all for
invocation either by name or by globbing (wild-card syntax). For example:

The files apricot.yml, banana.yml, cherry.yml, and dogwood.yml must exist in the
configs subdirectory. The connector only looks for config files in the configs
subdirectory under the installation base directory.

Whenever the connector is run, an entry is made in the logs/git2rally.log file to note
the invocation. For each config named at invocation, there is an entry in that file
noting the return code from running that config. When the connector run has finished with
all configs, an entry is written to note the completion of the connector run.

Additionally, there will be a file written in the logs subdirectory for each config named
that will have much more detail about the activity that occurs during the run.
You can adjust the verbosity written to these log files by modifying the LogLevel value
in the config file. Normally, the LogLevel would be set to Info. Should you encounter
situations where the connector does not complete normally, you can adjust the LogLevel to
Debug and run the connector to begin the troubleshooting process. These log files
can be sent to Rally Support to expedite the investigation of a case.

The connector will write a file in the base installation directory corresponding to the
config name with the date of the last commit processed. The file is named
config_time.file and has a time entry in the form
YYYY-mm-dd HH:MM:SS Z (for Zulu time).
When first run, there won't be a time file for the config and the connector defaults
to looking for commits that occurred after 2010-01-01 00:00:00 Z. You can override that
behavior by creating and editing a time file for the config you are about to process.
By providing an entry in the format mentioned above, you can control that point from which
commits are processed.

Extensions

Within the extension sub-folder of the installation, there is an exemplar Ruby class
in the file named statex.rb. The class definition contained in that file is BasicActionsAndArtifactsExtractor. This example class demonstrates the basic technique
of examining a commit message and extracting Rally artifact identifiers and state transition
target values. Using this class when the config file item UpdateArtifactState value is set
to True results in the transition of the State (or ScheduleState in the case of UserStory) of
the identified artifact to the state value mentioned in the commit message.

For example, if there is a Rally defect (identified as DE1987) mentioned in the commit message
with a new valid state value either immediately preceding or following the artifact identifier,
then the connector changes the state of the identified artifact in Rally to that state.

If Rally defect DE1987 had a state of Open prior to the commit and run of the connector,
then subsequent to the operation of the connector processing this particular changeset, the
state of Rally defect DE1987 would display as Fixed. Please note this
message is case-sensitive, fixed is not the same as Fixed.

The extension folder allows you to provide your own message processing to extract Rally artifact
identifiers and state changes if the example provided does not fit your conventions.
Your extension must be a class written in Ruby and must provide an instance method called service which takes the commit message as an argument and must return a Ruby Hash instance with entries
keyed by a state name (Fixed, Completed, ...) or nil with a Ruby Array as the associated
value populated by Rally artifact identifiers (FormattedID).

Updated to use Rally Web Services API v2.0 and the updated rally_api gem.

1.2.4 - master-1032 (16-Sep-2014)

Enhancements/Fixes:

Added support for using API Key in lieu of username and password in the Rally portion of the configuration file.

Updated to rally_api toolkit version 1.0.1.

1.2.3 - master-1030 (19-Aug-2014)

Enhancements/Fixes:

Fixed DE21993 - to meet Rally's commit message field limitation of 4000 characters, if a commit message exceeds the character limit, characters over the limit are truncated. Upon truncation, the commit message is appended with an annotation of the truncation and a warning message displays in the log file.

Feedback

Need more help? The Rally Success Community is your one-stop shop for self-service and support. To submit feedback or cases to Rally Support, find answers, and collaborate with others, please join us at rallydev.force.com/answers.