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 function 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.

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')]
        )
      }
    }
  }
}

Integrate with Jenkins¶