Jenkins Installation & User Guide

Print this topicEmail this topicSave as PDF

Installation & User Guide

1. Introduction

The Rally Connector for Jenkins (formerly Hudson) enables teams to see the build status for the projects they're working on and display charts and reports on build health in Rally.

The Connector is a Jenkins plug-in that publishes the results of a build to a Rally project. Each Jenkins job corresponds to a BuildDefinition object in Rally, which is given the name of the Jenkins job. Each build for that job creates a Build object in Rally, linked to the BuildDefinition.

A particular workspace/project combination in Rally can have one or more associated BuildDefinitions, and there is a build status indicator in the upper right corner of the Rally user interface that shows the most recent build status for the jobs associated with the currently selected workspace and project.

2. Pre-installation requirements

  1. Jenkins installed and running. We have tested with a sample of Jenkins/Hudson versions as recent as 1.386 and as far back as 1.350. You will need to know the hostname and port for your Jenkins host.
  2. Your Jenkins host must be running Java 6. Because the Rally Connector plug-in was built using Java 6, we have seen some problems with the Jenkins configuration page not displaying on systems running Java 5.
  3. A Rally subscription. You will need to know the URL for the Rally server hosting your subscription, for example rally1.rallydev.com, along with a Rally username and password for your subscription. The connector assumes that you connect to the Rally server over https. If you are an on-premise customer and are not using https, please contact Rally Support.
  4. Obtain the Rally Connector for Jenkins plug-in here. (at the bottom of the page).

If the plug-in will be connecting to Rally through a proxy server, you will also need to know the name and port number of the proxy, and username and password for authentication if the proxy requires it.

3. Installation

Basic Installation Steps

  1. Edit existing configuration files (for current plug-in users only).
  2. Install the plug-in into Jenkins.
  3. Configure the plug-in.
  4. Configure a Jenkins job to publish build results.

3.1 Edit existing Jenkins configuration files

If you are using a previous version of the Rally Connector for Jenkins plug-in, you will need to edit the configuration files for each job. Previously, the job-specific configuration required you to specify a BuildDefinition ID, which was stored in the config.xml file for the job. That parameter has been removed, and replaced with parameters for workspace and project name. To make the edits, cd to your Jenkins jobs directory (jobs subdirectory in your Jenkins home directory, such as ~/.Jenkins/jobs). You will see a subdirectory for each job, and in each subdirectory is a config.xml file. Search for the <builddefinitionid> tag in each of those config.xml files, and remove it.

3.2 Install the plug-in into Jenkins

If you are unfamiliar with Jenkins plug-ins, consult the Jenkins documentation for plug-ins to become familiar with the concept and how to install plug-ins in Jenkins.

  1. In the Jenkins web interface, go to Manage Jenkins → Manage Plug-ins.
  2. Click the Choose File button and navigate to the file rally-hudson-plug-in.hpi. For recent versions of Jenkins, you will have to select the Advanced tab on the Manage Plug-ins page.
  3. Click Upload to upload the file to Jenkins.
  4. Restart Jenkins. You should now see the rally-hudson-plug-in on the Manage Plug-ins page in Jenkins.

3.3 Configure the Jenkins plug-in

  1. In the Jenkins web interface, go to Manage Jenkins → System Configuration. Scroll down to the Rally Build Publisher section and fill in the following fields:
    • Rally Server: Normally, you should enter rally1.rallydev.com in the text box. If you are evaluating Rally, enter trial.rallydev.com. If you are running an on-premise instance, enter the name of your Rally server.
    • Rally Username and Rally Password: the username and password for a Rally user with access to the workspace in which you want to publish Jenkins build results.
    • Hudson Host: Specify the hostname and port for your Jenkins server (such as machinename:9000)
    • Hudson Context: Normally this field is blank. Also, if you are running Jenkins through Winstone, leave the field blank. If you are running a default installation of Jenkins in a container such as Tomcat, then you should enter Jenkins in this field.
      step1
  2. If you access Rally through a proxy server, click Advanced... in the Rally Build Publisher Proxy Settings section to display the fields used to specify the proxy:
    • Proxy Server: The name or IP address of the proxy server.
    • Proxy Port: The port number to use on the proxy server.
    • Proxy Username (optional): A valid username for the proxy server, if it requires authentication.
    • Proxy Password (optional): A valid password for the proxy server, if it requires authentication.
      step2

3.4 Configure a Jenkins job to publish build results

Any free-style or maven2 job in Jenkins can be configured to publish to a BuildDefinition in Rally. Every project in Rally has one or more BuildDefinitions that can be used to publish a build status indicator.

In Jenkins:

  1. Go to the Jenkins job you want to configure to publish build results to Rally, and click the Configure link in the upper-left.
  2. In the Post-build Actions section of the page, ensure that the Rally Build Publisher checkbox is checked.
  3. In the Rally Build Publisher section of the page, enter the name of the workspace and project in which the build results are to be published.
  4. Click Save on the configuration page.
    step3

The next time the job runs, the plug-in will search for a BuildDefinition in Rally with the same name as the Jenkins job. If it is not found, one will be created. Each time the job runs, a Build object will be created in Rally and linked to this BuildDefinition.

Repeat these steps as necessary to configure additional Jenkins jobs to publish results to other Rally projects.

You should now see the build status indicator in the Rally project(s) (in the upper right corner, just below the Search textbox) displayed as green for successful builds and red for failing builds.

4.0 Supported SCM Systems

The Rally Connector for Jenkins now supports Subversion, Git and Perforce. Jenkins itself has a built-in Subversion plug-in. Git and Perforce plug-ins are available as optional plug-ins that must be installed by the Jenkins administrator. The Rally Connector for Jenkins has been tested with version 1.1 of the Git plug-in and versions 1.1.9 and 1.1.10 of the Perforce plug-in. Consideration for support of other Jenkins SCM plug-ins is under review.

5.0 Troubleshooting

  • Turn on debug output
    For debugging purposes, this plugin will look at a Java property called rally.debug which can be specified on the command line used to invoke the Jenkins server. If the value of this variable is "true", the plugin will output additional debug information. For example, this command line can be used to start the Jenkins server with the debug flag set to "true":
  • View console output
    If you are having trouble with the plug-in, view the console output from your job or the application server log that is running Jenkins. To view the console output from the job, select a build number in the Jenkins web interface, and then click Console Output on the resulting Jenkins page.
  • Tomcat server log
    If you are using Tomcat, navigate to [TOMCAT_INSTALL_DIR]/logs/catalina.out to view the application server log.

6.0 Contacting Support

Submit a Rally Support case from Rally by navigating to Help & Training and click the Contact Support tab or visit http://www.rallydev.com/support.jsp.

7.0 Known issues

  1. DE13653: After upgrading the Jenkins plugin from 1.640 to 1.643, the Rally Build Notifier section is no longer available.
    Symptom details:
    • After upgrading, verify the Rally plugin is in the list of currently installed plugins; create a new free style job; on the job configuration page go to Post-build Actions; notice that Jenkins recognizes the Rally plugin; the Rally Build Notifier dropdown value is available; when Rally Build Notifier is selected, the selection does not stick; there is no place to specify Rally Workspace and Project.

    Workaround details:
    1. Locate the config.xml file for the job you created. For example, if your job is called job123, then its location follows this general format: "C:\Users\myuser\.jenkins\jobs\job123"
    2. Edit this file, and you should see a line like this:
      <builders/>
      Replace the above builders tag line with the following 17 lines (using your workspaceName, projectName, username, password, etc.)
      <publishers>
      <com.rallydev.integration.build.hudson.RallyBuildNotifier>
      <workspaceName>W1</workspaceName>
      <projectName>P1</projectName>
      <service>
      <username>user@co.com</username>
      <password>secret</password>
      <host>rally1.rallydev.com</host>
      <version>1.21</version>
      <port>-1</port>
      <pluginName>Hudson Plugin</pluginName>
      <pluginVersion>2.1</pluginVersion>
      <secure>true</secure>
      <proxyPort>-1</proxyPort>
      </service>
      </com.rallydev.integration.build.hudson.RallyBuildNotifier>
      </publishers>
    3. Now stop Jenkins and restart it.
    4. At this point you should be able to see the Rally Build Notifier settings.
© 2012 Rally Software Development Corp | Legal