Jenkins Installation & User Guide

Print this topicEmail this topic
Version Type Files
3.0.6 All Platforms Jenkins Plugin 3.0.6
2.4.1 All Platforms Jenkins Plugin 2.4.1

Overview

Jenkins Cl (formerly Hudson) is an application for building/testing projects continuously and monitoring executions of externally-run jobs.

The Rally plugin for Jenkins enables teams to use Rally to see the build status for the projects they are working on, display charts on build health, and trace code commits to builds. The plugin achieves this by populating build data into Rally.

Each Jenkins job corresponds to a BuildDefinition object in Rally, which is given the name of the Jenkins job. When a Jenkins job completes, it is represented by a Build object in Rally. Builds are automatically linked to their BuildDefinition in Rally as well. A workspace and project in Rally can have one or more associated BuildDefinitions.

When used in conjunction with an SCM system and a Rally VCS connector, the Jenkins plugin will link Builds to ChangeSets as well. The Rally VCS connector will parse the commit message, and if Rally artifacts are mentioned (such as DE27), the VCS connector will link the artifact to the the ChangeSet for the change committed to the SCM system. When the next Jenkins build occurs, the Jenkins plugin will link the ChangeSet to the Build in Rally. The result is traceability from Story/Defect → ChangeSet → Build.

Once Builds and BuildDefinitions are populated in Rally, 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/project.

Additionally, custom dashboards can be built to display Build Health and Traceability apps to manage the health of continuous build/test pipelines across the enterprise.

This install guide includes:

Software Requirements

Jenkins support

  • Jenkins 1.42 or higher is recommended
  • Testing has been done on versions between v1.42 through v1.596
  • Note: Yosemite OS X customers please use Jenkins version v1.42 to v1.597 as newer versions are unsupported with this OS

SCM System Support

  • SCM systems are necessary in order to link ChangeSets to Build objects in Rally, so that Stories/Defects can be traced to Builds.
  • Certified to support Git, Subversion, and Mercurial.
  • A Jenkins plugin for the SCM system must be installed in Jenkins. Jenkins has a built-in Subversion plugin, and optional plugins for Git and Mercurial are available on the Jenkins CI site.
  • The Rally VCS connector for the appropriate SCM must be installed in order for ChangeSets to be populated in Rally (Git, Subversion, Mercurial).

Installation

Installation of the plugin follows these basic steps:

  1. Install the Ruby Runtime plugin into Jenkins (one time)
  2. Install the Rally Build Notifier plugin into Jenkins (one time)
  3. Configure the plugin’s global settings (one time)
  4. Configure a Jenkins job to publish build results into Rally (for each job)

Jenkins Setup

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.

Upgrading the plugin from v2.4 or below

If you were using the Jenkins plugin for Rally v2.4 or below, you should follow these steps before installing v3.0 of the Jenkins plugin:

  1. Make a note of all of your Jenkins settings, at both the global and job levels. You will need to re-enter these after installing the new plugin.
  2. Uninstall the Rally plugin for Jenkins (v2.4 or below) from Jenkins
  3. Follow the instructions below to install the plugin into Jenkins

Installing the plugin into Jenkins

  1. In the Jenkins web interface, go to Manage Jenkins → Manage Plugins.
  2. Select the Advanced tab on the Manage Plugins page.
  3. Under Upload Plugin click Choose File and navigate to the file ruby-runtime-rally.hpi.
  4. On the Installing Plugins/Upgrades status page you should see a Success message after the plugin has finished installing.
  5. In the Jenkins web interface, go to Manage Jenkins → Manage Plugins.
  6. Select the Advanced tab on the Manage Plugins page.
  7. Under Upload Plugin click Choose File and navigate to the file jenkins-rally-build-publisher.hpi.
  8. Click Upload to upload the file to Jenkins.
  9. If Jenkins instructs you to restart or you encounter missing fields in the next step of these instructions you may need to restart Jenkins.
  10. You should now see the Rally Plugin on the Manage Plugins page under the Installed tab in Jenkins.

Configuration

Once the plugin is installed, it needs to be configured at the global level, as well as once for each Jenkins job.

Configuring Global Settings

  1. In the Jenkins web interface, go to Manage Jenkins → System Configuration.
  2. 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.
  3. 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 the 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

Configuring a Jenkins job to publish build results

Any free-style or maven2 job in Jenkins can be configured to publish a BuildDefinition & Build 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, then click Configure in the upper-left.
  2. In the Post-build Actions section of the page click the Add post-build action drop-down and select the Rally Build Publisher option.
  3. In the Rally Build Publisher section of the page, enter the name of the Rally workspace and project in which the build results are to be published ( note that the user you entered in the global config must have permissions to the workspace you specify).
  4. 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 a green circle for successful builds and a red square for failing builds.

Viewing Build Information in Rally

Viewing Build Status by Project

Any project that has Build Definitions and Builds will display a status indicator in the top right. If there are any failing builds, the indicator will be a red square, and if all builds are successful the indicator will be a green circle.

Clicking on the indicator will display all of the Build Definitions and the latest build status for each build. Clicking on the build will take you to the Jenkins job page associated with the build, so you can research the build status in more detail.

Note that the build status indicator allows project scoping. For example, all Build statuses will be shown for sub-projects of the selected project if down-scoping is enabled in the project picker. If a BuildDefinition is disabled then it will not show in the drop-down list until a new build is posted to it.

Viewing Build Health in Reports

Build health reports are available in the Reports → Reports page in Rally. Specifically, Build Health and Build Health by Iteration are available.

Creating Custom Build Dashboards

When building custom dashboards, you can select from four different Build dashboard apps, including Build Health, Build Health by Iteration, Build Traceability, and Build Dashboard.

Troubleshooting

Use the following command to start Jenkins in debug mode and view messages:

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

Ensure that the Rally Username and Password entered into the Global Configuration for the plugin are correct and haven’t changed.

SubSystem Interaction

Several subsystems need to interact in order for the Jenkins plugin to perform properly. The diagrams below describe how the systems interact.

  1. User checks in code and provides an Artifact ID (such as DE27)
  2. Rally connector detects the change
  3. Rally VCS Connector updates Rally with change info and...
    • Creates a new SCM Repo in Rally (if needed)
    • Creates a ChangeSet object, with child Change objects in Rally
    • Links the ChangeSet object to the artifact named in the check-in (DE27)
  4. A Jenkins build is triggered either automatically or manually
  5. The build is performed in Jenkins and completes
  6. The Jenkins plugin for Rally detects a new build has completed
  7. The Jenkins plugin for Rally detects a new build has completed
  8. The Jenkins plugin for Rally updates Rally and...
    • Creates a new Build Definition (if needed)
    • Creates a new Build and links to Build Definition
    • Checks if the ChangeSet associated with the Build is in Rally and, if so, links the Build to it

Object Model

Once the Jenkins plugin for Rally has run, the relationship between the data objects inside Rally is the following:

English

Feedback

Need more help? The Rally Success Community is your one-stop shop for self-service and support. To submit feedback or cases to Rally Support, find answers, and collaborate with others, please join us at rallydev.force.com/answers.
© 2015 Rally Software Development Corp | Legal