Rally's Git Connector Installation & User Guide

Print this topicEmail this topic

Connector downloads:

Note: This documentation applies to Rally's newest VCS-Git connector. If you are using Rally's original, post-commit hook style Git connector, please refer to the Git Legacy Installation & User Guide.

The Git to Rally connector helps you show traceability of code changes to artifacts in Rally.

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)


  • 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.

Distribution contents

Archive:  git2rally-gemconn-1.2.5-cib1034.zip
   creating: git2rally-1.2.5/
   creating: git2rally-1.2.5/configs/
  inflating: git2rally-1.2.5/configs/sample.yml  
  inflating: git2rally-1.2.5/configs/user_map.txt  
   creating: git2rally-1.2.5/extension/
  inflating: git2rally-1.2.5/extension/metpost.rb  
  inflating: git2rally-1.2.5/extension/statex.rb  
  inflating: git2rally-1.2.5/git2rally.rb  
   creating: git2rally-1.2.5/lib/
  inflating: git2rally-1.2.5/lib/git_connection.rb  
  inflating: git2rally-1.2.5/LICENSE  
   creating: git2rally-1.2.5/logs/
   creating: git2rally-1.2.5/plugin/
  inflating: git2rally-1.2.5/plugin/blank.rb  
  inflating: git2rally-1.2.5/plugin/chainlkup.rb  
  inflating: git2rally-1.2.5/plugin/domainaug.rb  
  inflating: git2rally-1.2.5/plugin/emailaddr.rb  
  inflating: git2rally-1.2.5/plugin/filemap.rb  
  inflating: git2rally-1.2.5/plugin/passthru.rb  
  inflating: git2rally-1.2.5/plugin/ralkup.rb  
  inflating: git2rally-1.2.5/plugin/viscount.rb  
  inflating: git2rally-1.2.5/README  
  inflating: git2rally-1.2.5/User-Mapping-Strategies  
  inflating: git2rally-1.2.5/vcseif-1.2.5.gem  

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)


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

  1. 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.

  2. 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

  3. 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.

Example configuration


    Server         : us1.rallydev.com
    Protocol       : https
    Username       : jojo@muchly.com
    Password       : 22333four
    Workspace      : VanillaBean
    SCMRepository  : Balloon
    #Proxy         : some_proxy.yoursite.com:9876  # or an IP address:port
    #ProxyUser     : outbound
    #ProxyPassword : bvc-357%GNQ
    Lookback : 5 days  # in minutes by default, use m/h/d suffix for minutes/hours/days
    UpdateArtifactState : False
    StateExtractorClass : BasicActionsAndArtifactsExtractor(message)
    Debug : False

#   Server    : your_vcs_server.company.com # optional, but if set connector runner user
                                            # must authenticate using PKI
    RepositoryBase: /var/git/repo.git        #make sure the .git is specified for remote servers
    RevURI    : http://git.company.org/cgit/repo.git/commit/?id={revnumber}   # optional, if running web access to repo
    FileURI   : http://git.company.org/cgit/repo.git/tree/{filepath}/?id={revnumber}  # optional, if running web access
    Lookback : 5 days
    Debug    : False

    Preview  : False
    LogLevel : Debug

    Author : Passthru


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.

For help creating a full-access API Key, please visit http://help.rallydev.com/rally-application-manager.


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:

For Windows:
    git2rally.exe  apricot  banana  cherry  dogwood
For Ruby:
    ruby  git2rally.rb  apricot  banana  cherry  dogwood
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.


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.

git  commit  my_file.java  -m  "Fixed DE1987 by changing preamble paragraph 3"

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).



Revision history

  • 1.2.6 - master-1036 (Jan-2015)
    • Enhancements:
      • Updated rally_vcs_connection.rb configureExtensionEnvironment and statex.rb to accommodate custom artifact prefixes (such as 'BUG' for Defect, etc).
      • Updated dependency for rally_api to version 1.1.2.
  • 1.2.5 - master-1034 (October-2014)
    • Enhancements:
      • 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.


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.
© 2015 Rally Software Development Corp | Legal