[GitHub's REST API](https://docs.github.com/en/rest) and [webhooks](https://docs.github.com/en/developers/webhooks-and-events/about-webhooks) give customers the option of exporting alerts to any issue tracker, by allowing users to fetch the data via API endpoints and/or by receiving webhook POST requests to a hosted server.
This repository gives a quick illustrative example of how to integrate GitHub Code Scanning with Jira. The code is intended as a proof-of-concept, showing the basic operations necessary to handle incoming requests from GitHub. Please feel free to use this as a starting point for your own integration.
The easiest way to use this tool is via its GitHub Action, which you can add to your workflows. Here is what you need before you can start:
* A GitHub repository with Code Scanning enabled and a few alerts. Follow [this guide](https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/setting-up-code-scanning-for-a-repository) to set up Code Scanning.
* A [Jira project](https://confluence.atlassian.com/adminjiraserver/creating-a-project-938846813.html) to store your issues. You will need to provide its `project key` to the action.
* A Jira Server account (username + password) with the following permissions for the abovementioned project:
* Depending on where you run your workflow, the Jira Server instance must be accessible from either the [GitHub.com IP addresses](https://docs.github.com/en/github/authenticating-to-github/about-githubs-ip-addresses) or the address of your GitHub Enterprise Server instance.
Make sure you safely store all credentials as [GitHub Secrets](https://docs.github.com/en/actions/reference/encrypted-secrets). For accessing the Code Scanning alert data, the action uses the [GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#using-the-github_token-in-a-workflow) which is automatically created for you, so you don't need to provide it. Finally, set up the following workflow in your repository, e.g. by adding the file `.github/workflows/jira-sync.yml`:
This action will push any changes (new alerts, alerts deleted, alert states changed) to Jira, by creating, deleting or changing the state of the corresponding Jira issues. There are two sync directions for the field `sync_direction`:
#### Using this Action to synchronize secret scanning alerts
Secret scanning alerts can only be queried with the API in private repositories. For public repositories, there will just be an empty results list. You'll need to pass in a PAT via `github_token` that has admin rights to access secret scanning alerts. Ensure the PAT has the `security_events` scope:
You can also create labels for the Jira issues that are created. By using the example yaml below in your workflow, you can use multiple labels, and spaces will be respected. For example, if you add `red-team, blue team`, the labels would be created 'red-team' and 'blue team'. If this input is updated in the workflow, the existing JIRE issues will also be updated with the same labels.
* a GitHub `personal access token`, so that the program can fetch alerts from your repository. Follow [this guide](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) to obtain a dedicated token. It will have to have at least the `security_events` scope and muist have admin rights to access secret scanning alerts.
Note: Instead of the `--gh-token` and `--jira-token` options, you may also set the `GH2JIRA_GH_TOKEN` and `GH2JIRA_JIRA_TOKEN` environment variables. The above command could be invoked via a cronjob every X minutes, to make sure issues and alerts are kept in sync.
There is an optional parameter you can use for creating labels in your Jira issues. As previously mentioned, spaces within the double quotes will be respected and saved. Just like the GitHub Actions way, the custom transition states are also optional when using the CLI.
In this case the repository's state is stored in a JSON file (which will be created if it doesn't already exist). Alternatively, the state can also be stored in a dedicated Jira issue via `--state-issue -` (this will automatically generate and update a storage issue within the same Jira project). If the storage issue should be in a separate Jira project, you can specify `--state-issue KEY-OF-THE-STORAGE-ISSUE`.
The following method is the most involved one, but currently the only one which allows two-way integration (i.e. changes to Code Scanning alerts trigger changes to Jira issues and vice versa). It uses a lightweight `Flask` server to handle incoming Jira and GitHub webhooks. The server is meant to be an example and not production-ready.
* A machine with an address that can be reached from GitHub.com or your GitHub Enterprise Server instance and your Jira Server instance. This machine will run the server.
* Webhooks set up, both, on GitHub and Jira. On GitHub only repository or organization owners can do so. On Jira, it requires administrator access.
This can be either a repository or an organization-wide hook. Set the `Payload URL` to `https://<the machine>/github`, the `Content type` to `application/json` and insert your webhook `Secret`. Make sure to `Enable SSL verification`.
Second, [register a webhook on Jira](https://developer.atlassian.com/server/jira/platform/webhooks/#registering-a-webhook). Give your webhook a `Name` and enter the `URL`: `https://<the machine>/jira?secret_token=<INSERT WEBHOOK SECRET>`. In the `Events` section specify `All issues` and mark the boxes `created`, `updated` and `deleted`. Click `Save`.
This will enable two-way integration between GitHub and Jira. Note: Instead of the `--secret` option, you may also set the `GH2JIRA_SECRET` environment variable.
