jenkinsci / themis-plugin

Themis plugin for Jenkins

Themis Plugin for Jenkins

A Jenkins plugin to communicate with a Themis instance. It can send report files to be analyzed by Themis and send a refresh request for a project.

Usage

Create a Themis instance

In global configuration (“Manage Jenkins” ⇒ “Configure System”), add a Themis instance in the Themis configuration section. You need to fill the following fields:

• instance name: the name of the instance, used to identify it if there are several instances.
• URL: the base url of your Themis instance (e.g., “https://themis.example.com”).
• API key: a Themis API key, generated from the administration page of your Themis instance. Used for authentication.

Refreshing Themis

The action will send a request for refreshing the project, but will not wait for its completion. You should thus check your Themis instance to see the refresh status. By default errors will not mark the build as failed, but you can change this behavior by checking the “Error fails build” checkbox.

Freestyle project

In the configuration of your job, add the post-build action “Refresh Themis Project”. Select the Themis instance where the project to refresh is located, then enter the project key, which is available in the project administration page of Themis.

Pipeline

The Themis refresh step is available in pipeline mode:

themisRefresh(instanceName: 'Some instance', projectKey: 'key')

If you want errors to fail the build, add the failBuild parameter, set as true.

Sending report files

The action will gather report files (e.g., test coverage reports) to Themis. You need to specify the Themis instance to use, the key of the source that was analyzed by the reports, and a list of report files.

Report files have a type and paths. If several paths are required to match all the files for a type, you can add several report files with the same type or use a single report file with all the paths separated by commas. Paths can match several files using ant-style wildcards (e.g., “target/**/*.xml”).

By default errors will not mark the build as failed, but you can change this behavior by checking the “Error fails build” checkbox.

Freestyle project

In the configuration of your job, add the post-build action “Send report files to Themis”. Select the Themis instance and enter the source key. You can then add as many report files as needed.

Pipeline

You can send report files in a pipeline job using the themisReport function:

themisReport(instanceName: 'Some instance', sourceKey: 'key', reports: [[type: 'type1', path: 'path'], [type: 'type2', path: 'path']])

Reports are specified as a list of maps, each containing a type (key type) and a path (key path).

If you want errors to fail the build, add the failBuild parameter, set as true.

⚠ Retrieving SCM version

To properly analyze the reports, Themis requires the SCM version. In a freestyle project it is automatically retrieved from environments variable. Due to limitations of pipeline, these environment variables are not set in a pipeline project and you will need to manually add it in the environment. This can be done using the withDev step (recommended) or the environment directive.

For git:

withEnv(["GIT_COMMIT=${sh(returnStdout: true, script: 'git rev-parse HEAD').trim()}"]) {
    themisReport(…)
}

For SVN:

withEnv(["SVN_REVISION=${sh(returnStdout: true, script: 'svn info --show-item last-changed-revision .').trim()}"]) {
    themisReport(…)
}

Proxy

The plugin uses the Jenkins proxy configuration, in the “Advanced” tab of the “Manage plugins” configuration page. Authentication, HTTPS, and exclusions are all supported.

Changelog

1.4:

• Add Jacoco to the list of supported tools
• Fix an issue that could occur if report files archiving failed

1.3:

• Add a button to test connection with Themis instance in global configuration

1.2.3:

• Modify the version of workflow step api to be more inclusive

1.2.1:

• Fix a bug where old commit ID was sent

1.2:

• Add a post build action and a step to send report files to Themis

1.1:

• Add support for http proxy

1.0:

• Initial release