Jenkins Installation & User Guide

Connector download

Log in to the CA Agile Central Community for support of this and all of our connectors. The CA Agile Central Community is your one stop shop for self service and support. Accessing the CA Agile Central Community is quick and easy:

  • Navigate to the CA Community.
    • If it's your first time to the site, click Don't have an account yet? Create one now!
    • Complete the self-service registration form to be automatically logged into the CA Agile Central Community.
  • In the Community, click the profile drop-down (top-right), and select My Downloads. The connector will be listed for eligible users.

Overview

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

The CA Agile Central plugin for Jenkins enables teams to use CA Agile Central 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 CA Agile Central.

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

When used in conjunction with a Version Control System (VCS) and a CA Agile Central VCS connector, the Jenkins plugin will link Builds to ChangeSets as well. The CA Agile Central VCS connector will parse the commit message, and if CA Agile Central 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 CA Agile Central. The result is traceability from Story/Defect → ChangeSet → Build.

Once Builds and BuildDefinitions are populated in CA Agile Central, there is a build status indicator in the upper-right corner of the CA Agile Central 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

  • The following Jenkins versions are supported: Jenkins v1.642.4 - 1.651.2. (Due to a defect in Jenkins versions 1.598 to 1.609, these versions cannot be used with this plugin on any of the platforms listed below.)
  • Testing has been done on Ubuntu, CentOS, Mac OS X Yosemite, and Windows Server 2012. These operating systems are recommended.

SCM System Support

  • SCM systems are necessary in order to link ChangeSets to Build objects in CA Agile Central, 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).
  • NOTE*** The Jenkins plugin does not support SSO at this time

Installation

Installation of the plugin follows these basic steps:

  1. Install the Ruby Runtime plugin into Jenkins (one time)
  2. Install the CA Agile Central 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 CA Agile Central (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 a prior version to the 4.0.1 version

If you were using the Jenkins plugin for CA Agile Central v4.0.0 or below, you should follow these steps before installing v4.0.1 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 CA Agile Central plugin for Jenkins from Jenkins
  3. Follow the instructions below to install the plugin into Jenkins

Installing the plugin into Jenkins on Linux and Mac OS X

  1. In Jenkins, go to Manage Jenkins → Manage Plugins.
  2. Click the Available tab.
  3. Find the ruby-runtime plugin by scrolling to it or using the search box in the right hand corner.
  4. Click the checkbox next to the ruby-runtime (tested with ruby-runtime 0.12 ).
  5. Click the Install without restart button.
  6. Confirm that the ruby-runtime plugin is now listed under the Installed plugins tab. If it is not, you may need to restart Jenkins.
  7. In the Jenkins web interface, go to Manage Jenkins → Manage Plugins.
  8. Select the Advanced tab on the Manage Plugins page.
  9. Under Upload Plugin, click Choose File and navigate to the file jenkins-rally-build-publisher.hpi.
  10. Click Upload to upload the file to Jenkins.
  11. Restart Jenkins to ensure you changes have been applied.
  12. You should now see the CA Agile Central Plugin on the Manage Plugins page under the Installed tab in Jenkins.

Installing the plugin into Jenkins on Windows Server 2012

  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 CA Agile Central 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 CA Agile Central Build Publisher section, complete the following fields:
    • CA Agile Central Server: Enter rally1.rallydev.com in the text box. If you are evaluating CA Agile Central, enter trial.rallydev.com. If you are running an On-Premises instance, enter the name of your CA Agile Central server.
    • CA Agile Central Username and CA Agile Central Password: The username and password for a CA Agile Central user with access to the workspace in which you want to publish Jenkins build results.
  3. If you access CA Agile Central through a proxy server, click Advanced in the CA Agile Central 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 CA Agile Central. Every project in CA Agile Central 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 CA Agile Central, 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 CA Agile Central Build Publisher option.
  3. In the CA Agile Central Build Publisher section of the page, enter the name of the CA Agile Central 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). Known issue: If publishing to a sub project the top level project will be entered for project. The plugin will display the following error if sub project is referenced: ERROR: [Rally Publisher] Unable to post Build info to Rally for Test1 build #35, unable to find default project SubProj1
  4. Click Save on the configuration page.

The next time the job runs, the plugin will search for a BuildDefinition in CA Agile Central 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 CA Agile Central and linked to this BuildDefinition.

Repeat these steps as necessary to configure additional Jenkins jobs to publish results to other CA Agile Central 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 CA Agile Central

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 CA Agile Central 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. CA Agile Central connector detects the change
  3. CA Agile Central VCS Connector updates CA Agile Central with change info and...
    • Creates a new SCM Repo in CA Agile Central (if needed)
    • Creates a ChangeSet object, with child Change objects in CA Agile Central
    • 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 CA Agile Central detects a new build has completed
  7. The Jenkins plugin for CA Agile Central detects a new build has completed
  8. The Jenkins plugin for CA Agile Central updates CA Agile Central 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 CA Agile Central and, if so, links the Build to it

Object Model

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

Historical version highlights

  • Context identification parameter added.
  • Global settings retained and available restarting Hudson.
  • Support of BuildDefinition and Build objects in Rally.
  • Support for Hudson versions through 1.381.
  • Support for Maven2 project types in Hudson.
  • Support for Git and Perforce as SCM options.
  • Proxy settings for Rally are persisted
  • Duration field in Build objects populated with Jenkins provided value.
  • Added debug flag.

Revision history

  • 4.0.1 18-May-2016
    • Fixes:
      • SSL error connecting to Agile Central caused by older ruby-runtime-plugin.
  • 4.0.0 16-November-2015
    • Enhancements:
      • Brand redesign.
  • 3.0.6 25-February-2015
    • Known issues:
      • The following error is received when entering sub project in Build Configuration:

        ERROR: [Rally Publisher] Unable to post Build info to Rally for Test1 build #35, unable to find default project SubProj1

      • Plugin does not translate Chinese characters for Project name correctly.
English

Feedback

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.