Git Installation & User Guide

Note: This documentation applies to the original, post-commit hook style Git connector for CA Agile Central (formerly known as Rally). If you are using the latest Git VCS version 1.20, please refer to the Git VCS Installation & User Guide.

The connector for Git can link to and modify tasks, defects, and user stories contained in CA Agile Central. To change the state of a CA Agile Central artifact, enter the ID for the artifact, followed by the state you wish to change to in your commit message.

The connector, upon a push to a remote repository, will:

  • Inspect the contents of all commit comments and create a changeset object in CA Agile Central associated to the CA Agile Central artifact for each comment
  • Create a change object for each affected file
  • Optionally update the state of the CA Agile Central artifact

For example, if you check in two files with the commit message Fixed DE17, upon the push to a remote repository the Git connector:

  • Creates a changeset object for the commit revision
  • Creates two change objects for the affected files
  • Links the changeset object to the defect object
  • Sets the state of defect 17 to Fixed

The diagram below shows the objects that are created and modified when a check-in occurs with a CA Agile Central 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 CA Agile Central.

scm

The connector makes the following changes to CA Agile Central:

  1. Change the Status field (depending up the artifact type) to the new status specified in the commit message (note Completed in the above example). The Status fields on the artifacts are:
    • Defect: State
    • Story: ScheduleState
    • Task: State
  2. Create an SCMRepository object if one does not exist in CA Agile Central based on the <RallySCMRepositoryName> value in the configuration file.
  3. Create a changeset object in CA Agile Central associated to the artifact with message, revision, commit timestamp, and URI populated.
    artifact
  4. Creates change object in CA Agile Central for each affected file associated to the changeset object with action, filename path, base, extension, and URI fields populated.
    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.

This install guide includes:

Basic Installation Steps

  1. Install Ruby and the CA Agile Central connector for Git code.
  2. Set up the provided config.xml file with your customizations for Git.
  3. Run the config_test.rb to validate the configuration file.
  4. Set up git2rally.rb to be executed by the Git post-receive hook.

Get the Connector

The CA Agile Central connector for Git runs as a hook into a remote Git repository to create changeset objects in CA Agile Central from the message in your Git commit.

Connector download: RallyConnectorForGit-3.7.zip

This zip file contains the source code and Ruby scripts to plug into your hook for Git.

Software and Hardware Requirements

  • A CA Agile Central subscription . Most build and changeset data will not display in CA Agile Central until a workspace administrator enables the build and changeset flag by editing the workspace .
  • Access to your Git server.
  • 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.
  • Currently, cgit is the only supported Git web front-end client.
  • 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

Install the Connector

Note on upgrade process: If you are using a pre-2.0 version of connector and wish to upgrade to 2.0, 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 that you wish to create in CA Agile Central. 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 CA Agile Central changesets, add a <UserDomain> element to your config.xml file and set it to the email domain for your company (mydomain.com).

  1. Install the Ruby programming language.
  2. Install the required Ruby gems by entering the following from a command window:
    gem install builder -y # Will be 3.0.0 or later.
    gem install rally_rest_api -y # Will be 1.0.3 or later.
    gem install rally_api -y # Will be 0.4.1 or later.<br />
    • Answer yes to any questions about installing required dependencies.
    • 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. Go 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:
    chmod a+rx GitToRally
    chmod a+rw GitToRally/Rally_Connector_Error.log

Git Setup

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

Set 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.
    #!/bin/sh
    /usr/bin/ruby /opt/integrations/GitToRally/git2rally.rb $1 $2
  2. Verify the RallyWrapper.sh file is executable by entering this command:
    chmod u+x RallyWrapper.sh
  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.
    #!/bin/sh
    while read oldrev newrev refname
    do
     cd /opt/integrations/GitToRally/
     bash RallyWrapper.sh $oldrev $newrev > Rally_Connector_Error.log 2>1 &
    done
  5. Verify the post-receive file is executable by entering this command:
    chmod u+x post-receive

Configure the Connector

Set Up 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.

  • <RallyUserName>: The CA Agile Central user's login name you want to use for the updates in CA Agile Central.
  • <RallyPassword>: The CA Agile Central user's password. The first time the connector runs, it will encode your password in the XML file for added security.
  • <RallyBaseUrl>: The URL you use to log into CA Agile Central. For most users, the expected URL is rally1.rallydev.com or trial.rallydev.com.
  • <RallyWorkspaceName>: The name of the CA Agile Central workspace where you want to update artifacts.
  • <SourceControlUrl>: 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>. For example, git/cgit/integrations_test.
  • <RallySCMRepositoryName>: Any name of your choosing for the CA Agile Central SCMRepository object. The first time the connector runs, the connector automatically creates a new CA Agile Central SCMRepository object with Name set to the specified name.
  • <UserDomain>: Your company domain name such as acme.com. This tag determines what CA Agile Central user is used to populate the author field when creating the changeset object.
  • Optional—<CommitterUserLookupField>: A field name on the User Object in CA Agile Central. This will look up a commit user through that User field in CA Agile Central to link the changset Author to a user in CA Agile Central. For example, committer is user123 and the CA Agile Central user is [email protected] with MiddleName set to user123. If no users are found and the UserDomain element is set, the search will also try that association.

If set, the connector searches the CA Agile Central user based on the map to the Git user name such as [email protected] username in CA Agile Central to myuser Git user name.

If not set, the connector searches the CA Agile Central user based on the Git user email such as [email protected] username in CA Agile Central to [email protected] Git user email.

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

  • <Defect> is DE (default)
  • <Story> is US (default)
  • <Task> is TA (default)

Example config.xml file:

<Config>
	<RallyBaseUrl>rally1.rallydev.com</RallyBaseUrl>
	<RallyUserName>[email protected]</RallyUserName>
	<RallyPassword>MyPassword</RallyPassword>
	<RallyWorkspaceName>MyWorkspace</RallyWorkspaceName>
	<SourceControlUrl>gitserver/cgit/myrepo</SourceControlUrl>
	<RallySCMRepositoryName>MyGitRepository</RallySCMRepositoryName>
   <!--	The following is used to determine how to translate a commit author to a CA Agile Central user.
	Example: "user" to "[email protected]"
   -->
	<UserDomain>domain.com</UserDomain>A

   <!-- The following section is for specifying if you have configured CA Agile Central to use
	custom prefixes for the FormattedIDs.  NOTE: If your custom prefix
	ends with a digit, this connector will not function properly.
   -->
	<Prefixes>
		<Defect>DE</Defect>
		<Story>US</Story>
		<Task>TA</Task>
	</Prefixes>

	<Log>
		<FileName>Rally_Connector_Error.log</FileName>
		<Level>0</Level>
	</Log>
</Config>

After the first check-in comment which includes a CA Agile Central 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 CA Agile Central administrator modifies the allowed state values for user stories and 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:

<CachedStates>
	<DefectStates>
		<!-- State field on the Defect artifact.-->
		<State>Pre-test</State>
		<State>Submitted</State>
		<State>Open</State>
		<State>Fixed</State>
		<State>Closed</State>
		<State>Post-test</State>
	</DefectStates>

	<HierarchicalRequirementStates>
		<!-- ScheduleState field on the User Story artifact.-->
		<State>Pre-story</State>
		<State>Defined</State>
		<State>In-Progress</State>
		<State>Completed</State>
		<State>Accepted</State>
		<State>Post-story</State>
	</HierarchicalRequirementStates>

	<TaskStates>
		<!-- State field on the Task artifact.-->
		<State>Defined</State>
		<State>In-Progress</State>
		<State>Completed</State>
	</TaskStates>
</CachedStates>

Test the Configuration File

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

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

Troubleshoot the Connector

Changesets not Displaying in CA Agile Central

Verify your workspace administrator has selected the Enable Build and Changeset option on the Edit Workspace editor and verify there are no unexpected messages in the Rally_Connector_Error.log file. No errors are written to the console.

Debug output

You can change the level of logging from the connector by including the following information in your configuration file:

<Log>
        <FileName>Rally_Connector_Error.log</FileName>
        <Level>0</Level>
</Log>

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

Revision History

  • 3.7.0 - Jun 2012
    • Added support for multiple artifacts of the same type and multiple types
    • Now the artifact's State and ScheduleState are identified dynamically, no longer requiring the <CachedStates> section in the configuration file
    • Updated build environment so that Ruby 1.9.2 (or greater) is required
  • 2.4.0 - Jan 2012
    • Added support for mapping Git user name to CA Agile Central username through the MiddleName field in CA Agile Central
  • 2.2.0b - Jun 2011
    • Added support for mapping Git user email to CA Agile Central username on changeset object
    • Added ability to specify prefix (https or http) on SourceControlUrl
  • 2.1.0b - Jan 2011
    • Added support for mapping Git author to CA Agile Central user on changeset object
    • Added instructions on running connector as background process for optimal performance
  • 2.0.0b - Jun 2010
  • 1.0.3b - Jan 2010
    • Original version of the connector
Download Code

Feedback

Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.