8000 Merge pull request #20 from zacharyr-qb/main · github/ghas-jira-integration@43cbf77 · GitHub
[go: up one dir, main page]
Skip to content

Commit 43cbf77

Browse files
author
Chelsea Boling
authored
Merge pull request #20 from zacharyr-qb/main
Labels README changes.
2 parents 8c8cbf1 + 4ea8a13 commit 43cbf77

File tree

1 file changed

+63
-18
lines changed

1 file changed

+63
-18
lines changed

‎README.md‎

Lines changed: 63 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
1-
# `gh2jira` - Synchronize GitHub Code Scanning alerts and JIRA issues
1+
# Synchronize GitHub Code Scanning alerts to Jira issues
22

3-
[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.
3+
[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.
44

55
## This repository
66

7-
This repository gives a quick illustrative example of how to integrate GitHub Code Scanning with a third-party issue tracker - in this case JIRA. The code is intended as a proof-of-concept, showing the basic operations necessary to handle incoming requests from GitHub. It is not intended for production use. Please feel free to use this as a starting point for your own integration.
7+
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.
88

99
## Using the GitHub Action
1010

1111
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:
1212

1313
* 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.
14-
* The URL of your JIRA Server instance.
15-
* 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.
16-
* A JIRA Server account (username + password) with the following permissions for the abovementioned project:
14+
* The URL of your Jira Server instance.
15+
* 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.
16+
* A Jira Server account (username + password) with the following permissions for the abovementioned project:
1717
* `Browse Projects`
1818
* `Close Issues`
1919
* `Create Issues`
2020
* `Delete Issues`
2121
* `Edit Issues`
2222
* `Transition Issues`
23-
* 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.
23+
* 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.
2424

2525
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`:
2626

2727
```yaml
28-
name: "Sync with JIRA"
28+
name: "Sync GHAS to Jira"
2929

3030
on:
3131
schedule:
@@ -35,8 +35,8 @@ jobs:
3535
test_job:
3636
runs-on: ubuntu-latest
3737
steps:
38-
- name: Sync with JIRA
39-
uses: github/codescanning-jira-integration@master
38+
- name: Sync alerts to Jira issues
39+
uses: github/ghas-jira-integration@v1
4040
with:
4141
jira_url: '<INSERT JIRA SERVER URL>'
4242
jira_user: '${{ secrets.JIRA_USER }}'
@@ -45,7 +45,34 @@ jobs:
4545
sync_direction: 'gh2jira'
4646
```
4747
48-
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. If you set `sync_direction` to `jira2gh`, it will synchronize the other way. Currently, two-way integration is not yet possible via the action. If you need it, use the CLI's `serve` command (see below).
48+
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`:
49+
50+
- `gh2jira`
51+
- `jira2gh`
52+
53+
54+
Using `gh2jira` means the alerts will sync from GitHub to Jira. If you set `sync_direction` to `jira2gh`, it will synchronize the other way.
55+
Currently, two-way integration is not yet possible via the action. If you need it, use the CLI's `serve` command (see below).
56+
57+
#### Other optional features for this Action
58+
59+
##### Labels
60+
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.
61+
62+
```yaml
63+
with:
64+
jira_labels: 'red-team,blue-team,green-team'
65+
```
66+
67+
##### Custom transition states (end, reopen)
68+
You can customize the end and reopen states if your Jira workflows don't use the default close/reopen states.
69+
70+
```yaml
71+
with:
72+
issue_end_state: 'Closed'
73+
issue_reopen_state: 'red-team-followup'
74+
```
75+
4976

5077
## Using the CLI's `sync` command
5178

@@ -81,7 +108,18 @@ pipenv run ./gh2jira sync \
81108

82109
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.
83110

84-
Here an example for two-way integration:
111+
#### Other optional features for the CLI
112+
113+
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.
114+
115+
116+
```bash
117+
--jira-labels "red-team,blue-team,green-team"
118+
--issue-end-state "Closed"
119+
--issue-reopen-state "blue-team-reopen"
120+
```
121+
122+
Here's an example for a two-way integration:
85123

86124
```bash
87125
pipenv run ./gh2jira sync \
@@ -97,15 +135,20 @@ pipenv run ./gh2jira sync \
97135
--direction both
98136
```
99137

100-
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`.
138+
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`.
139+
140+
## Other CLI sync options
141+
142+
<details>
143+
<summary>The serve command</summary>
101144

102145
## Using the CLI's `serve` command
103146

104-
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.
147+
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.
105148

106149
In addition to the [usual requirements](#using-the-github-action) you also need:
107-
* 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.
108-
* Webhooks set up, both, on GitHub and JIRA. On GitHub only repository or organization owners can do so. On JIRA it requires administrator access.
150+
* 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.
151+
* Webhooks set up, both, on GitHub and Jira. On GitHub only repository or organization owners can do so. On Jira, it requires administrator access.
109152
* A secret which will be used to verify webhook requests.
110153

111154
First, [create a GitHub webhook](https://docs.github.com/en/developers/webhooks-and-events/creating-webhooks) with the following event triggers:
@@ -114,7 +157,7 @@ First, [create a GitHub webhook](https://docs.github.com/en/developers/webhooks-
114157

115158
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`.
116159

117-
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`.
160+
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`.
118161

119162
Finally, start the server:
120163

@@ -131,7 +174,9 @@ pipenv run ./gh2jira serve \
131174
--direction both
132175
```
133176

134-
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.
177+
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.
178+
179+
</details>
135180

136181
## Contributing
137182

0 commit comments

Comments
 (0)
0