Subversion Installation & User Guide


Note: This documentation refers to the unsupported and deprecated post-commit hook Subversion connector. Refer to the new SVN-VCS connector, which is based on a polling method.

The Rally connector for Subversion inspects the contents of a check-in comment and creates a changeset in Rally associated to the Rally artifact, creates changes objects for each affected file and optionally updates the state of the Rally artifact.

The Rally connector for Subversion:

  • Inspects the contents of a check-in comment and create a changeset object in Rally associated to the Rally artifact
  • Creates Rally change object objects (within the changeset) for each affected file
  • Optionally updates the state of one or more Rally artifacts

For example, if you check in two files with the commit message Fixed DE17, the Subversion connector:

  • Creates a changeset object for the check-in revision
  • Creates two change objects, one for each affected file
  • Links the changeset to the defect
  • Sets the state of the defect (DE17) to Fixed

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


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. For example, Extremely important fetching feature done. S123 Completed.

The connector makes the following changes to Rally:

  1. Create an SCMSystemRepository object if one does not exist in Rally based on the <SCMRepositoryName> value in the config file.
  2. Create a changeset object in Rally associated to the artifact with message, revision, commit timestamp, and URI populated.

  3. Create a change object in Rally for each affected file associated to the changeset with action, filename path, base, extension, and URI fields populated.

  4. Depending on 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: State
    • Story: ScheduleState
    • Task: State

There are two ways to update a task, defect, or user story. Either include the new state directly before or after the FormattedIDs of the same artifact type.

Examples of commit messages containing artifact IDs and state transitions:

  • Added new class and Fixed DE174 DE248
  • Completed US234 US345 Fixed DE843 and Completed TA124 while I was in the code

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 Rally connector for Subversion code.
  2. Setup the config.xml for Subversion.
  3. Run the config_test.rb to validate that the config.xml file is set up correctly.
  4. Setup svn2rally.rb to be executed by the Subversion post-commit hook.

Get the connector

Connector downloads:

The attached ZIP file contain the source code and Ruby scripts to plug in to your post-commit hook.

The attached PDF document describes the setup and two usage scenarios:

  • The connector is called through wrapper scripts
  • The connector is called directly by a post-commit.bat file (useful for troubleshooting purposes)

Software and hardware requirements

  • A Rally subscription    
    • Note: Most build and changeset data will not be visible in Rally until a workspace administrator checks the Enable Build and Changeset box in the workspace editor on all workspaces being used.
  • Access to your Subversion server
  • Ruby version 1.9.2 or greater (issue ruby -v at a command prompt to see the version)
  • Ruby gems (libraries) installed (issue gem install --local at a command prompt to view them)      

    The gem rally_api 0.4.1 or greater is needed. It can be downloaded from:

Install the connector

Note on upgrade process: For those customers using a pre-3.0 version of connector and wish to upgrade to 3.0, ensure you 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, add an <SCMRepositoryName> element to your config.xml and set it to the name of the SCMRepository you wish to create in Rally. SCMRepositoryName is a required element. Additionally, you will need to download version 0.4.1 or later of the rally_api gem by typing the command gem install rally_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 (

  1. Install the Ruby programming language. As of version 3.7, you must use Ruby version 1.9.2 or greater. Make sure the user running your Subversion server is given access to the Ruby installation.
  2. Install the builder (version 3.0.x or greater) and rally_api (version 0.4.1 or greater) gems by entering the following from a command window:
    gem install builder
    gem install rally_api

    Answer yes to any questions about installing required dependencies.
  3. Save the file on your machine into the directory where you want to install the connector. Navigate to the install directory, and extract the file.

If running on Unix, save the file locally on your machine into a directory of your choosing, for example, /opt/Rally. Navigate to the install directory, and extract the file. The unzip will create a SvnToRally subdirectory. For the connector to run successfully, Subversion 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 SvnToRally:

chmod -R a+x SvnToRally
chmod 775 SvnToRally/Rally_Connector_Error.log

Set up Subversion

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

Multiple repositories and workspaces

It is possible to have multiple subversion repositories mapping into a single Rally workspace. In this case, a separate install of the subversion connector must be performed for each repository.

It is not recommended to have a single subversion repository attempting to map into multiple Rally workspaces (otherwise, a check-in comment for DE10 is not unique, as each workspace could have a DE10).

Set up the post-commit 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 that contains the command to run the svn2rally script. Ensure you specify the full path to Ruby and the svn2rally.rb file.
    /usr/bin/ruby /opt/integrations/SvnToRally/svn2rally.rb $1 $2

  2. Verify the file is executable by entering this command:
    chmod u+x              
  3. Go to the Subversion installation hooks subdirectory (the name should be something like <YourRepositoryPath>/hooks) and copy post-commit.tmpl to post-commit if it does not exist already. This script must be named post-commit as the SVN system will invoke it by that name.
  4. In the post-commit script, add the line below. This command runs the child process in the background and redirects standard error to the Rally_Connector_Error.log file:
       bash /opt/integrations/SvnToRally/ "$REPOS" "$REV" 2> /opt/integrations/SvnToRally/Rally_Connector_Error.log &

  5. Verify the post-commit file is executable by entering this command:
    chmod u+x post-commit              

Set up the post-commit hook on Windows

The steps below assume that all files are saved in the C:\SvnToRally directory. Your file paths may vary depending on your installation.

  1. Create a VBScript (RunSvnToRally.vbs) which contains commands to run the connector in the background, as follows:
    Set WshShell = WScript.CreateObject("WScript.Shell")
    set args = WScript.Arguments
    WshShell.Run("ruby C:\SvnToRally\svn2rally.rb" & " " & chr(34) & args(0) & chr(34) & " " & args(1))

  2. Create a batch file (RallyWrapper.bat) which contains commands to run the VBScript, as follows:
    C:\SvnToRally\RunSvnToRally.vbs %1 %2

  3. Browse to the repository directory on the Subversion server and navigate to the hooks directory.
  4. Create and modify the post-commit.bat file and add the lines below:
    SET REPOS=%1
    SET REV=%2
    C:\SvnToRally\RallyWrapper.bat %REPOS% %REV%

Configure the connector

Edit and save the config.xml file by 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 Rally user's login name you want to use for the updates in Rally.
  • <RallyPassword>: The Rally user's password. The first time the connector runs it will encode your password and re-write it into the XML file for added security.
  • <RallyBaseUrl>: The URL used to log into Rally. For most users, the expected URL is or
  • <RallyWorkspaceName>: The name of the Rally workspace where artifacts are to be updated. If the workspace name contains an ampersand character, replace it with the five character string &amp;.
  • <SourceControlUrl>: The URL used to reference the Subversion web interface. You may fully qualify the URL with the protocol (http, https, svn), but it defaults to http:// for the protocol if not specified.
  • <RallySCMRepositoryName>: 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 Name set to the user specified name.
  • <UserDomain>: The domain name of your company. If set, this will map a Subversion author (myuser) to a Rally user ( The Rally user is used to populate the Author field when creating the changeset object.
  • Optional—<CommitterUserLookupField>: The name of a field on the User Object in Rally. When the connector runs, it attempts to find a Rally user object where the string in the specified field is identical to the user doing the commit. If found, the matching Rally user becomes the Author on the changeset. This field must be populated with a username in all lowercase—regardless of the actual subversion username—as the subversion username will be converted to lowercase before the comparison. If no match is found, then the <UserDomain> element above is tried. For example, if <CommitterUserLookupField>MiddleName</CommitterUserLookupField>, then:
    • SVN committer is User123
    • SVN user User123 has a Rally username of
    • MiddleName field for Rally is set to user123 (must be lowercase)
    • Author on changesets in Rally is set to
    • Note: If no matching user is found with this method and the <UserDomain> element is set, then the lookup will also try to use the domain association.

  • <Prefixes>: The element used to specify any custom prefixes you have specified for your artifacts:
    • <Defect>
    • <Story>
    • <Task>

Example config.xml file:

      <!-- This section is for specifying if you have configured
           Rally to use custom prefixes for the FormattedIDs.
           NOTE: If your custom prefix ends with a number,
                 this connector will not function properly.

Test the configuration file

To test the 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. Ruby version check                                 PASSED  
 2. Ruby rally_api gem check                           PASSED  
 3. Current directory world searchability check        PASSED  
 4. Wrapper script world executability check           PASSED  
 5. <vcs>2rally.rb driver world readability check      PASSED  
 6. Log file write check                               PASSED  
 7. Rally Url check                                    PASSED  
 8. Rally Connection check                             PASSED  
 9. Rally Workspace check                              PASSED  
10. Rally Build and Changeset flag enabled check       PASSED  
11. Email validation check                             PASSED  

Troubleshoot the connector

Changesets do not display in Rally

Verify your workspace administrator has selected the Enable Build and Changeset option on the 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 the connector outputs by including the following information in the config.xml file:


Log level 0 will produce the maximum amount of output, with log level 5 producing the least. These levels are documented at

  • DEBUG   = 0
  • INFO    = 1
  • WARN    = 2
  • ERROR   = 3
  • FATAL   = 4
  • UNKNOWN = 5

Beta-test scripts

The following two scripts, post-commit and (along with their output file), are being tested and considered for inclusion in the product. They were developed and tested on MAC OS X (terminal window). Any feedback is welcomed.

#       post-commit
#       To be placed in the "hooks" directory of an SVN repository,
#       where it will be invoked upon an SVN commit.

# Define the variables needed.

# Redirect all output to the designated logfile.
exec >> ${MY_logfile} 2>&1

# This script should have been invoked with exactly 2 arguments; verify.
#      Arg1 - The repository name
#      Arg2 - The committed revision
if [ ${#} -ne 2 ]; then
        echo "[`date`] post-commit : ERROR - Command requires 2 args; found ${#}"
        echo "[`date`] post-commit : Arguments supplied: ${*}"
        exit -1

# Invoke the Rally SVN Wrapper script in the background so user does not
# wait for a prompt on commits. Pass it 3 arguments:
#      Arg1 - The repository name
#      Arg2 - The committed revision
#      Arg3 - The path to the Rally SVN connector's Ruby source file
enable -n echo
echo    "[`date`] ------------------------------------------------------------"
echo    "[`date`] post-commit : INFO - Entry. ${#} args (${1} & ${2})"
echo -n "[`date`] post-commit : INFO - Invoking: ${MY_wrapper}"
echo    " ${MY_repo_name} ${MY_commitrev} ${MY_svn2rally} &"
${MY_wrapper} "${MY_repo_name}" "${MY_commitrev}" "${MY_svn2rally}" &
echo    "[`date`] post-commit : INFO - Exiting."

#[the end]#

#       Invoked into the background by the post-commit script of an SVN
#       repository upon a commit.

# This script should have been invoked with exactly 3 arguments; verify.
#      Arg1 - The repository name
#      Arg2 - The committed revision
#      Arg3 - The path to the Rally SVN connector's Ruby source file
if [ ${#} -ne 3 ]; then
        echo "[`date`] RallyWrapper: ERROR - Command requires 3 args; found ${#}"
        echo "[`date`] RallyWrapper: Arguments supplied: ${*}"
        exit -1

# Define the variables needed.
echo "[`date`] RallyWrapper: INFO - Entry. ${#} args (${1} & ${2} ${3})"


# Invoke the SVN-to-Rally Ruby script which will create a Rally changeset
# for this commit.
enable -n echo
echo -n "[`date`] RallyWrapper: INFO - Invoking:"
echo    " ruby ${MY_svn2rally} ${MY_repo_name} ${MY_commitrev}"
if [ -d ~/.rvm ]; then source ~/.rvm/scripts/rvm; fi
ruby ${MY_svn2rally} ${MY_repo_name} ${MY_commitrev}
echo -n "[`date`] RallyWrapper: INFO - Back from:"
echo    " ruby ${MY_svn2rally} ${MY_repo_name} ${MY_commitrev}"
echo    "[`date`] RallyWrapper: INFO - Exiting."

#[the end]#

[Sat May 26 10:26:48 MDT 2012] ------------------------------------------------------------
[Sat May 26 10:26:48 MDT 2012] post-commit : INFO - Entry. 2 args (/tmp/Repo & 6)
[Sat May 26 10:26:48 MDT 2012] post-commit : INFO - Invoking: /tmp/SvnToRally/ /tmp/Repo 6 /tmp/SvnToRally/svn2rally.rb &
[Sat May 26 10:26:48 MDT 2012] post-commit : INFO - Exiting.
[Sat May 26 10:26:48 MDT 2012] RallyWrapper: INFO - Entry. 3 args (/tmp/Repo & 6 /tmp/SvnToRally/svn2rally.rb)
[Sat May 26 10:26:48 MDT 2012] RallyWrapper: INFO - Invoking: ruby /tmp/SvnToRally/svn2rally.rb /tmp/Repo 6
[Sat May 26 10:26:53 MDT 2012] RallyWrapper: INFO - Back from: ruby /tmp/SvnToRally/svn2rally.rb /tmp/Repo 6
[Sat May 26 10:26:53 MDT 2012] RallyWrapper: INFO - Exiting.

Revision history

  • 3.7 – Minor fixes
  • 3.5 – Minor fixes
  • 3.4 – Change to wrap calls out to svnlook's repopath in quotes in case repopath has spaces
  • 3.3 – Update to capture and log errors in svn2rally.rb at execution
  • 3.2 – Build and changeset support


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.