Jenkins integration

ALM Octane incorporates data from your Jenkins CI pipelines into your application delivery process, helping you analyze quality and progress.

Connecting your Jenkins server with the Micro Focus Application Automation Tools to ALM Octane enables you to track and analyze builds, automated test results, and SCM data.

Supported plugins

If you have these Jenkins plugins, ALM Octane supports them:

  • MultiJob Plugin 1.15 or later
  • Maven Plugin 2.5 or later
  • Parameterized Trigger Plugin 2.25 or later
  • Matrix Job Plugin 1.4 or later
  • Pipeline Plugin (enabling Pipeline as Code). ALM Octane creates a single pipeline step for each Jenkins job. Steps and stages inside a job are not recognized.

Follow these guideline when preparing the integration:

  • If you are working with ALM Octane, make sure that you work with 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 and configure the ALM Octane CI plugin on your CI server.
  • For ALM Octane-UFT 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 Performance Center test results from pipeline runs, make sure that you work with version 5.2 or later of this plugin.
  • 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

The following are the prerequisites for integrating ALM Octane with Jenkins.

  • Java version 8 or higher. To verify your Java version, go to http://www.java.com/en/download/installed.jsp.
  • ALM/Quality Center client installed the machine that will run the tests. To check if you have a client installed, follow the instructions on this page: http://<your_server>:8080/qcbin/TDConnectivity_index.html
  • For running UFT tests from ALM install the ALMClient in common registration mode by accessing the following link from an Internet Explorer browser on the UFT machine: http://<almserver>:8080/qcbin/start_a.jsp?Common=true
  • For running file system scenarios with LoadRunner or UFT, you need to set up a node in Jenkins. For details, see Create an execution node.
  • For building and tracking pipelines on ALM Octane:

    • 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, NUnit plugin, and so on (Required to enable ALM Octane to collect your automated test results.)
  • For ALM Octane integration with UFT:

    • Jenkins Git plugin (version 2.4.4 or later)

Back to top

Upgrading to the Micro Focus Application Automation Tool plugin

If you already set up your CI server to work with ALM Octane using the ALM Octane CI plugin, you must first remove it before using the Micro Focus Application Automation Tool for Jenkins.

  1. Go to the Jenkins Server home page.
  2. Click the Manage Plugins link in the left pane.
  3. Select the Installed tab and uninstall the ALM Octane CI plugin.
  4. Restart Jenkins.
  5. Install the Micro Focus Application Automation Tool plugin, version 5.1 or later.
  6. Restart Jenkins.
  7. Configure the connection to your ALM Octane server.
  8. Configure the Jenkins or TFS plugin to work with existing ALM Octane pipelines.

Back to top

Configure the connection to your 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 the CI/CD Integration role in all relevant workspaces. For details, see Set up API access.
  2. If your network requires a proxy to connect to the Internet, set up the proxy configuration.

    1. 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 (FDQN)).
        Note: In this case, you may still need the proxy server details defined to enable Jenkins to access other external resources, such as Git.
    2. Test that Jenkins can now reach ALM Octane:

      1. Click the Advanced button beneath the HTTP Proxy Configuration details.
      2. Enter ALM Octane's URL (using its FQDN) and click Test URL.
    3. Restart the Jenkins server so the plugin uses the new proxy settings.

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

    Caution: We strongly recommend setting this user’s permissions to the minimum required for this integration. The Jenkins user must have the following permissions:

    • For working with ALM Octane pipelines: Job Build.
    • For ALM Octane-UFT integration: Job Create, Delete, and Read.
    • If your Git repository requires credentials, Credentials create and update permissions are also required.

Configure the connection

  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:

    • For Location, enter the URL of the ALM Octane server, using its fully qualified domain name (FQDN). Use the following format (port number is optional): 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
      Tip: You can copy the URL from the address bar of the browser in which you opened ALM Octane.
    • When entering the Client ID and Client secret, make sure to enter the exact text without leading or trailing spaces.
    • For Jenkins user, enter the Jenkins user ALM Octane will 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.
      We strongly recommend specifying 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.
  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.

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

Back to top

Create and configure ALM Octane 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. Enter the details for the pipeline:

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

Caution: If you delete a pipeline, all its labels and configuration information are 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, or release.
  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.

Back to top

Troubleshoot the Jenkins-ALM Octane 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
Cannot run pipelines from ALM Octane. The Run button is disabled.
  • 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. For details, see Upgrading to the Micro Focus Application Automation Tool plugin.
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. For details, see Install and configure the ALM Octane CI plugin on your CI server.

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 Install and configure the ALM Octane CI plugin on your CI server.
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 connectivity issues, security issues, and so on.

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 and configuring ALM Octane 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 Set up 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 Set up API access.

Back to top

See also: NOTE TO WRITER: Add your link/cross-reference in a bullet list after the snippet. Apply the SeeAlso style to the <ul> tag.