Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Arc-1466 permissions docs #1322

Merged
merged 3 commits into from
Jul 4, 2022
Merged

Arc-1466 permissions docs #1322

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f5c3b9f
update permissions
rachellerathbone Jul 1, 2022
dc365c2
remove line break
rachellerathbone Jul 1, 2022
38f5085
Merge branch 'main' into ARC-1466-permissions
rachellerathbone Jul 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 25 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. <br><br> **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: <br> - repository (all events excluding `deleted`) <br><br> **Contents:** Read-only content permissions are used for the following webhooks: <br> - commit comment <br> - create <br> - delete <br> - push <br> - 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. <br><br> **Deployments:** Read deployment permissions are used for the following webhooks: <br> - 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. <br><br> **Issues:** Read and write issue permissions are used for the following webhooks: <br> - issue comment <br> - issues <br><br> **Pull requests:** Read and write pull request permissions are used for the following webhooks: <br> - pull request <br> - 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: <br> - commit comment <br> - create <br> - delete <br> - push <br> - 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: <br> - 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: <br> - 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. <br><br> **Issues:** Read and write issue permissions are used for the following webhooks: <br> - issue comment <br> - issues <br><br> **Pull requests:** Read and write pull request permissions are used for the following webhooks: <br> - pull request <br> - 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鈥檛 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鈥檒l be more than happy to answer and will update our FAQ doc accordingly.

Expand Down
8 changes: 0 additions & 8 deletions docs/FAQs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,6 @@

![Pull request and issue comment links](./images/read-and-write-permissions-issues-and-prs.png)

<h3>Q: Why do you need read and **write** access for deployments? It appears that sending deployment data to Jira would only require read access.</h3>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are out-of-date. I obviously forgot to update this when I removed the need for write permissions from the app. We definitely need to compile a list of other questions are customers may have but that will be covered in ARC 1292


**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鈥檛 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).

<h3>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?</h3>

**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.

<h3>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鈥檛 want/feel comfortable with?</h3>

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