Configuration and Features

The behaviour of the Jenkins Integration for Jira app can be customized through configuration and features. Features are essential on or off configuration settings, whereas other configuration settings can contain other bit of information as well.

To customize the configuration of the app, navigate to Settings > Apps > Jenkins Integration > Configuration. Once on the configuration page is open you can access the Features dialog by clicking on the Features button.

Configuration

The configuration page is split into two sections, section named Integration related to the settings for data synchronization and visualization, and once section named Automation related to the settings for the rule engine.

Maximum Builds per Page

This configuration setting allows you to limit the number of builds that are shown on a CI Builds panel, defaults to 100.

Data Retention Period

Retention period, in months, how long jobs and builds that are marked as deleted will be kept in the build cache, defaults to 12.

Jobs are only cleaned up from the build cache if the job itself is marked as deleted, and the latest build in the cache is older than the retention period. Builds are cleaned up from the build cache if the build is marked as deleted, and the timestamp of the build is older than the retention period.

User Id vs Display Name

Some feature of the integration require user information, like triggering a build send who triggered the build to the Jenkins site. This setting allows you to choose whether the user’s display name or id is used.

Parameter Issue Fields

Selected issue fields are passed to Jenkins when triggering a build. Parameter names are created by taking the issue field name and replacing any non alphanumeric character with an underscore. The Jira Integration for Jenkins plugin will match parameters to actual job parameters. This matching is cas-insensitive. For example, if the Fix versions field in enabled, Jira sends a parameter named Fix_versions and Jenkins will match Fix_versions, fix_versions and FIX_VERSIONS.

Issue fields are only send as parameters if the field contains a value for issue where the build was triggered from, and any user field will respect the User Id vs Display Name setting.

Parameter Issue Field Mappers

Natively the parameter issue fields support the creator, assignee, reporter, labels, components, affects and fix versions fields. It can also handle text fields. Custom fields especially can require custom mappings to obtain the value that should be sent to Jenkins when triggering a build. Mappers allow you to specify a specific json path to be used to obtain the value of a field. Each mapper needs to be specified on a new line using format field_id=json_path for example customfield_12345=$.[*].name or project=$.name. Each field can only contain a single String value, if the json path returns multiple values, then they are concatenated using a comma.

Custom mappers take priority over predefined mappers, so using a mapper like project=$.id to send the project id instead of the project name that is send by default.

To check custom mappers, you can provide an issue key to evaluate the parameter fields and mappers.

The Jayway JsonPath implementation is used, refer to its documentation for details on available Operators, Functions, Filter Operators and some examples.

Jira Sync URL

This configuration setting allows you to change the sync URL that Jenkins plugin will use to communicate with Jira. By default, this will be the same as the application URL that is configured in Administration > System > General Configuration. This can be useful if your Jenkins instance should bypass a proxy in order to connect to Jira.

Synchronize All Builds vs. Unknown Only Builds

This configuration setting allows you to specify if all available builds on only unknown builds should be synchronized when synchronizing a Job. The default behaviour is to only synchronize unknown builds to limit the impact on Jenkins. Temporarily selecting the Synchronize all builds option can help to correct synchronized build data, but should be only selected for a limited time. Be aware selecting the Synchronize all builds option will impact the performance of Jenkins as this will increase the number of data requests Jira sends to Jenkins.

Rule Actor

This configuration setting specifies the user that should be used when the rules engines interacts with Jira, to get available projects and issue types, to create, update or transition an issue, etc.

Not setting this may lead to rule failing with a message stating that you don’t have to required permissions to perform the rule action.

Features

There are two types of features, system and site, System features are features that are either enabled or disabled by the app itself and cannot be customized. Site features however are features that administrators of a Jira site can enable or disable to customize the behaviour of the app.

System Features

Site Features