Git Installation & User Guide

Print this topicEmail this topicSave as PDF

1. Introduction

The Rally Connector for Git inspects the contents of a check-in comment and creates a changeset in Rally associated to the Rally artifact, creates changes for each affected file and optionally updates the state of the Rally artifact. For example, if a developer checks in two files with the commit message "Fixed DE17", the Git Connector would create a changeset for the check-in revision, create two change objects for the affected files, link the changeset to the defect, and set the state of defect 17 as fixed.

The diagram below shows the objects that are created/modified when a check-in occurs with a Rally ID in the commit message (such as S123, DE17, TA123). No objects are created if the formatted ID in the change message is not found in Rally.

scm

1.2 Features

The connector can link to and modify tasks, defects and user stories contained in Rally. To change the state of a Rally artifact enter the ID for the story followed by the state you wish to change in your commit message.
Example: "Extremely important fetching feature done. S123 Completed"

The connector makes the following changes to Rally:

  1. Depending up the artifact type, the "status" field is changed to the new status specified in the check-in comment (note "Completed" in the above example). The "status" fields on the artifacts are:
    • Defect: The "State" field.
    • Story: The "ScheduleState" field.
    • Task: The "State" field.
  2. Creates an SCMRepository object if one does not exist in Rally based on the <RallySCMRepositoryName> value in the configuration file.
  3. Creates a Changeset object in Rally associated to the artifact with message, revision, commit timestamp and URI populated. Note screenshot (click to enlarge):
    artifact
  4. Creates a Change object in Rally for each affected file associated to the changeset with action, filename path, base, extension and URI fields populated. Note screenshot:
    changes

The connector automatically sets the ToDo value of a task to 0 if the commit message contains a task ID and a state of completed.

2. Pre-installation requirements

Click on the Contact Support link at the bottom of any page in Rally to open a support case to obtain the Rally Connector for Git. Once you've received a response and obtained the installation package, proceed with the following tasks.

2.1 Software and hardware requirements

The following are the hardware and software requirements to install and run the Rally Connector for Git.

  1. A Rally subscription. Most build and changeset data will not show in Rally until a workspace administrator enables the build and changeset flag by editing the workspace.
  2. Access to your Git server.
  3. Ruby programming language and Ruby gems (libraries) installed on the Git server. NOTE: You must use Ruby REST API version 1.0.3 as the connector will not work with earlier versions. This is discussed in installation steps below.
  4. Currently, cgit is the only supported Git web front-end client.
  5. The connector should work with the latest version of Git. Beta testing included running the connector as a post-receive hook with Git version 1.5.4.3 and 1.6.4.2 on a Linux server using these clients:
    • Linux
    • Mac OS X
    • Windows XP

3. Installation

Basic installation steps

  1. Install Ruby and the Rally Connector for Git code.
  2. Setup the provided config.xml file with your customizations for Git.
  3. Run the config_test.rb to validate the config file.
  4. Setup git2rally.rb to be executed by the Git post-receive hook.

Note on upgrade process:

If you are using a pre-2.0 version of connector and wish to upgrade to 2.0, please backup your config.xml file and then follow the installation directions outlined below. If you plan to use your old config.xml file once you extract the contents of the new ZIP file, add an <RallySCMRepositoryName> element to your config.xml file and set it to the name of the SCMRepository you wish to create in Rally. The <RallySCMRepositoryName> is a required element. Additionally, you will need to download version 1.0.3 or later of the rally_rest_api gem by typing the command "gem install rally_rest_api" from the command line. Optionally, to map authors to Rally changesets, add a <UserDomain> element to your config.xml file and set it to the email domain for your company (mydomain.com).

3.1 Install Ruby and the Rally connector to Git

  1. Install the Ruby programming language.
  2. Install the required Ruby Gems by entering the following from a command window:
       
    • Note1: Answer yes to any questions about installing required dependencies.
    • Note2: The rally_api gem will cause the gems mime-types (1.18 or later) and rest-client (1.6.7 or later) to be installed as well.
  3. Save the RallyConnectorForGit.zip file on your machine in a directory of your choosing, for example, /opt/Rally. Navigate to this directory, and extract the RallyConnectorForGit.zip file. This should create a GitToRally subdirectory.
  4. For the connector to run successfully, git users must have execute permissions on the install directory, and write access to the connector's log file, Rally_Connector_Error.log. To set these permissions, enter these commands in the directory above GitToRally:
       

3.2 Setup the config.xml file

Edit and save the provided config.xml file (contained in the GitToRally directory), entering the appropriate values between each begin and end tag. The XML is commented throughout to provide details on expected values for each tag.

  • Set <RallyUserName> to the Rally user's login name you want to use for the updates in Rally.
  • Set <RallyPassword> to the Rally user's password. The first time the connector runs, it will encode your password in the XML file for added security.
  • Set <RallyBaseUrl> to the URL you use to log into Rally. For most users, the expected URL is rally1.rallydev.com or trial.rallydev.com.
  • Set <RallyWorkspaceName> to the name of the Rally Workspace where you want to update artifacts.
  • Set <SourceControlUrl> to the URL you use to reference the Git web front-end (optional). The connector only supports cgit at this time. Usually, the format is: <git_server>/cgit/<path_to_repo>. Here is an example:
    git/cgit/integrations_test
  • Set <RallySCMRepositoryName> to any name of your choosing for the Rally SCMRepository object. The first time the connector runs, the connector automatically creates a new Rally SCMRepository object with the Name attribute set to the specified name.
  • Set <UserDomain> to your company domain name such as acme.com. This tag determines what Rally user is used to populate the author field when creating the changeset object.
  • Optional - Set <CommitterUserLookupField> to a field name on the User Object in Rally. This will look up a commit user via that User field in Rally to link the changset Author to a user in Rally. For example, committer is user123 and the Rally user is user@ralydev.com with MiddleName set to user123. If no users are found and the UserDomain element is set, the lookup will also try that association.

If set, the connector will lookup the Rally user based on the map to the Git user name. such as myuser@domain.com username in Rally → myuser Git user name.

If not set, the connector will lookup the Rally user based on the Git user email. such as myuser@domain.com username in Rally → myuser@domain.com Git user email.

The <Prefixes> element is used to specify any custom prefixes you have specified for your artifacts.

  • <Defect> This element is used to specify the prefix you use for defect artifacts. The default prefix is: DE.
  • <Story> This element is used to specify the prefix you use for story artifacts. The default prefix is: US.
  • <Task> This element is used to specify the prefix you use for task artifacts. The default prefix is: TA.

Example config.xml file:

After the first check-in comment which includes a Rally ID, the connector will rewrite the config.xml file to include the allowed state values for User Stories, Defects and Tasks. This will happen automatically as long as the connector script has write access to the file. This re-write will also add the <CachedStates> element to the file.

The <CachedStates> content in the config.xml file can remain untouched unless your Rally administrator modifies the allowed state values for User Stories and/or Defects. To force the next run of the connector to update the values stored in the config.xml file, modify it by deleting the text from the <CachedStates> tag to the closing tag </CachedStates>. The <CachedStates> content will be functionally equivalent to the following:

 

3.3 Test the config file

To test the your config.xml file for completeness, issue this command:

   

The above script will test the network settings and the connection information in your config.xml file. The output from the command should be:

  1. Log file write Passed.
  2. Rally Url Passed
  3. Successfully connected to Rally
  4. Rally Workspace found
  5. Email Validation Passed

3.4 Setup Git hook

The Git post-receive hook is setup so the Rally connector process runs in the background for optimal performance. After the developer checks in code, the Rally connector immediately runs and updates the appropriate objects in Rally without the developer having to wait for the Rally web services requests to complete. Consequently, check the Rally log file for any errors.

Setting up the post-receive hook on Unix:

The steps below assume you are running in a bash shell and that all files are saved in the /opt/integrations directory. Your file paths may vary depending on your installation.

  1. Create a bash script called RallyWrapper.sh that contains the command to run the git2rally script. Ensure you specify the full path to Ruby and the git2rally.rb file.
         
  2. Verify the RallyWrapper.sh file is executable by entering this command:
           
  3. Go to the Git server hooks directory.
  4. Open the post-receive file for editing (create this file if it does not exist) and add the line below. This command runs the child process in the background and redirects standard output and standard error to the Rally_Connector_Error.log file.
         
  5. Verify the post-receive file is executable by entering this command:
                

4.0 Known issues

5.0 Tip

  1. Why are changesets not displaying in Rally?
    Verify your Workspace administrator has selected the Enable Build and Changeset option on the Edit Workspace configuration pop-up and verify there are no unexpected messages in the Rally_Connector_Error.log file. No errors are written to the console.
  2. Debug output
    You can change the level of logging from the connector by including the following information in your configuration file:
       

    Log level 0 will produce the maximum amount of output, with log level 5 producing the least. These levels are documented at http://corelib.rubyonrails.org/classes/Logger/Severity.html:

    • DEBUG   = 0
    • INFO    = 1
    • WARN    = 2
    • ERROR   = 3
    • FATAL   = 4
    • UNKNOWN = 5
© 2012 Rally Software Development Corp | Legal