Jira

P4 Code Review's Jira integration allows code reviews and committed changes to be associated with Jira issues, making it easy to reference associated issues, and see the state of a code review or committed change within Jira. To associate a code review with a Jira issue, include a Jira issue identifier in the review's description, for example SW-1234. P4 Code Review links to the Jira issue and creates a link within the Jira issue back to the code review in P4 Code Review. Multiple Jira issues can be included in the changelist description. As a code review progresses, P4 Code Review updates each associated Jira issue with the review's current status.

For instructions on how to configure basic Jira integration, see Jira integration.

Additionally, if you have the P4 Defect Tracking Gateway (P4 DTG) configured to integrate Perforce jobs with Jira issues. P4 Code Review can be configured to add a link to a Perforce job within a Jira issue. Perforce job links are created when a new Jira or job is created or updated. This gives you direct access to the Perforce job from a link in the Issue Links section of the Jira issue.

For instructions on how to configure Jira integration and Perforce job links, see Jira integration and Perforce job links.

If you make a configuration change, P4 Code Review will not use it until the configuration cache has been reloaded, this forces P4 Code Review to use the new configuration. You must be an admin or super user to reload the P4 Code Review config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Jira integration

Basic Jira integration enables:

  • In P4 Code Review: Hyperlinks are created to Jira issues referenced in changelist descriptions and review descriptions. Jira links in comments are only supported in the classic review page. For example, if Jira issue SW-1234 is found in the text, the text is linked to the Jira issue in P4 Code Review.

    For the legacy Jira linkify, the links for Jira issues in changelist descriptions, review descriptions, and comments open in a new tab in the web browser.

  • In the Issue Links section of the Jira issue: Creates hyperlinks to the associated P4 Code Review changelist (commit) and review pages.

P4 Code Review fetches Jira project identifiers using a worker, once per the worker process' lifetime. See Worker configuration. New Jira projects will not auto-link to Jira until the project identifiers have been updated. By default, project identifiers are updated once every ten minutes.

Prerequisites for basic Jira integration

  • The P4 Code Review workers must be working, see Worker status.
  • The Jira module must be enabled, see Enabling the Jira module.

  • The Jira user specified in the Jira module configuration must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    To troubleshoot the permissions:

    1. Log in to Jira as the P4 Code Review Jira user.

    2. Retrieve an issue.

    3. Try to create a link.

When a user is provided in the Jira module configuration, P4 Code Review will use HTTP Basic authentication with the provided username and password. If the username is left blank, P4 Code Review will use Bearer authentication with the password (token) instead.

Enabling the Jira module

By default, the Jira module is not enabled. To enable the Jira module, add the following configuration block to your SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'jira' => array(
        'host'         => '', // URL for your installed Jira web interface (start with https:// or  http://)
        'api_host'     => '', // URL for Jira API access, 'host' is used for Jira API access if 'api_host' is not set 
        'user'         => '', // Jira Cloud: the username or email address used to connect to your Atlassian account 
                              // Jira on-premises: the username required for Jira API access
                              // Jira on-premises with Personal Access Tokens (PATs): the username must be blank
        'password'     => '', // Jira Cloud: a special API token obtained from https://id.atlassian.com/manage/api-tokens
                              // Jira on-premises: the password required for Jira API access
                              // Jira on-premises with Personal Access Tokens (PATs): the Personal Access Token (PAT) obtained from Jira On-premises. 
        'relationship' => '', // Jira subsection name links are added to defaults to empty, links added to the "links to" subsection
        'ignored_users'=> array(), // Reviews or changes by users specified here are not linked to any Jira issue. 
    ),

  • host: URL for your Jira web interface starting with https:// or http://

    • For example, for a Jira cloud instance it might be: https://my-company-jira.atlassian.net

  • api_host (optional): URL for Jira API access, the host URL is used for Jira API access if api_host is not set.

  • user: The user must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    • Jira Cloud: Username or email address used to connect to your Atlassian account.

    • Jira on-premises: Username for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): The username must be blank.

  • password:

    • Jira Software Cloud: A special API token. To obtain your API token:

      1. Go to API Tokens.
      2. Log in with your Atlassian administrator credentials.
      3. Click Create and name your API token something recognizable, for example swarmjira.
      4. The API token is displayed in a dialog.
      5. Copy the token and paste it into the password configurable. It is a good idea to save the API token somewhere safe in case you need it in the future.

    • Jira on-premises: Password required for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): A Personal Access Token (PAT) obtained from Jira On-premises. For more information about PATs, see Using Personal Access Tokens.

  • relationship: sets which subsection of the Jira Issue Links section P4 Code Review commit, review, and Perforce job links are added to. P4 DTG is required for Perforce job links, see Jira integration and Perforce job links.
    • '' empty: links are added to the links to subsection of Issue Links section of Jira issues. This is the default value.
    • <JobLinksSubsectionName>: creates a new subsection in the Issue Links section of Jira issues. Links are added to this subsection.

    • Existing links are not moved to the subsection defined by the relationship configurable. However, if a link is updated or a new link is added, the link is added to the new subsection. The link is not deleted from its original location.

  • ignored_users: reviews or changes by users specified here are not linked to any Jira issue.

Jira SSL client configuration

If your Jira site certificate is from one of the more common Certificate Authorities (such as the CA used by Jira Software Cloud), the following configuration changes are not usually required.

If your Jira site certificate is not from one of the more common Certificate Authorities, you might need to configure the P4 Code Review http_client_options configuration block in your SWARM_ROOT/data/config.php file.

For example, if your root and intermediate certificates are stored in a pem format file in /path/to/certs/jira.pem, point to the file with:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslcafile'     => '/path/to/certs/jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
        ),
    ),
)

For more information about configuring your Jira HTTP client options, see HTTP client options.

If you need to troubleshoot P4 Code Review's connection with your Jira instance, see P4 Code Review to JIRA Connection Troubleshooting in the Perforce Knowledge Base.

Jira integration and Perforce job links

Jira integration and Perforce job links enable:

  • In P4 Code Review:

    • Creates hyperlinks to Jira issues referenced in changelist descriptions and review descriptions. Jira links in comments are only supported in the classic review page. For example, if Jira issue SW-1234 is found in the text, the text is linked to the Jira issue in P4 Code Review.

    • Creates hyperlink to associated Jira issues on the P4 Code Review job page.

  • In the Issue Links section of the Jira issue:

    • Creates hyperlinks to the associated P4 Code Review changelist (commit) and review pages.

    • When a Perforce job is created, creates a hyperlink to the P4 Code Review job page.

    • If a job is added to a review, creates a hyperlink to the review page.

    • For fixes (p4 fix) to a job, when the job_field is set, creates a hyperlink to the P4 Code Review changelist (commit) page.

    • When P4 DTG replication detects a change to an issue, creates a job link for the associated Jira issue if it does not already exist.

For a summary of Jira integration and Perforce job link workflow, see Jira integration and Perforce job link workflow.

Prerequisites for Jira integration and Perforce job links

Enabling the Jira module

If P4 Code Review fails to add a Perforce job link to a Jira issue because that Jira issue does not exist, the failure is logged by P4 Code Review. P4 Code Review will not try to add the job link to that Jira issue again.

If a Perforce job is updated and the DTG_DTISSUE field value is changed, a job link will be added to the new Jira issue. The Perforce job link will not be removed from the original Jira issue.

By default, the Jira module is not enabled. To enable Perforce job links in Jira issues, add the following configuration block to your SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'jira' => array(
        'host'            => '', // URL for your installed Jira web interface (start with https:// or  http://)
        'api_host'        => '', // URL for Jira API access, 'host' is used for Jira API access if 'api_host' is not set
        'user'            => '', // Jira Cloud: the username or email address used to connect to your Atlassian account 
			          // Jira on-premises: the username required for Jira API access
			          // Jira on-premises with Personal Access Tokens (PATs): the username must be blank
        'password'        => '', // Jira Cloud: a special API token obtained from https://id.atlassian.com/manage/api-tokens 
			          // Jira on-premises: the password required for Jira API access
			          // Jira on-premises with Personal Access Tokens (PATs): the Personal Access Token (PAT) obtained from Jira On-premises. 
        'job_field'       => '', // if P4DTG is replicating Jira issue IDs to a job field, list that field here
        'link_to_jobs'    => false, // set to true to enable Perforce job links in Jira, P4DTG and job_field required  
        'delay_job_links' => 60, // delay in seconds, defaults to 60 seconds 
        'relationship'    => '', // Jira subsection name links are added to defaults to empty, links added to the "links to" subsection
        'ignored_users'   => array(), // Reviews or changes by users specified here are not linked to any Jira issue 
    ),

  • host: URL for your Jira web interface starting with https:// or http://

    • For example, for a Jira cloud instance it might be: https://my-company-jira.atlassian.net

  • api_host (optional): URL for Jira API access, the host URL is used for Jira API access if api_host is not set.

  • user: The user must have permission to view issues, update issues, and add remote links to issues in Jira projects where the Jira integration is required.

    • Jira Cloud: Username or email address used to connect to your Atlassian account.

    • Jira on-premises: Username for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): The username must be blank.

  • password:

    • Jira Software Cloud: A special API token. To obtain your API token:

      1. Go to API Tokens.
      2. Log in with your Atlassian administrator credentials.
      3. Click Create and name your API token something recognizable, for example swarmjira.
      4. The API token is displayed in a dialog.
      5. Copy the token and paste it into the password configurable. It is a good idea to save the API token somewhere safe in case you need it in the future.

    • Jira on-premises: Password required for Jira API access.

    • Jira on-premises with Personal Access Tokens (PATs): A Personal Access Token (PAT) obtained from Jira On-premises. For more information about PATs, see Using Personal Access Tokens.

  • job_field: If P4 DTG is replicating Jira issue IDs to a job field, list the job field here.

  • link_to_jobs:
    • false: disable Perforce job links in Jira. The default setting is false.
    • true: enable Perforce job links in Jira.
  • delay_job_links: delay set in seconds. Sets the delay between a new Jira or job being created or updated, and P4 Code Review adding the job link to the Jira issue. This configurable is used to avoid a race condition between Jira and the P4 Server. By default delay_job_links is set to 60 seconds, if a race condition is experienced increase the delay time.
  • relationship: sets which subsection of the Jira Issue Links section P4 Code Review commit, review, and Perforce job links are added to. P4 DTG is required for Perforce job links.
    • '' empty: links are added to the links to subsection of Issue Links section of Jira issues. This is the default value.
    • <JobLinksSubsectionName>: creates a new subsection in the Issue Links section of Jira issues. Links are added to this subsection.

    • Existing links are not moved to the subsection defined by the relationship configurable. However, if a link is updated or a new link is added, the link is added to the new subsection. The link is not deleted from its original location.

  • ignored_users: reviews or changes by users specified here are not linked to any Jira issue.

Jira SSL client configuration

If your Jira site certificate is from one of the more common Certificate Authorities (such as the CA used by Jira Software Cloud), the following configuration changes are not usually required.

If your Jira site certificate is not from one of the more common Certificate Authorities, you might need to configure the P4 Code Review http_client_options configuration block in your SWARM_ROOT/data/config.php file.

For example, if your root and intermediate certificates are stored in a pem format file in /path/to/certs/jira.pem, point to the file with:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslcafile'     => '/path/to/certs/jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
        ),
    ),
)

For more information about configuring your Jira HTTP client options, see HTTP client options.

If you need to troubleshoot P4 Code Review's connection with your Jira instance, see P4 Code Review to JIRA Connection Troubleshooting in the Perforce Knowledge Base.

Jira integration and Perforce job link workflow

This section describes the workflow for Jira integration and job links in Jira issues when you request a new review from P4V.

The process for adding a Perforce job and creating a review differs for the other clients but the P4 Code Review worker and P4 Defect Tracking Gateway (P4 DTG) workflow is the same.

  1. Create a new Jira issue in your Jira system. P4 DTG detects the new Jira issue and creates a new Perforce job for that Jira issue.
  2. Add the new Perforce job to a pending changelist in P4V. See Add a job to a pending changelist in the P4 Visual Client (P4V) Documentation.
  3. Request a new review for the pending changelist in P4V. See Request a review in the P4 Visual Client (P4V) Documentation.

    P4V passes the review request to the P4 Code Review worker queue. The review request is processed by the next available P4 Code Review worker, the new review is created. P4 Code Review checks its Jira configuration. If the job_field exists in the Perforce job, P4 Code Review adds a link to the new Perforce job in the Issue Links section of the Jira issue.

To check that these steps have been completed and to view the links:

  1. Open the new review. The associated Perforce jobs are displayed on the review page below the review description.
  2. Click the Perforce job link to open the job. The review link is displayed on the job page below the job description.
  3. Click the Details tab on the Perforce job page to view the DTG_DTISSUE field.
  4. Click the Jira link in the DTG_DTISSUE field to view the Jira issue. The review and Perforce job links are displayed in the Issue Links section of the Jira issue page.