LGTM Enterprise 1.19.2

Adding webhook-based issue tracker integration

Issue tracker integration allows LGTM Enterprise to automatically open, close and reopen issue tickets in an external issue tracking system. You add this integration by defining a webhook issue tracker provider.

Using the webhook issue tracker provider, you can integrate any issue tracking system. The integration with Atlassian Jira is a special implementation of the webhook issue tracker provider, in that it uses the LGTM Jira add-on, which you'll need to install in your Jira instance. For more information, see Adding Jira integration.

After you have added the webhook issue tracker provider, it 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. You’ll need to set up your own webhook receiver to take this information and send it to your issue tracking application.

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

Follow these instructions for issue tracking systems other than Jira:

  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 provider for a different instance of your issue tracking application, 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 webhook 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. In the Webhook URL field, enter the URL to which your webhook receiver expects POST requests to be sent.

    For example: https://integrations.example.com/bug-tracker-notifications

  7. Copy the Secret value to the settings for your webhook receiver. This allows the receiver to verify the origin of the POST request.

  8. In the Query filters box, enter a YAML fragment containing include and exclude properties, as required, to define which alerts LGTM should open 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. Click Add to create the issue tracker provider.

LGTM Enterprise will now start sending requests to the webhook URL to open 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.

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.

Example JSON data

The blocks of JSON shown below are examples of the data that LGTM posts to the webhook URL.

This is a request to open a new issue ticket:

{
  "transition": "create",
  "project": {
    "id": 1000003,
    "url-identifier": "px/project-x/project-x.js",
    "name": "project-x/project-x.js",
    "url": "https://lgtm.example.com/projects/px/project-x/project-x.js"
  },
  "alert": {
    "file": "/src/ng/compile.js",
    "message": "@param tag refers to non-existent parameter enabled.\n",
    "url": "https://lgtm.example.com/issues/1000003/javascript/+ja0cf6+84AGgat15W1jooeMfUY=",
    "query": {
      "name": "JSDoc tag for non-existent parameter",
      "url": "https://lgtm.example.com/rules/1000507"
    }
  }
}

As confirmation that a ticket was successfully created, LGTM Enterprise expects to receive back a JSON response containing the ID assigned to the new ticket by the issue tracking application. For example:

{
  "issueId": "BUG-10101"
}

When LGTM Enterprise closes an issue ticket it posts a close transition, referencing the ticket ID. For example:

{
  "transition": "close",
  "issueId": "BUG-10101"
}

If LGTM Enterprise reopens an issue ticket it posts a reopen transition, referencing the ticket ID. For example:

{
  "transition": "reopen",
  "issueId": "BUG-10101"
}

Troubleshooting

See Why are no issue tracking tickets being raised?

Related topicsRelated topics