Jenkins Installation & User Guide
The Rally connector for Jenkins (formerly Hudson) is a plugin that enables teams to see the build status for the projects they are working on and display charts and reports on build health in Rally. It will monitor executions of repeated jobs, such as building a software project or jobs run by cron. Among those things, current Jenkins focuses on the following two jobs:
- Building and testing software projects continuously, just like CruiseControl or DamageControl. Jenkins provides an easy-to-use continuous integration system, making it easier for developers to integrate changes to the project and making it easier for users to obtain a fresh build. The automated, continuous build increases the productivity.
- Monitoring executions of externally-run jobs, such as cron jobs and procmail jobs, even those that are run on a remote machine. For example, with cron, all you receive are regular emails that capture the output, and you must review them to find any errors. Jenkins keeps those outputs and makes it easy for you to notice when something is wrong.
This install guide includes:
- Install the connector
- Jenkins setup
- Configure the connector
- Troubleshoot the connector
- Revision history
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 that is linked to the BuildDefinition .
A workspace and project 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 displays the most recent build status for the jobs associated with the currently selected workspace and project.
Basic installation steps
- Edit existing configuration files (for current plugin users only).
- Install the plugin into Jenkins.
- Configure the plugin.
- Configure a Jenkins job to publish build results.
Supported Hudson versions
- Hudson versions 1.350 through 1.395 were tested. After 1.395, we recommend switching to Jenkins.
- We have discovered problems with 1.398 on the Hudson side of the source branch, while the plugin works fine with the Jenkins side of the source branch (most recently tested 1.404).
Supported SCM systems
The Rally connector for Jenkins supports Subversion, Git, and Perforce. Jenkins has a built-in Subversion plugin. Git and Perforce plugins are available as optional plugins that must be installed by the Jenkins administrator. The Rally connector for Jenkins has been tested with version 1.1 of the Git plugin and versions 1.1.9 and 1.1.10 of the Perforce plugin. Consideration for support of other Jenkins SCM plugins is under review.
Download the connector
Connector download: Jenkins-2.4.1_1.zip
There is also an attached diagram, HudsonSCM.pdf.zip, which illustrates the relationship and interaction of the different subsystems (it assumes you are using Perforce). The Rally connector for Perforce (the trigger code) parses the commit message and, if Rally artifacts are mentioned (for example, DE27), the plugin updates their status and creates a Rally changeset object. The next time Jenkins/Hudson runs a job configured to publish results to Rally (through the Rally Build Notifier plugin), the Perforce plugin in Jenkins/Hudson makes the changeset information available to Jenkins/Hudson, which in turn passes it to the Rally Build Notifier. The Rally Build Notifier then creates a Build object in Rally and links the appropriate changeset object to it. Currently, we have only upgraded Jenkins/Hudson to support the new build and changeset features.
Install the connector
- A working version of Jenkins installed and running. Rally has 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.
- Your Jenkins host must be running Java 6. Because the Rally connector plugin was built using Java 6, we have seen some problems with the Jenkins configuration page not displaying on systems running Java 5.
- A Rally subscription. You will need to know the URL for the Rally server hosting your subscription (for example rally1.rallydev.com), and 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-Premises customer and are not using https, please Contact Support.
- Obtain the Rally connector for Jenkins plugin here.
If the plugin 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.
If you are using a previous version of the Rally connector for Jenkins plugin, 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.
Install the plugin into Jenkins
If you are unfamiliar with Jenkins plugins, consult the Jenkins documentation for plugins to become familiar with the concept and how to install plugins in Jenkins.
- In the Jenkins web interface, go to Manage Jenkins → Manage Plugins.
- Click Choose File and navigate to the file rally-hudson-plug-in.hpi.
For recent versions of Jenkins, select the Advanced tab on the Manage Plugins page.
- Click Upload to upload the file to Jenkins.
- Restart Jenkins.
You should now see the rally-hudson-plugin on the Manage Plugins page in Jenkins.
Configure the connector
- In the Jenkins web interface, go to Manage Jenkins → System Configuration.
- In the Rally Build Publisher section, complete the following fields:
- Rally Server: Enter rally1.rallydev.com in the text box. If you are evaluating Rally, enter trial.rallydev.com. If you are running an On-Premises 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. 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, enter Jenkins in this field.
- 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.
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.
- Go to the Jenkins job you want to configure to publish build results to Rally, then click Configure in the upper-left.
- In the Post-build Actions section of the page, ensure that the Rally Build Publisher checkbox is selected.
- 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.
- Click Save on the configuration page.
The next time the job runs, the plugin 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 projects (in the upper-right corner, just below the Search textbox) displayed as green for successful builds and red for failing builds.
Troubleshoot the connector
- 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:
java -Drally.debug="true" -jar jenkins.war --httpPort=9000
- Console output
If you are having trouble with the plugin, 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, 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.
- Password changes
Changes to your Rally password on the configuration page are not reflected retroactively in the configuration files of the preexisting Jenkins jobs. Stopping Jenkins and restarting it is not sufficient to propagate the change. Details:
- The credentials information is not written or read to and from a global configuration file, but to and from individual jobs' configuration files. Here is an example of the location of a job's configuration file: /var/lib/jenkins/jobs/job1.
- Verify that Rally information, including workspace, project, username, and password are correct. The respective tags are found under:
Rally credentials are specified in the tags shown in the example below:<publishers>
If the values are incorrect, modify and save the configuration file, and restart Jenkins.<username>email@example.com</username>
- Contact support
Click the Contact Support link in the footer of any page in Rally.
- 2.4.1—Added debug flag.
- 2.1.0—Fixed defect: Duration field in Build objects was always zero. Fixed defect: Proxy settings for Rally were not persisted.
- 2.0.0—Added support for Git and Perforce as SCM options. Added support for Maven2 project types in Hudson. Added support for Hudson versions up through 1.381.
- 1.3.0—Support of new build objects in Rally. Refer to Installation Guide for more information.
- 1.2.0—Added Trial as an available option in the configuration. Fixed issue where the global settings were not restored after restarting Hudson.
- 1.1.0—Added the ability to change the context for where Hudson is running.
- 1.0.0 —Initial GA Release currently being tested with Hudson 1.1.x.