Skip to content

Integrate with Jenkins

Jenkins is an application that allows you to create and build things at any scale. You can use an instance running on your workstation or an instance running somewhere else.

In the following guide you will update a git repository with its own OpenTestFactory workflow that will run whenever you push changes on your repository.

You need to have access to a repository on a git server, and your Jenkins instance needs to be able to run a job whenever a change occurs on that repository.

You also need to have access to a deployed OpenTestFactory orchestrator instance, with a corresponding token, that is accessible from your Jenkins instance.

You will use the opentf-jenkins-plugin plugin.

Preparation

You need to install and configure the opentf-jenkins-plugin plugin. It is compatible with Jenkins version 2.164.1 or higher.

Installation

Upload the opentestfactory-orchestrator.hpi file in the Upload Plugin area accessible by the Advanced tab of the Plugin Manager in Jenkins configuration:

jenkins-plugin-upload

Configuration

Go the Configure System page accessible in the System Configuration space of Jenkins, through the Manage Jenkins tab:

jenkins-system-configuration

A block named OpenTestFactoryOrchestrator servers will then be available:

jenkins-orchestrator-server

Server id

This ID is automatically generated and cannot be modified.

Server name

Any name you like. You will use it in your pipelines to identify the orchestrator you want to use for your workflows.

Receptionist endpoint URL

The address of the receptionist service of the orchestrator, with its port as defined for the orchestrator instance.

Workflow Status endpoint URL

The address of the observer service of the orchestrator, with its port as defined for the orchestrator instance.

Credential

A Jenkins credential of type Secret text, containing a JWT Token allowing authentication to the orchestrator.

Workflow Status poll interval

This parameter sets the interval between each update of the workflow status. Checking once every 5 seconds is enough, so setting this to 5S is fine. (The trailing S is the unit, seconds here. You can use H for hours and M for minutes. The case is important.)

Workflow creation timeout

Timeout used to wait for the workflow status to be available on the observer after reception by the receptionist. A 30 seconds grace period usually do, so setting this to 30S will do. (The trailing S is the unit, seconds here. You can use H for hours and M for minutes. The case is important.)

You can define multiple orchestrator instances if you interact with multiple orchestrators.

Local deployment

If you are using a local deployment, on your workstation, as for example described in Docker compose deployment, the endpoints will probably look something like the following:

  • Server name: orchestrator
  • Receptionist endpoint URL: http://127.0.0.1:7774
  • Workflow status endpoint URL: http://127.0.0.1:7775
  • Workflow Status poll interval: 5S
  • Workflow creation timeout: 30S

Do not forget to add or specify a credential for your orchestrator token.

Non-local deployment

If you are using a non-local deployment, on your intranet or open to the internet, as for example described in Kubernetes deployment, it will probably looks something like the following.

(In the example below, the HTTP protocol is used. If your deployment is using the HTTPS protocol, which is strongly recommended, define the port values as 443.)

  • Server name: orchestrator
  • Receptionist endpoint URL: http://example.com
  • Workflow status endpoint URL: http://example.com
  • Workflow Status poll interval: 5S
  • Workflow creation timeout: 30S

Do not forget to add or specify a credential for your orchestrator token.

Integration

Now that the plugin is configured, you are ready to integrate your OpenTestFactory orchestrator within your Jenkins CI.

This section assumes a basic knowledge of Jenkins pipelines. See “Getting started with Pipelines” for more information.

Note

There is no required location for your project’s workflows, but it is a good practice to put them in a single location. .opentf/workflows is a good candidate.

Running a workflow

If you have a .opentf/workflows/workflow.yaml orchestrator workflow in your repository, you can use the following Jenkinsfile file to run it each time you make changes to your project.

pipeline {
  agent any
  stages {
    stage('Sanity check') {
      echo 'OK pipelines work in the test instance'
    }
    stage('QA') {
      runOTFWorkflow(
        workflowPathName: '.opentf/workflows/workflow.yaml',
        workflowTimeout: '200S',
        serverName: 'orchestrator',
        jobDepth: 2,
        stepDepth: 3,
        dumpOnError: true
      )
    }
  }
}

The runOTFWorkflow method allows the transmission of a PEaC to the orchestrator for an execution.

It uses 6 parameters:

workflowPathName

The path to the file containing the PEaC on your SCM.

workflowTimeout

Timeout on workflow execution. This timeout will trigger if workflow execution takes longer than expected, for any reason. This aims to end stalled workflows (for example due to unreachable environments or unsupported action calls). It is to be adapted depending on the expected duration of the execution of the various tests in the PEaC.

serverName

Name of the OpenTestFactory Orchestrator server to use. This name is defined in the OpenTestFactory Orchestrator servers space of the Jenkins configuration.

jobDepth

Display depth of nested jobs logs in Jenkins output console. This parameter is optional. The default value is 1.

stepDepth

Display depth of nested steps logs in Jenkins output console. This parameter is optional. The default value is 1.

dumpOnError

If true, reprint all logs with maximum job depth and step depth when a workflow fails. This parameter is optional. The default value is true.

Information

To facilitate log reading and debugging, logs from test execution environments are always displayed, regardless of the depth of the logs requested.

Sharing files and variables

Sometimes, you need to share information—variables or files—for your workflow to work.

For variables, you can do it through the environment statement in your Jenkinsfile file, prefixing them with OPENTF_.

For files, you pass them using the fileResources command parameter.

The following example will run a .opentf/workflows/my_workflow_2.yaml workflow, providing it with a file file (which content will be the one of my_data/file.xml) and two environment variables: FOO and TARGET.

pipeline {
  agent any
  environment {
    OPENTF_FOO = 12
    OPENTF_TARGET = 'https://example.com/target'
  }
  stages {
    stage('Greetings'){
      steps {
        echo 'Hello!'
      }
    }
    stage('QA') {
      steps {
        runOTFWorkflow(
          workflowPathName: '.opentf/workflows/my_workflow_2.yaml',
          workflowTimeout: '200S',
          serverName: 'orchestrator',
          jobDepth: 2,
          stepDepth: 3,
          dumpOnError: true,      
          fileResources: [ref('name': 'file', 'path': 'my_data/file.xml')]
        )
      }
    }
  }
}