LGTM Enterprise 1.25

Adding issue tracker integration

Issue tracker integration allows LGTM Enterprise to automatically open, close and reopen issue tickets for LGTM alerts in an external issue tracking system. You add this integration by defining a webhook issue tracker in LGTM Enterprise and then configuring an application to send and receive ticket details.

Which issue trackers are supported?

You can use a webhook issue tracker integration to link LGTM with any issue tracking system. For example, for Atlassian Jira, you should install the LGTM Jira add-on in Jira and configure it to process requests sent from a webhook issue tracker integration. For more information, see Adding issue tracker integration for Jira.

For other issue tracking systems, you’ll need to set up your own web app to pass data between LGTM and the issue tracker. For an example web app, see LGTM issue tracker integration example. This repository contains a basic sample application that passes data between LGTM Enterprise and the GitHub issue tracker.

What does an issue tracker integration do?

After you have defined a webhook issue tracker integration (described below), LGTM sends POST requests to the specified tracker endpoint. Each request contains data about an existing LGTM alert.

This data can be used to:

  • Create issues for new LGTM alerts in the issue tracker.
  • Suppress issues in the issue tracker when LGTM detects suppression comments in the codebase.
  • Close issues for LGTM alerts when they are fixed in the codebase and verified by LGTM.

In addition, the webhook can accept POST requests made to the LGTM endpoint and use them to hide alerts in some views of your LGTM Enterprise instance. For full details of the webhook API calls, see Issue tracker webhook API.

Issue tracker integration is enabled by default for all projects. After you define an issue tracker integration LGTM Enterprise will start opening issue tickets for alerts in all projects, based on the settings in the integration 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 integration

Follow these instructions for issue tracking systems other than Jira:

  1. On the Integrations page, click Add new integration to display the Integrate with a new system page. 

  2. Select the Issue tracker integration.

  3. Click Continue to display the Add new webhook issue tracker integration page.

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

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

    If you clear this check box when you add the integration, and then you later edit the settings and select this check box, LGTM Enterprise doesn't close the issues it created for alerts that already existed when you added the integration.

  6. Optional. If you do not want LGTM to start creating issues for all new projects immediately after they are added, clear the Automatically track issues for new projects check box.

    If you clear this check box, issues are created for a newly added project only after you manually enable issue tracker integration for that project. For more information, see Turning on or off issue tracker integration for a project.

  7. Optional. Required only if you want to send suppress/unsuppress transitions from the issue tracker to LGTM Enterprise. Copy the LGTM endpoint value to the settings for your webhook receiver.

  8. In the Tracker endpoint field, enter the URL that your webhook receiver expects LGTM Enterprise to POST requests to.

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

  9. Copy the Shared secret value to the settings for your webhook receiver. This allows the receiver to verify the origin of the POST request.

  10. 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. For details of the syntax and examples, see Configuring issue tracking.
    • LGTM Enterprise will begin opening issue tickets for all projects as soon as you add the integration. 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.
  11. Click Add to create the issue tracker integration.

When LGTM Enterprise next polls each repository for the latest data, it starts sending requests to the Tracker endpoint URL to open issue tickets.

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 on or off issue tracker integration for a project.

Example JSON data

The blocks of JSON shown below are examples of the data that LGTM posts to the Tracker endpoint 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": {
    "key": "+ja0cf6+84AGgat15W1jooeMfUY=",
    "file": "/src/ng/compile.js",
    "message": "This case label is a duplicate of 'id'.\n",
    "url": "https://lgtm.example.com/issues/1000003/javascript/+ja0cf6+84AGgat15W1jooeMfUY=",
    "query": {
      "id": 3717280014,
      "pack": "com.lgtm/javascript-queries",
      "name": "Duplicate switch case",
      "language": "javascript",
      "properties": {
        "id": "js/duplicate-switch-case",
        "name": "Duplicate switch case",
        "severity": "warning",
        "tags": [
          "maintainability",
          "correctness",
          "external/cwe/cwe-561"
        ]
      }
      "url": "https://lgtm.example.com/rules/3717280014"
    },
    "suppressed": false
  }
}

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:

{
  "issue-id": "BUG-10101"
}

When an alert is fixed—or when an alert is no longer matched after you've changed the settings for the issue tracker integration—LGTM Enterprise closes the issue ticket. It does this by posting a close transition that references the ticket ID. For example:

{
  "issue-id": "BUG-10101",
  "transition": "close"
}

For full details of transition payloads and the expected responses, see Issue tracker webhook API.

Changing which alerts are tracked

You can update the configuration of the integration at any time by editing the query filters defined in the issue tracker integration. For details, see Configuring issue tracking.

Troubleshooting

See Why are no issue tracking tickets being raised?

Related topicsRelated topics