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.

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

Feature Flag Lite Data Center/Server Cloud Description
data-migration Migrate data from Jira Data Center/Server to Jira Cloud.
jira-jenkins-automation Share synchronization events with the Jenkins Integration Automation for Jira add-on to trigger rule executions.
build-info-provider Push build data to Jira when a build is synchronized and has links to valid issues. This data is then made available in the Development Panel.
deployment-info-provider Push build data to Jira when a build is synchronized that represents a deployment to an environment and has links to valid issues. This data is then made available in the Development Panel.

Site Features

Feature Flag Lite Data Center/Server Cloud Description
dynamic-ui-elements When enabled only show UI elements, CI Build Panels, Triggering Builds, Release Report, when the viewing issue or project has one or more builds linked to it. This can be useful in case you have multiple Jira Software projects in Jira but only a subset of them use the Jenkins integration.
disable-issue-indexing Enabling this feature will cause the app to stop automatically updating issue indexes after a build is synchronized and will instead rely on Jira to perform the indexing.
sync-all-builds When enabled all builds available of a job on Jenkins are synchronized every time a job is synchronized, instead of only synchronizing unknown builds.