Subversion Installation & User Guide

Print this topicEmail this topic

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.

Get Subversion Connector

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.

Connector Download(s):

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

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

  1. The connector is called via wrapper scripts
  2. The connector is called directly by a post-commit.bat file (this scenario is useful for troubleshooting purposes).

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

Introduction

The Rally Connector for Subversion will:

  • Inspect the contents of a check-in comment and create a Changeset object in Rally associated to the Rally artifact
  • Create Rally Change object objects (within the changeset) for each affected file
  • Optionally update the state of one or more Rally artifacts

For example, if a developer checks in two files with the commit message "Fixed DE17", the Subversion Connector would:

  • Create a Changeset object for the check-in revision
  • Create two Change objects, one for each affected file
  • Link the changeset to the defect
  • Set the state of the defect (DE17) to "Fixed"

The diagram below shows the objects that are created/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.

scm

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. Creates an SCMSystemRepository object if one does not exist in Rally based on the <SCMRepositoryName> value in the config file.

  2. Creates a Changeset object in Rally associated to the artifact with message, revision, commit timestamp and URI populated. Note screenshot (click to enlarge):
    artifact

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

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

There are two ways to update a task, defect, or user story.

  1. Include the new state of the task, defect, or user story directly before the FormattedID or FormattedIDs of the same artifact type.
  2. Include the new state of the task, defect, or user story directly after the FormattedID or FormattedIDs of the same artifact type.

    Here are a couple of examples of commit messages containing artifact IDs and state transitions:
  • Added Foo 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.

Software and hardware requirements

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

  • 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 on all workspaces being used (located under the Edit Workspace area).
    •      
  • 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).      

Installation

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 setup correctly.
  4. Setup svn2rally.rb to be executed by the Subversion post-commit hook.

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 (mydomain.com).

Install Ruby and the Rally Connector for Subversion

  1. Install the Ruby programming language. As of Rally Connector for Subversion 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), 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 RallyConnectorForSvn-X.X.zip file on your machine into the directory where you want to install the connector. Navigate to the install directory, and extract the RallyConnectorForSvn-X.X.zip file.

If running on Unix, save the RallyConnectorForSvn-X.X.zip file locally on your machine into a directory of your choosing, for example, /opt/Rally. Navigate to the install directory, and extract the 'RallyConnectorForSvn-X.X.zip' 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
   

Setup the config.xml file

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. The tags and their meaning:

  1. <RallyUserName> the Rally user's login name you want to use for the updates in Rally.
  2. <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.
  3. <RallyBaseUrl> the URL used to log into Rally. For most users, the expected URL is rally1.rallydev.com or trial.rallydev.com.
  4. <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;".
  5. <SourceControlUrl> the URL used to reference the Subversion web interface. You may fully qualify the URL with the protocol (http, https, svn, etc). Defaults to "http://" for the protocol if not specified.
  6. <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.
  7. <UserDomain> the domain name of your company. If set, this will map a Subversion author (myuser) to a Rally user (myuser@domain.com). The Rally user is used to populate the Author field when creating the Changeset object.
  8. Optional - <CommitterUserLookupField> the name of a field on the User Object in Rally [9]. When the connector runs, it will attempt 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 will become 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:
    • you have <CommitterUserLookupField>MiddleName</CommitterUserLookupField>
    • the SVN committer is User123
    • the SVN user User123 has a Rally username of user@rallydev.com
    • the MiddleName field for Rally user@rallydev.com is set to user123 (NOTE: It must be lowercase.)
    • the author on changesets in Rally will be set to user@rallydev.com
    • 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.
  9. 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.
    • <Story> This element is used to specify the prefix you use for story artifacts.
    • <Task> This element is used to specify the prefix you use for task artifacts.

Example config.xml file:

<Config>
   <RallyBaseUrl>rally1.rallydev.com</RallyBaseUrl>
   <RallyUserName>email@domain.com</RallyUserName>
   <RallyPassword>password</RallyPassword>
   <RallyWorkspaceName>MyWorkspace</RallyWorkspaceName>
   <RallySCMRepositoryName>MyRepository</RallySCMRepositoryName>
   <SourceControlUrl>localhost:8080</SourceControlUrl>
   <UserDomain>domain.com</UserDomain>
   <CommitterUserLookupField>MiddleName</CommitterUserLookupField>
   <Prefixes>
      <!-- This section is for specifying if you have configured
           Rally to use custom prefixes for the FormattedID's.
           NOTE: If your custom prefix ends with a number,
                 this connector will not function properly.
      -->
      <Defect>DE</Defect>
      <Story>US</Story>
      <Task>TA</Task>
   </Prefixes>
   <Log>
      <FileName>Rally_Connector_Error.log</FileName>
      <Level>0</Level>
   </Log>
</Config>

Test the config 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  
   

Set up Subversion hook

First a note about multiple repositories and multiple 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 checkin comment for "DE10" is not unique, as each workspace could have a "DE10").

The Subversion post-commit hook is set up 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 log file Rally_Connector_Error.log for any errors.

Setting 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 RallyWrapper.sh that contains the command to run the svn2rally script. Ensure you specify the full path to Ruby and the svn2rally.rb file.
      
    #!/bin/sh
    /usr/bin/ruby /opt/integrations/SvnToRally/svn2rally.rb $1 $2
  2. Verify the RallyWrapper.sh file is executable by entering this command:
    chmod u+x RallyWrapper.sh
                 
  3. Go to the Subversion installation "hooks" subdirectory (the name should be something like <YourReposityPath>/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/RallyWrapper.sh "$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
                 

Setting 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/modify the post-commit.bat file and add the lines below:
    SET REPOS=%1
    SET REV=%2
    C:\SvnToRally\RallyWrapper.bat %REPOS% %REV%

Tips

  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 the connector outputs by including the following information in the config.xml file:
     
       ....
       <Log>
          <FileName>Rally_Connector_Error.log</FileName>
          <Level>0</Level>
       </Log>
    </Config>
     

    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
  3. Beta-test scripts
    The following two scripts, post-commit and RallyWrapper.sh (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.
    #!/bin/bash
    #------------------------------------------------------------------------
    # SCRIPT:
    #       post-commit
    # PURPOSE:
    #       To be placed in the "hooks" directory of an SVN repository,
    #       where it will be invoked upon an SVN commit.
    #------------------------------------------------------------------------

    #------------------------------------------------------------------------
    # Define the variables needed.
    #
    MY_install=/tmp/SvnToRally
    MY_logfile=${MY_install}/Rally_Connector_Error.log
    MY_wrapper=${MY_install}/RallyWrapper.sh
    MY_svn2rally=${MY_install}/svn2rally.rb

    #------------------------------------------------------------------------
    # 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
    fi
    MY_repo_name="${1}"
    MY_commitrev="${2}"

    #------------------------------------------------------------------------
    # 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]#

    #!/bin/bash
    #------------------------------------------------------------------------
    # SCRIPT:
    #       RallyWrapper.sh
    # PURPOSE:
    #       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
    fi

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

    MY_repo_name="${1}"
    MY_commitrev="${2}"
    MY_svn2rally="${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/RallyWrapper.sh /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.
English

Feedback

Please send us your feedback regarding our help site. For feedback regarding the Rally product, click here to open a support case or click here to submit a new feature request
English
By submitting this form, you accept the Mollom privacy policy.
© 2014 Rally Software Development Corp | Legal