Jenkins integration

Integration with Jenkins enables you to incorporate data from your Jenkins CI pipelines into your application delivery process.

Note: For details on integrating a non-Jenkins CI server, see Install and configure the plugin on your CI server.

Plugin overview

The CI plugin enables ALM Octane to integrate with a CI server.

For a list of available plugins and their locations, see CI and CD server integrations.

The CI plugins provide the following capabilities:

  • Retrieve and display the build pipelines that run on the CI server

  • Trigger pipeline runs on the CI server

  • Retrieve build run results, test run results, and commit information from the CI server

  • Retrieve code coverage reports from a Jenkins CI server

  • Trigger UFT One test execution on a Jenkins CI server

Note: To integrate with Jenkins, do not install the ALM Octane CI plugin on the Jenkins server. For details, see Upgrade to the Application Automation Tool plugin.

Back to top

Supported plugins

You connect your Jenkins server with the Application Automation Tools plugin to ALM Octane. You can then track and analyze builds, automated test results, and SCM data.

For the latest list of supported plugins, see Dependencies.

Follow these guideline when preparing the Jenkins integration:

  • If you are working with ALM Octane, make sure that you work with the plugin version 5.1 or later of this plugin, and that you do not have the ALM Octane CI plugin installed. For more details, see Install or upgrade the plugin.
  • For ALM Octane-UFT One integration, make sure that you work with version 5.2 or later of this plugin and with UFT 12.50 or later.
  • For ALM Octane to collect LoadRunner Enterprise test results from pipeline runs, make sure that you work with version 5.2 or later of this plugin. For details, see LoadRunner Enterprise.

  • ALM Octane can display a pipeline's structure only if it is built using one of the following:

    • The built-in Jenkins upstream/downstream mechanism
    • The Multijob plugin
    • The Parameterized plugin

Back to top

Prerequisites

Make sure you meet the necessary requirements.

  • For setting up an integration with a CI server, see Prerequisites.

  • For integrating ALM Octane with Jenkins:

    Prerequisite Details
    Java version 8 or later Verify your Java version.
    ALM/Quality Center client The ALM/Quality Center client must be installed on the machine that runs the tests. To check if you have a client installed, follow the instructions on this page: http://<your_server>:8080/qcbin/TDConnectivity_index.html.
    Node in Jenkins

    For running file system scenarios with UFT One, you need to set up a node in Jenkins. For details, see Create an execution node.

    JQuery Plugin and a plugin for publishing test results

    For building and tracking pipelines in ALM Octane, install the following:

    • JQuery Plugin 1.7.2-1 or later (Required to enable the integration)
    • A plugin that enables publishing test results. For example, JUnit Plugin 1.10 or later, or NUnit plugin (Required to enable ALM Octane to collect your automated test results)
    Jenkins Git plugin

    For ALM Octane integration with UFT One, install Jenkins Git plugin (version 2.4.4 or later).

Back to top

Install or upgrade the plugin

In your Jenkins server's user interface, open the plugin management area and upload the Application Automation Tools plugin.

To install the plugin:

  1. Go to the Jenkins Server home page.

  2. Click Manage Jenkins.

  3. Click Manage Plugins, select the Advanced tab, and scroll down to Upload Plugin.

  4. Browse to the plugin file that you downloaded and click Upload.

  5. Select the option to restart Jenkins when installation is complete and no jobs are running.

Note: If you activate or deactivate the plugin at any time after installation, you must restart your CI server.

Upgrade to the Application Automation Tool plugin

If you are currently using the ALM Octane CI plugin, you must remove it and replace it with the Application Automation Tools plugin.

  1. Go to the Jenkins Server home page.

  2. Click the Manage Plugins.

  3. Select the Installed tab and uninstall the ALM Octane CI plugin.

  4. Restart Jenkins.

  5. Install the Application Automation Tools plugin, version 5.1 or later.

  6. Restart Jenkins.

Back to top

Configure connection to the ALM Octane server

This section describes how to set up the connection between ALM Octane and the Jenkins machine.

Before you configure the connection:

  1. Ask the ALM Octane shared space admin for an API access client ID and client secret. The plugin uses these for authentication when communicating with ALM Octane. The access keys must be assigned with the CI/CD Integration role in all the relevant workspaces. For details, see API access.

  2. If your network requires a proxy to connect to the Internet, set up the proxy configuration:

    Action Details
    Define the HTTP Proxy Configuration

    Go to Manage Jenkins > Manage Plugins > Advanced and define the necessary HTTP Proxy Configuration details:

    • If the ALM Octane server is located outside of the Jenkins server's private network, define the proxy server's details to enable Jenkins to communicate with ALM Octane.
    • If the ALM Octane server and the Jenkins server are both in the same private network (common if you are using ALM Octane on premises), instruct Jenkins not to use the proxy to reach ALM Octane: Add ALM Octane's URL to the No Proxy Host list (using ALM Octane's Fully Qualified Domain Name (FQDN).
      Note: In this case, you may still need the proxy server details defined to enable Jenkins to access other external resources, such as Git.
    Test that Jenkins can now reach ALM Octane

    Click the Advanced button beneath the HTTP Proxy Configuration details. Enter ALM Octane's URL using its Fully Qualified Domain Name (FQDN), and click Test URL.
    Restart the Jenkins server Restarting is necessary for the plugin to use the new proxy settings.

  3. Decide which Jenkins user ALM Octane should use to execute jobs on the server.

    Caution: It is strongly recommended that you set this user’s permissions to the minimum required for this integration. The Jenkins user must have the following permissions:

    • Job Build: For working with ALM Octane pipelines

    • Job Create, Delete, and Read: For ALM Octane-UFT integration

    • Credentials create and Update: If your Git repository requires credentials

Configure the connection

To set up the connection between Jenkins and ALM Octane:

  1. Go to the Jenkins Server home page.
  2. Click the Manage Jenkins link in the left pane.
  3. Click Configure System.
  4. Scroll down to the ALM Octane CI section.
  5. Click Add ALM Octane server.

  6. Follow the instructions on the screen to complete the configuration:

    Field Details
    Location

    Enter the URL of the ALM Octane server using its fully qualified domain name (FQDN).

    Use the following format: http://<ALM Octane hostname / IP address> {:<port number>}/ui/?p=<shared space ID>

    For example, in this URL, the shared space ID is 1002: http://myServer.myCompany.com:8081/ui/?p=1002

    If the port is 80, you do not need to add the port number.

    You can copy the URL from the address bar of the browser in which you opened ALM Octane. For example, if this is your workspace URL, copy the full address: https://almoctane.saas.microfocus.com/ui/?p=100101/1002#/
    Client ID and Client secret

    Make sure to enter the exact text without leading or trailing spaces.
    Jenkins user

    • Enter the Jenkins user ALM Octane should use to execute jobs on the server. Make sure the user can log in to Jenkins and has the minimum permission required for this integration:

      Job Build permissions.

      Note: We recommend that you specify a Jenkins user for ALM Octane. If you do not specify a Jenkins user, ALM Octane uses the Anonymous user, and is limited to the Anonymous user permissions.

    • In some environments, you might want users in ALM Octane to only have access to a subset of jobs in specific workspaces. To define a user in Jenkins that only has access to a subset of jobs, click Advanced, and enter one or more sets of users per workspace in the Jenkins user for specific workspaces box. When creating a pipeline, you only see the jobs that can be accessed by the Jenkins user assigned to the current workspace. For details, see the plugin help.
  7. To connect additional ALM Octane shared spaces, click Add ALM Octane server and enter the details.
  8. Click Test Connection to validate the configuration.
  9. Click Submit to save your changes.

Post setup actions

After the connection is set up, you can do any of the following:

  • Create ALM Octane pipelines from the ALM Octane user interface. To do this, define a CI server in the ALM Octane settings and then create pipelines. For details, see Prerequisites.
  • Create ALM Octane pipelines from the Jenkins user interface. For details, see Create and configure pipelines on Jenkins.
  • Set up ALM Octane integration with UFT One. To do this, define a CI server in the ALM Octane settings and then create a testing tool connection. For details, see Set up UFT One integration.
  • Set up a security integration with Fortify Software Security Center (SSC), to display data on vulnerabilities using ALM Octane. For details, see Set up an integration with Fortify.

Back to top

Move an existing CI server to a new address

If you move your Jenkins server and reinstall the plugin, use the following steps to adjust the plugin's configuration and continue working with your existing pipelines.

To configure the Jenkins plugin to work with existing ALM Octane pipelines:

  1. Get the plugin instance ID originally used to set up the CI server on ALM Octane:

    1. In ALM Octane, in Settings > Spaces, select a workspace.

    2. Click the DevOps tab. On the left side of the pane, and select CI servers.

    3. In the grid, locate the Instance ID column and copy your CI server's Instance ID.

  2. In Jenkins, update the new plugin to use the original instance ID.

    1. Click Manage Plugins in the left pane.

    2. Click Configure System.

    3. Scroll down to the ALM Octane CI configuration area.

    4. Click Show plugin instance ID.

    5. In the Instance ID box, enter the Instance ID you copied from ALM Octane earlier.

Back to top

Create and configure pipelines on Jenkins

Before you can create an ALM Octane pipeline, make sure you have configured the connection to your ALM Octane server (above).

To create an ALM Octane pipeline in Jenkins:

  1. Go to the Jenkins Server home page.
  2. Click on the job that you want to use as the root job for your pipeline.
    Note: Select a job that is not already part on an existing ALM Octane pipeline.
  3. In the menu in the left pane, click ALM Octane Pipelines.
  4. Click Create Pipeline.

  5. Select the configuration of the ALM Octane server configured in Jenkins.

  6. Enter the details for the pipeline:

    1. Provide a name for the pipeline.
    2. The Workspace list displays all of the workspaces on the ALM Octane server you configured in the ALM Octane CI section. Select a workspace for your pipeline.
    3. The Release list displays the releases available in the workspace you selected. Optionally, select a release to associate with your pipeline.
    4. The Milestone list displays the milestones available in the release you selected. Optionally, select a milestone to associate with your pipeline.
  7. Click Create.

Caution: If you delete a pipeline, all its labels and configuration information will be lost.

To edit the pipeline and configure pipeline steps:

  1. Go to the Jenkins Server home page.
  2. Click on a job that is included in an existing ALM Octane pipeline.
  3. In the menu in the left pane, click ALM Octane Pipelines. The page for editing pipelines opens.
  4. You can edit the pipeline’s name, workspace, release, or milestone. Note that if you change a milestone or release, a new set of runs is created on ALM Octane, with a new run history.

  5. For a job that runs tests, configure test and environment details. For details, see Create and configure pipelines.
    Note:

    • A Jenkins job may be included in a pipeline more than once. When you configure a Jenkins job, this affects all of the relevant steps in the ALM Octane pipeline.
    • To dynamically set environment tags during the build run, based on build parameter values, configure the pipeline in ALM Octane.
  6. Click Apply.

For details on tracking your pipelines in ALM Octane, see Run pipelines.

To configure a pipeline with parameterized tests (optional):

  1. If your tests are parameterized, each run result is displayed in ALM Octane as a separate test. To see run results under a single test with a separate run for each parameter value, add a parameter to your pipeline job called octane_test_result_name_run_regex_pattern.

  2. Define its value using a regular expression which splits the test name into two parts, one to be used as the test name, and the other (representing the parameter value) to be used as the external run ID.

    For example, if your test uses the format Test name [parameter1,parameter2], define the regex as \[,*\]

  3. In ALM Octane when you run the pipeline with parameters, define the parameter name as octane_test_result_name_run_regex_pattern. Define its value as the regex you defined in the job.

    In the above example, the result are two test runs whose name is the test name, and whose external run IDs are parameter1 and parameter2.

Back to top

Trigger suite runs from Jenkins

You can use automated test execution modes in the Jenkins plugin, to enable Jenkins to trigger suite runs. This can be useful in a number of scenarios. For example:

  • Defining a schedule in Jenkins (if you do not use Functional Test Execution).

  • Triggering suite runs from an auto action in a release process.

  • Triggering suite runs in ALM Octane as a step in a bigger pipeline.

The following modes are available:

Suite context

You provide suite IDs. The Jenkins job creates a suite run for each one, and triggers the test runs as if you ran the suite from ALM Octane.

The job does not have to be defined as a pipeline in ALM Octane. To see and analyze results, go to the suite run.

Pipeline context

You provide suite IDs. The Jenkins job fetches all tests from the selected suites. The job runs them by triggering the correct sub-job based on the assigned test runner.

The job should be defined as a pipeline in ALM Octane. To see and analyze results, go to the Pipeline module.

For details, see Application Automation Tools.

Back to top

Troubleshoot the Jenkins integration

If you are working with version 5.1 or later of this plugin, make sure you do not have the old ALM Octane Plugin installed on your Jenkins server.

The following table provides suggestions for solving integration issues:

Issue Possible solutions
Test Connection fails Verify that you are not using an outdated sdk version of the CI plugin.
Cannot run pipelines from ALM Octane. The Run button is unavailable.
  • The Jenkins server might be down, or it is not communicating with ALM Octane.
  • If this occurred after upgrading from the ALM Octane Plugin: Make sure that in the plugin's ALM Octane CI configuration, you updated the Instance ID with the ID defined in ALM Octane for the CI server.
When creating a new pipeline in ALM Octane, the message "Failed to fetch Jenkins job" is displayed in the Job field after you select a CI server.
  • This happens when a Jenkins job indirectly calls itself. Try creating the pipeline from Jenkins. In this case, the log files do not indicate any problem. Version 5.2 of this plugin introduced a fix for this issue.
  • See the next issue, "Errors occur when ALM Octane requests something from Jenkins".

Errors occur when ALM Octane requests something from Jenkins. When running a pipeline from ALM Octane, the error message is displayed: "Run pipeline: an Error occurred while running the pipeline”

When creating a new pipeline in ALM Octane, the message "Failed to fetch Jenkins jobs - Error 403 forbidden" is displayed in the Job field after you select a CI server.

This is an issue with the permissions of the Jenkins user that ALM Octane uses to execute jobs on the server.

In the Jenkins configuration, in the ALM Octane CI section, define a Jenkins user. This user must have Job Build permissions.

When creating a new CI server in ALM Octane, the Jenkins server is not displayed in the list of connected servers even though Test Connection on Jenkins worked. Make sure that the Jenkins proxy settings are correct and that you restarted the Jenkins server after changing proxy settings. For details, see Prerequisites.
Test results from the pipelines are not reflected in ALM Octane. Test results from Maven jobs are not reported to ALM Octane if the job is under a folder. Free style and pipeline jobs report results as expected. Version 5.2 of this plugin introduced a fix for this issue.

Using log files to troubleshoot

Jenkins sends various events and data to ALM Octane. For example: Start job, Finish job, SCM data, test results.

When an error occurs, check the communication between Jenkins and ALM Octane.

To help troubleshoot, you might want to check the log file on the Jenkins server for things like connectivity issues or security issues.

The log files are located in the following locations:

  • Jenkins system logs: http://<Jenkins url>/log/all
  • Plugin logs: http://<Jenkins url>/userContent/nga/logs/nga.log

Understanding the plugin's log messages

  • At the end of a successful flow, Jenkins sends: done, left to send 0 events. For example:

    • INFO - EventsClient: sending events [job\-name:STARTED] to 'http://localhost:8080'...
    • INFO - EventsClient: sending events [job\-name:FINISHED] to 'https://mqast010pngx.saas.mf.com'...
    • INFO - EventsClient: ... done, left to send 0 events
    • INFO - TestDispatcher: There are pending test results, connecting to the MQM server
    • INFO - TestDispatcher: Successfully pushed test results of build job-name#10

  • When the ALM Octane server is not available, log messages may look like this:

    ERROR - BridgeClient: connection to MQM Server temporary failed: authentication error com.hp.mqm.client.exception.AuthenticationException: Authentication failed: code=503; reason=Service Unavailable

  • When an error occurs in the Jenkins -> ALM Octane communication, log messages may look like this:

    ERROR - EventsClient: max number of retries reached TestDispatcher: There are pending test results, but we are in quiet period

Back to top

Troubleshoot creating pipelines

Use this table to solve your integration issues.

Issue Possible solutions
Error when trying to create a pipeline: Unable to create pipeline

Make sure the workspace you selected is included in the list of workspaces defined for the access keys that you used to connect the ALM Octane CI to ALM Octane.

If you still encounter an error, select a different workspace, or ask an ALM Octane shared space admin to add the workspace to the list. For details, see API access.
Error when trying to configure a job: Unable to retrieve job configuration

The pipeline containing this job might have been created in ALM Octane in a workspace that is not accessible from the ALM Octane CI plugin. Make sure that the workspace is included in the list of workspaces defined for the access keys that you used to connect the ALM Octane CI to ALM Octane.

If you still encounter an error, ask an ALM Octane shared space admin to add the workspace to the list. For details, see API access.

Back to top

See also: