Jenkins Plugin Installation & User Guide
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.
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.
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
- Connector Download
- Viewing Build Information in CA Agile Central
- Object Model
- Historical version highlights
- Supported versions
- Revision History
- We currently support Jenkins 2.7.1. (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, 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 CA Agile Central VCS connector for the appropriate SCM must be installed in order for ChangeSets to be populated in CA Agile Central (Git, Subversion, Mercurial).
- NOTE*** The Jenkins plugin does not support SSO at this time
Portfolio Type Cannot Match A Standard Entity Name
The connector does not support ambiguous use cases when a custom portfolio item type's name matches a standard entity name. The following example illustrates this: a regular entity in Agile Central → task and a similarly-named portfolio item → PortfolioItem/Task. This above constraint applies even if you reference an ambiguously named item. If you have the situation where a custom portfolio item type has the same name as a existing entity in the Agile Central system, you cannot use this connector.
To download the connector, follow the steps here.
Installation of the plugin follows these basic steps:
- Install the Ruby Runtime plugin into Jenkins (one time)
- Install the CA Agile Central Build Notifier plugin into Jenkins (one time)
- Configure the plugin’s global settings (one time)
- Configure a Jenkins job to publish build results into CA Agile Central (for each job)
Set up CA Agile Central
Verify that your target WorkspaceConfiguration object has BuildandChangsetEnabled set to true.
Your CA Agile Central workspace administrator needs to enable this for your target workspace. If it is not enabled, the connector will work, but you will not be able to see any of the changeset/change information that is associated with your Rally work items (story, defect, task).
The workspace administrator must edit the workspace and do the following:
- Click the Setup icon .
- Click the Workspaces & Projects tab.
- On the Workspaces & Projects summary page, select your workspace.
- From the Actions drop-down, select Edit.
- On the workspace editor, select the checkbox labeled Enable Build and changeset.
- Click Save & Close.
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:
- 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.
- Uninstall the CA Agile Central plugin for Jenkins (Or Rally plugin) from Jenkins
- Follow the instructions below to install the plugin into Jenkins
Installing the plugin into Jenkins on Linux, Mac OS X, and Windows Server 2012
This is also found on the README that comes with the plugin.
- In the Jenkins interface, navigate to Manage Jenkins → Manage Plugins.
- Click the Advanced tab.
- In the Upload Plugin section, click Choose File, and select ruby-runtime-plugin-0.14.hpi.
- Click Upload. Jenkins displays a status screen that shows the plugin installing.
- Install the Jenkins CA Agile Central Publisher plugin following the same steps as above.
- Navigate to the Manage Plugins screen and click the Advanced tab.
- In the Upload Plugin section, click Choose File, then select the agile-central-build-publisher-1.0.1.hpi. Jenkins displays a status screen, which shows the plugin installing.
You may need to restart Jenkins.
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
- In the Jenkins web interface, go to Manage Jenkins → System Configuration.
- 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.
- 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.
- Go to the Jenkins job you want to configure to publish build results to CA Agile Central, then click Configure in the upper-left.
- 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.
- 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
- 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.
Viewing Build Information in CA Agile Central
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.
Use the following command to start Jenkins in debug mode and view messages:
java -Drally.debug="true" -jar jenkins.war --httpPort=9000
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.
Ensure that the CA Agile Central Username and Password entered into the Global Configuration for the plugin are correct and haven’t changed.
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.
|Version||End of Support|
|Jenkins 2.x and later||N/A|
|Jenkins 1.642.4 to 1.651.2||12/1/2016|
|Jenkins 1.42 to 1.642.3||12/1/2016|
|Jenkins 1.41 and below; any Hudson version||4/1/2013|
- 4.0.1 18-May-2016
- SSL error connecting to Agile Central caused by older ruby-runtime-plugin.
- 4.0.0 16-November-2015
- 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.
- The following error is received when entering sub project in Build Configuration:
- Known issues:
||Jenkins Plugin 4.0.1||5/18/2016|
||Jenkins Plugin 4.0.0||11/16/2015|
||Jenkins Plugin 3.0.6||1/28/2015|
|1.0 - 2.4.1||