diff --git a/README.md b/README.md index 9599ac3111..f700fd8607 100644 --- a/README.md +++ b/README.md @@ -109,34 +109,37 @@ Read, Write, and Admin for Development Information (branches, commits, and pull ##### Repository Permissions -|**Permission scope**|**Why the app needs it**| -|---|---| -|**Read** access to contents & metadata |**Contents** (aka code) and **metadata** are needed to sync development information to Jira.

**Medadata:** All GitHub apps have read-only metadata permission set by default. This is a [mandatory requirement by GitHub](https://docs.github.com/en/rest/reference/permissions-required-for-github-apps#metadata-permissions) and is needed to provide access to a collection of read-only endpoints with metadata for various resources. These endpoints do not provide sensitive private repository information. Read-only metadata permissions are used for the following webhook:
- repository (all events excluding `deleted`)

**Contents:** Read-only content permissions are used for the following webhooks:
- commit comment
- create
- delete
- push
- workflow run| -|**Read** access to actions and deployments|If you want to see build and deployment information in Jira, the app will need read permissions for deployments. This will allow the integration to listen to the webhook `deployment_status` event which occurs when a deployment is created.

**Deployments:** Read deployment permissions are used for the following webhooks:
- deployment status| -|**Read** and **write** access to issues and pull requests|**Issues** and **pull requests** are used by the GitHub for Jira app to power Smart Commit actions and unfurl Jira URLs. "Unfurling" means that the app looks for Jira issue keys like `[ABC-123]` in pull request or issue comments and then replaces those issue keys with a link to the respective Jira issue.

**Issues:** Read and write issue permissions are used for the following webhooks:
- issue comment
- issues

**Pull requests:** Read and write pull request permissions are used for the following webhooks:
- pull request
- pull request review| -|**Read** access to Security events| If you want to see links to GitHub code scanning alerts in Jira, the app will need read permissions to Security events. The GitHub App will listen to [`code_scanning_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert) webhooks and send details of the Security reports to Jira. These will appear under the "Other links" tab of the Development Panel on Jira issues. | +| **Permission scope** | **Why the app needs it** | +|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Read-only** access to actions | Read-only access to actions exposes the `workflow_run` webhook event. This event includes information such as artifacts_url, check_suite_id, conclusion, head_branch, and head_sha. | +| **Read-only** access to code scanning alerts / security events| If you want to see links to GitHub code scanning alerts in Jira, the app will need read permissions to Security events. The GitHub App will listen to [`code_scanning_alert`](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert) webhooks and send details of the Security reports to Jira. These will appear under the "Other links" tab of the Development Panel on Jira issues. | +| **Read-only** access to contents | **Contents (aka code):** Read-only permissions are needed to sync development information to Jira for the following webhooks:
- commit comment
- create
- delete
- push
- workflow run | +| **Read-only** access to deployments | If you want to see build and deployment information in Jira, the app will need read permissions for deployments. This will allow the integration to listen to the webhook `deployment_status` event which occurs when a deployment is created. Read-only deployment permissions are used for the following webhooks:
- deployment status | +| **Read-only** access to metadata | **Metadata** All GitHub apps have read-only metadata permission set by default. This is a [mandatory requirement by GitHub](https://docs.github.com/en/rest/reference/permissions-required-for-github-apps#metadata-permissions) and is needed to provide access to a collection of read-only endpoints with metadata for various resources. These endpoints do not provide sensitive private repository information. Read-only metadata permissions are used for the following webhook:
- repository | +| **Read** and **write** access to issues and pull requests | **Issues** and **pull requests** are used by the GitHub for Jira app to power Smart Commit actions and unfurl Jira URLs. "Unfurling" means that the app looks for Jira issue keys like `[ABC-123]` in pull request or issue comments and then replaces those issue keys with a link to the respective Jira issue.

**Issues:** Read and write issue permissions are used for the following webhooks:
- issue comment
- issues

**Pull requests:** Read and write pull request permissions are used for the following webhooks:
- pull request
- pull request review | ##### Organization permissions -|**Permission scope**|**Why the app needs it**| -|---|---| -|**Read** access to members | To determine if you have admin access to a GitHub organization.| +| **Permission scope** |**Why the app needs it**| +|------------------------------|---| +| **Read-only** access to members | To determine if you have admin access to a GitHub organization.| ##### Events Our App Subscribes To -|**Event**|**When this event occurs**| -|---|---| -|Commit comment|A commit comment is created| -|Create|A Git branch or tag is created| -|Delete|A Git branch or tag is deleted| -|Deployment status|A deployment is created| -|Issue comment|Activity related to an issue or pull request comment| -|Issues|Activity related to an issue| -|Pull request|Activity related to pull requests| -|Pull request review|Activity related to pull request reviews| -|Push|One or more commits are pushed to a repository branch or tag| -|Repository|Activity related to a repository| -|Workflow run|When a GitHub Actions workflow run is requested or completed| +| **Event** | **When this event occurs** | +|--------------------------------------|--------------------------------------------------------------| +| Code scanning alert /security events | Code Scanning alert created, fixed in branch, or closed | +| Commit comment | A commit comment is created | +| Create | A Git branch or tag is created | +| Delete | A Git branch or tag is deleted | +| Deployment status | A deployment is created | +| Issue comment | Activity related to an issue or pull request comment | +| Issues | Activity related to an issue | +| Pull request | Activity related to pull requests | +| Pull request review | Activity related to pull request reviews | +| Push | One or more commits are pushed to a repository branch or tag | +| Repository | Activity related to a repository | +| Workflow run | When a GitHub Actions workflow run is requested or completed | Have more questions about permissions? Please see our [FAQ documentation](https://github.com/atlassian/github-for-jira/blob/main/docs/FAQs.md). If you can’t find the answer to a question, please feel free to [open an issue](https://github.com/atlassian/github-for-jira/issues/new) and send your question to our team. We’ll be more than happy to answer and will update our FAQ doc accordingly. diff --git a/docs/FAQs.md b/docs/FAQs.md index a1965c61e3..6119f27354 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -18,14 +18,6 @@ ![Pull request and issue comment links](./images/read-and-write-permissions-issues-and-prs.png) -

Q: Why do you need read and **write** access for deployments? It appears that sending deployment data to Jira would only require read access.

- -**A:** To correctly map the status of your deployments (pending, in progress, successful etc) we need to access the `state` property which only exists on the `deployment_status` webhook event which occurs when a deployment is created. The [GitHub API](https://docs.github.com/en/rest/reference/repos#create-a-deployment-status) requires that GitHub apps have read and write access to listen to deployment creation events. Unfortunately, the GitHub documentation doesn’t specify why write access is needed but we have raised the concern with them. You can follow the discussion [here](https://github.community/t/write-access-to-deployment-creation-events/215078/1). - -

Q: I do not wish to give Jira read and write access to deployments. What are the consequences of that? Does it affect existing functionality?

- -**A:** You won't be able to see deployments in Jira. If you choose to ignore the request for these permissions you will be able to use the integration and will still see branch, commit, pull request, and merge data show up in the dev panel in Jira. However, if you would like to data for builds and deployments, this access will need to be granted. -

Q: What happens if another change is made to the app in the future that requires new permissions? Can I choose to accept the new permission but ignore previously requested permissions that I don’t want/feel comfortable with?

**A:** Unfortunately not. GitHub apps are limited in this sense as permissions are not granular.