Configure Issue Tracker Integration

R2026b

Configure the Issue Tracker if you want to enable the creation of tickets in your bug tracking tool (BTT) from the Polyspace^® Access™ web interface. Polyspace Access supports integration with the Jira, Redmine, and Polarion™ bug tracking tools.

Configure your BTT by using the .env file for your Docker installation. After configuring your BTT, stop and remove containers by running docker compose down. Then, run docker compose up to apply your BTT changes.

To enable the issue tracker, add issuetracker to the COMPOSE_PROFILES variable and set ISSUETRACKER_PROVIDER to one of jira, redmine, or polarion.

Configure Jira Bug Tracking Tool

You can configure the Issue Tracker for use with Jira Server, Jira Cloud, or Jira Data Center. In the Issue Tracker settings section of your .env file, specify these variables:

Variable Description

JIRA_TYPE Jira deployment type, specified as server, cloud, or dataCenter.

Variable	Description
`JIRA_TYPE`	Jira deployment type, specified as `server`, `cloud`, or `dataCenter`.
`JIRA_URL`	URL of the Jira instance for your organization. For example, `https://jira.mycompany.com`. If your Jira instance is configured using HTTPS, see Add BTT Instance Configured Using HTTPS.
`JIRA_AUTHN_METHOD`	Authentication method. If `JIRA_TYPE` is set to `server`, specify either `cookie` or `oauth1`. If `JIRA_TYPE` is set to `cloud` or `dataCenter`, specify either `oauth1` or `oauth2`.

JIRA_URL

URL of the Jira instance for your organization. For example, https://jira.mycompany.com.

If your Jira instance is configured using HTTPS, see Add BTT Instance Configured Using HTTPS.

JIRA_AUTHN_METHOD Authentication method. If JIRA_TYPE is set to server, specify either cookie or oauth1. If JIRA_TYPE is set to cloud or dataCenter, specify either oauth1 or oauth2.

OAuth 1.0 Settings

If you use OAuth 1.0a as an authentication method, your Jira administrator must first create an application link in Jira. You can use OAuth 1.0a with Jira Server, Jira Cloud, and Jira Data Center.

For an OAuth 1.0a application link, the Jira administrator specifies an application URL (the URL for Polyspace Access) and generates an RSA public-private key pair. For more information, see Step 1: Configure Jira in the Atlassian OAuth documentation.

Variable	Description
`JIRA_AUTHN_OAUTH1_CONSUMER_KEY`	Consumer key value that your Jira administrator entered when configuring the application link in Jira, such as `OauthKey`.
`JIRA_AUTHN_OAUTH1_CALLBACK_URL`	The application URL as specified in Jira, for example `https://access-machine.company.com:9443`.
`JIRA_AUTHN_OAUTH1_PRIVATE_KEY`	Path to the private key file that your Jira administrator generated when configuring the application link in Jira, for example `/local/polyspace_access/jira_privatekey.pem`.

Note

The hostname that you specify when you create the Jira private key must match the hostname that you use in your Polyspace Access URL. If the hostnames do not match, for example if you use localhost instead of the hostname in your Polyspace Access URL, you might see a user authentication error when you attempt to create Jira tickets from Polyspace Access.

OAuth 2.0 Settings

If you use OAuth 2.0 as an authentication method, your Jira administrator must first create an application link in Jira. You can use OAuth 2.0 for Jira Cloud and Jira Data Center. For an OAuth 2.0 application link, the Jira administrator specifies a callback URL and permissions. For more information, see OAuth 2.0 (3LO) apps.

Variable Description

JIRA_AUTHN_OAUTH2_CLIENT_ID Client ID in the settings of your OAuth 2.0 application link.

JIRA_AUTHN_OAUTH2_CLIENT_SECRET Secret value in the settings of your OAuth 2.0 application link.

Variable	Description
`JIRA_AUTHN_OAUTH2_CLIENT_ID`	Client ID in the settings of your OAuth 2.0 application link.
`JIRA_AUTHN_OAUTH2_CLIENT_SECRET`	Secret value in the settings of your OAuth 2.0 application link.
`JIRA_AUTHN_OAUTH2_REDIRECT_URL`	OAuth 2.0 callback URL that Jira redirects to after authentication. Specify a link in this format: `hostname/issuetracker/authn/oauth2/callback` Here, `hostname` is your Polyspace Access URL. For example, if your Polyspace Access URL is `https://access-machine.company.com:9443`, your OAuth2 Redirect URL would be `https://access-machine.company.com:9443/issuetracker/authn/oauth2/callback`.

JIRA_AUTHN_OAUTH2_REDIRECT_URL

OAuth 2.0 callback URL that Jira redirects to after authentication. Specify a link in this format: hostname/issuetracker/authn/oauth2/callback

Here, hostname is your Polyspace Access URL. For example, if your Polyspace Access URL is https://access-machine.company.com:9443, your OAuth2 Redirect URL would be https://access-machine.company.com:9443/issuetracker/authn/oauth2/callback.

If JIRA_AUTHN_METHOD is set to oauth2 and JIRA_TYPE is set to cloud, also set these variables:

Variable Description

Variable	Description
`JIRA_AUTHN_OAUTH2_SCOPES`	Jira API permissions that are enabled in your application link, specified as a comma-separated list in brackets. At a minimum, include these permissions: `[read:jira-work, read:jira-user, write:jira-work]`
`JIRA_AUTHN_OAUTH2_SITE_URL`	The URL of the Jira Cloud instance for your organization, for example, `https://mycompany.atlassian.net`.

JIRA_AUTHN_OAUTH2_SCOPES

Jira API permissions that are enabled in your application link, specified as a comma-separated list in brackets.

At a minimum, include these permissions:

[read:jira-work, read:jira-user, write:jira-work]

JIRA_AUTHN_OAUTH2_SITE_URL The URL of the Jira Cloud instance for your organization, for example, https://mycompany.atlassian.net.

Limitations

Polyspace Access does not support creating BTT tickets with custom required fields, except for fields that are all numeric values, string only values, or single-select values.
After a user logs into Jira from Polyspace Access and starts creating Jira issues, they remain logged into their Jira session until the session expires.
In Jira Software version 8.4 and later, do not enable dark feature. See Enable Dark Feature in Jira.

Configure Redmine Bug Tracking Tool

To configure the Issue Tracker for use with Redmine, in the Issue Tracker settings of the .env file, specify these variables:

Variable Description

Variable	Description
`REDMINE_URL`	URL of the Redmine instance for your organization, for example, `https://redmine.mycompany.com`. If your Redmine instance is configured by using HTTPS, see Add BTT Instance Configured Using HTTPS.
`REDMINE_API_KEY`	API access key of a Redmine account with admin-level privileges. Create a dedicated API account and grant it admin-level privileges for the projects that you want to integrate with Polyspace Access. To obtain the API key, log into your instance of Redmine as the API account, click My account in the upper-right corner, then, in the right pane, click Show under API access key. The Issue Tracker does not validate the API key. Check periodically that the API key has not expired or become invalid.

REDMINE_URL

URL of the Redmine instance for your organization, for example, https://redmine.mycompany.com.

If your Redmine instance is configured by using HTTPS, see Add BTT Instance Configured Using HTTPS.

REDMINE_API_KEY

API access key of a Redmine account with admin-level privileges. Create a dedicated API account and grant it admin-level privileges for the projects that you want to integrate with Polyspace Access.

To obtain the API key, log into your instance of Redmine as the API account, click My account in the upper-right corner, then, in the right pane, click Show under API access key.

The Issue Tracker does not validate the API key. Check periodically that the API key has not expired or become invalid.

Limitations

Polyspace Access does not support the creation of BTT tickets that have required custom fields, except if the fields are all numeric values or string only values.
To create a Redmine ticket from Polyspace Access, the username used to log into Polyspace Access must match the username of a Redmine account.
Redmine tickets that users create from Polyspace Access can be populated only with default field values. Some of the ticket field values that a user selects in Polyspace Access might not match the field values of the Redmine ticket.

Configure Polarion Bug Tracking Tool

To configure the Issue Tracker for use with Polarion, in the Issue Tracker settings of the .env file, specify these variables:

Variable Description

Variable	Description
`POLARION_URL`	URL of the Polarion instance for your organization, for example, `https://polarion.mycompany.com`. If your Polarion instance is configured by using HTTPS, see Add BTT Instance Configured Using HTTPS.
`POLARION_API_KEY`	Personal access token of a Polarion account with admin-level privileges. The Polarion API requires admin-level access. Create a dedicated API account with admin-level privileges and use its personal access token for this field. To obtain the personal access token, log into your instance of Polarion as the API account, click My account in the settings menu, and then select Personal Access Token from the toolbar. On this page in your settings, you can create a new access token, or delete or renew an active access token. The Issue Tracker does not validate the personal access token. Check periodically that the API key has not expired or become invalid.

POLARION_URL

URL of the Polarion instance for your organization, for example, https://polarion.mycompany.com.

If your Polarion instance is configured by using HTTPS, see Add BTT Instance Configured Using HTTPS.

POLARION_API_KEY

Personal access token of a Polarion account with admin-level privileges. The Polarion API requires admin-level access. Create a dedicated API account with admin-level privileges and use its personal access token for this field.

To obtain the personal access token, log into your instance of Polarion as the API account, click My account in the settings menu, and then select Personal Access Token from the toolbar. On this page in your settings, you can create a new access token, or delete or renew an active access token.

The Issue Tracker does not validate the personal access token. Check periodically that the API key has not expired or become invalid.

Limitations

Polyspace Access does not support the creation of BTT tickets that have custom fields. When creating a ticket from Polyspace Access, a form shows the minimum required fields to create a Polarion ticket. After you create the ticket, you can fill out additional fields in Polarion.
To create a Polarion ticket from Polyspace Access, the username used to log into Polyspace Access or the email address associated with the Polyspace Access account must match the username or email address of a Polarion account.

Add BTT Instance Configured Using HTTPS

If your BTT instance is configured to use HTTPS, add the BTT SSL certificate to the gateway CA file. If you configured the gateway to use HTTPS, the BTT SSL certificate might already be included in your CA file. See Gateway Settings.

For instance, on Linux^®, to add BTT certificate btts_cert.pem to trust store file trust_store.pem, use this command:

cat trust_store.pem btts_cert.pem > combined_cert.pem

The command combines the contents of the two files into the output file combined_cert.pem. If you use a self-signed certificate to configure HTTPS, add the BTT certificate to the self-signed certificate. When adding the root certificate and any intermediate certificates to the CA file, confirm each certificate is in PEM format.

To complete the configuration, set GATEWAY_SSL_CA_FILE in the .env file to point to the combined certificate file and restart the services:

docker compose down
docker compose up -d

If you did not configure the gateway with HTTPS, set GATEWAY_SSL_CA_FILE to the path of the BTT SSL certificate.

Configure Issue Tracker Integration

Configure Jira Bug Tracking Tool

OAuth 1.0 Settings

OAuth 2.0 Settings

Limitations

Configure Redmine Bug Tracking Tool

Limitations

Configure Polarion Bug Tracking Tool

Limitations

Add BTT Instance Configured Using HTTPS

See Also

Topics