LGTM Enterprise 1.19.2

Adding Jira integration

Jira integration allows LGTM Enterprise to automatically open, close and reopen issue tickets in your Atlassian Jira instance. You add this integration by defining a webhook issue tracker provider in LGTM Enterprise, then installing and configuring the LGTM Jira add-on in Jira.

Issue tracker integration is enabled by default for all projects. After you define an issue tracker provider LGTM Enterprise will start opening issue tickets for alerts in all projects, based on the settings in the provider setup. If there are projects for which you don't want issue tickets to be opened, you can turn off issue tracking integration for those projects.

Defining a webhook issue tracker provider

In LGTM Enterprise:

  1. On the Integrations page, click Add new issue tracker provider to display the Add new issue tracker provider page. Webhook is the default option. Leave it selected.

  2. Click Continue to display the Add new Webhook issue tracker provider page.

  3. The Key value is a unique identifier for the issue tracker provider. You can change the default value if you want to.

    If you have previously defined an issue tracker provider and removed it (for example, for testing purposes), and you are now adding a new issue tracker provider for a different instance of Jira, make sure to choose a different key this time. Doing so will cause LGTM Enterprise to start over, opening new issue tickets according to the settings you define.

  4. Change the default Display name if you want the issue tracker provider to have a more descriptive name on the Integrations page.

  5. Clear the Only create issues for new alerts check box if you want to open issue tickets for LGTM analysis alerts that already exist in the current code for projects.

  6. The Webhook URL field will contain the URL to which your webhook receiver expects POST requests to be sent. You will get this URL later in the process, when you add the LGTM add-on to Jira. For now, leave this field empty.

  7. The Secret value allows the receiver to verify the origin of the POST request, and is filled in by default.

    You'll use this value when you come to configure the LGTM add-on in Jira, later in this process.

  8. In the Query filters box, enter a YAML fragment containing include and exclude properties, as required, to define which alerts LGTM should open Jira issue tickets for.

    • By default all alerts are excluded. You must enter a query filter that has at least one include statement to allow tickets to be raised for matching alerts.
    • The filter syntax is the same as is used in the queries section of lgtm.yml project configuration files. For details, see Showing/hiding query results in the user help. However, it is important to note that project configurations that hide certain alerts from being displayed in LGTM Enterprise have no effect on your ability to raise issue tickets for those alerts. With the exception of alerts in excluded files, tickets can be raised for any alert, irrespective of whether they are displayed in LGTM. (For information about how file classification tags are used to exclude alerts that occur in certain types of files, see File classification in the user help.)
    • LGTM Enterprise will begin opening issue tickets for all projects as soon as you add the provider. It's important, therefore, to define a query filter that will avoid unwanted tickets being generated. You can edit the query filter at any time—so if your initial filter is too restrictive you can modify it to generate additional tickets.

    Examples

    - include:

        severity: "error"

        tags: "correctness"

    - exclude: "py/uninitialized-local-variable"

    This filter:

    • Includes alerts with a severity of "error" and a tag of "correctness"
    • Then, from the matched alerts, excludes any that were generated by the query with the ID py/uninitialized-local-variable

    The result is that issue tickets will be opened for all correctness errors, except those generated by the specified query.

    To open tickets for all "error" or "correctness" alerts, the query filter would be:

    - exclude: "*"

    - include:

        severity: "error"

    - include:

        tags: "correctness"

  9. Before you can add the issue tracker provider you need to get some information from Jira. So leave this form open for now, in a separate browser tab, and we'll come back and finish adding the provider a little later in the process.

Installing the LGTM Jira add-on

The Jira integration is configured using the LGTM Jira add-on. To install and configure the LGTM Jira add-on in Jira, you need to have administrator rights in Jira.

  1. In a new browser tab, go to your instance of Jira.

  2. Navigate to the Administration page.

  3. Click Add-ons ( below). This displays the Manage add-ons page ( below).

  4. Click Upload add-on ( above).

  5. Select the add-on jar file that you received from Semmle in the Upload add-on dialog box, and click Upload.

  6. Click Close on the pop-up message that confirms the add-on has been successfully installed:

    Do not close the Manage add-ons page on Jira, as you now need to configure the add-on for LGTM Enterprise.

Configuring the LGTM Jira add-on

On the Jira Manage add-ons tab of the Administator page:

  1. Expand the LGTM for Jira add-on entry if it's collapsed ( below).

  2. Click Configure ( above). This opens the LGTM add-on configuration page:

  3. The Secret value allows the receiver to verify the origin of the POST request. Copy the Secret value from the Secret field for the webhook-based issue tracker provider that you started to define in LGTM Enterprise. For more information on where you can find this value on LGTM Enterprise, see Defining a webhook issue tracker provider.
  4. Enter the Username of the Jira user that LGTM Enterprise will use to open and update tickets.

  5. In the Project field, select an existing Jira project in which you want LGTM Enterprise to create Jira issues. You can also search for a Jira project in this field. Issue tickets for all of your code bases will be created in the same Jira project.

    LGTM Enterprise will create Jira issues of type LGTM alert. This issue type is created automatically in the default issue ticket scheme, and is available to all projects that use this scheme. However, if a project has its own custom scheme then the LGTM alert issue type must be added to that project's scheme.

  6. In the Closed status field, enter the status that your Jira instance applies to issues when they are closed.

    Typically this is Closed.

  7. In the Reopened status field, enter the status that your Jira instance applies to issues when they are reopened.

    Typically this is Reopened.

    LGTM Enterprise reopens an issue ticket when a problem for which it previously opened a Jira ticket (and which was then fixed, causing the ticket to be closed) is reintroduced into the same code. Tickets are only reopened when LGTM determines that this is a reintroduction of a problem and not the same error occurring in a slightly different part of the code (in which case a new issue ticket is opened).

  8. The Priority level of an issue defines its importance in relation to other issues. Select a priority level in the drop-down list.

    Leaving this at --Default-- means that the add-on will use the default priority configured in Jira for new tickets.

  9. Click Save.

  10. Copy the Webhook URL above the Settings list.

  11. Go back to the LGTM Enterprise page that you left open in another browser tab and paste the URL into the Webhook URL field.

  12. Click Add to create the issue tracker provider in LGTM Enterprise.

After you have added the webhook issue tracker provider, installed and configured the LGTM Jira add-on, the issue tracker provider sends POST requests to the specified webhook URL. Each request contains data about an existing LGTM alert for which you want to create an issue ticket.

LGTM Enterprise will now start opening Jira issue tickets for all projects.

If there are projects for which you don't want issue tickets to be opened, you can turn off issue tracking integration for those specific projects—see Turning off issue tracker integration for a project.

Sample Jira issue ticket

In the above example:

  • The project name used by LGTM Enterprise was "AP." Jira created ticket number AP-3276.
  • The name of the LGTM alert is "Self assignment." This is used in the ticket summary and in the description.
  • The code project to which this issue relates is "project-x/project-x.js." This is used in the ticket summary and as a label.
  • The issue type of "LGTM alert" indicates that LGTM Enterprise issued this ticket in Jira.
  • The label "LGTM" is added by LGTM Enterprise. This is added to all issues opened by LGTM.
  • The issue description contains details of the LGTM alert and a link to allow you to click through to view the alert details in LGTM Enterprise.
  • The name of the Jira user account that LGTM Enterprise used to access Jira is "LGTM Jira user."

The other information in this sample issue ticket uses the default values for new tickets, configured in the settings of this instance of Jira.

Changing the issue tracker provider settings

You can modify the settings for the issue tracker provider at any time. There are a few points to note if you do this.

If you edit the settings for an existing issue tracker provider, and you change the query filter to make it more restrictive (that is, fewer alerts are matched), LGTM will close any tickets raised for alerts that are no longer matched. Similarly, if changes to the query filter make it less restrictive, and the Only create issues for new alerts check box is not selected, LGTM will open tickets for existing alerts that were not previously matched—or reopen tickets if previous changes had caused them to be closed.

If you leave the Only create issues for new alerts check box selected when you are initially configuring the provider, and then you subsequently edit the settings and clear this check box, LGTM Enterprise will open tickets for alerts that it previously ignored because they already existed when you added the provider. However, if you clear the Only create issues for new alerts check box when you are initially configuring the provider, and then you subsequently edit the settings and select this check box, LGTM Enterprise will not close the issues it created for alerts that already existed when you added the provider.

Changes to issue tracker ticketing resulting from changes to the provider only occur when a new snapshot of a project is analyzed. It may, therefore, be a little while after you update the settings before your changes take effect.

Troubleshooting

See Why are no issue tracking tickets being raised?

Related topicsRelated topics