Confirmed users
1,351
edits
GitHub: Difference between revisions
update GitHub App terminology and bug data needed
(update mozilla-iam contact) |
(update GitHub App terminology and bug data needed) |
||
| Line 19: | Line 19: | ||
=== How do I hook up a new 3rd party application to a repository in the mozilla org? === | === How do I hook up a new 3rd party application to a repository in the mozilla org? === | ||
{{note|There are now multiple 3rd pary application types. " | {{note|There are now multiple 3rd pary application types. "GitHub Apps" (nee integrations) are the new approach and preferred.|gotcha}} | ||
{{note|Some 3rd party apps use GitHub as an OAuth identity provider for their website (e.g. for a dashboard). An ''OAuth Application'' will block the installation process if the app is not already approved. The "approval needed" block is what this section describes.|gotcha}} | |||
3rd party applications can easily impact many other repositories than the initial one. For that reason, the following steps are strongly encouraged. Note that there are three ways 3rd party apps can be associated with the entire organization, or a specific repository: | 3rd party applications can easily impact many other repositories than the initial one. For that reason, the following steps are strongly encouraged. Note that there are three ways 3rd party apps can be associated with the entire organization, or a specific repository: | ||
# via a manually configured webhook. This type of installation is not automatically affected by the other approaches. | # via a manually configured webhook. This type of installation is not automatically affected by the other approaches. | ||
# via an " | # via an "GitHub App" (nee integration), which is connected by "Installing" it into the target. Both of those steps require an "owner" to perform. Please open a bug. (This is the new, preferred way.) | ||
# via granting access via OAUTH tied to the installer's credentials. Please open a bug. | # via granting access via OAUTH tied to the installer's credentials. Please open a bug. Some services will OAuth just as an Identitdy Provider for access to a dashboard on their site. You only need to file if you get to a "request organization approval" prompt. | ||
You can help speed up the approval process by opening a bug as the way to contact the owners and provide answers to the questions they will have (the owners will open a bug for a security review if needed): | You can help speed up the approval process by opening a bug as the way to contact the owners and provide answers to the questions they will have (the owners will open a bug for a security review if needed): | ||
* Use this [https://bugzilla.mozilla.org/enter_bug.cgi?cc=gene%40mozilla.com&comment=I%20want%20to%20use%20the%20NAME_HERE%20addon%20in%20ORG_NAME_HERE%20for%20the%20following%20reasons%3A | * Use this [https://bugzilla.mozilla.org/enter_bug.cgi?cc=gene%40mozilla.com&comment=I%20want%20to%20use%20the%20NAME_HERE%20addon%20in%20ORG_NAME_HERE%20for%20the%20following%20reasons%3A%0D%0A%0D%0ABelow%20are%20my%20answers%20to%20your%20stock%20questions%3A%0D%0A%0D%0A%2A%2A%20Which%20repositories%20do%20you%20want%20to%20have%20access%3F%20%28all%20or%20list%29%0D%0A%0D%0A%2A%2A%20Are%20any%20of%20those%20repositories%20private%3F%0D%0A%0D%0A%2A%2A%20Provide%20link%20to%20vendor%27s%20description%20of%20permissions%20needed%20and%20why%0D%0A%0D%0A%2A%2A%20Provide%20the%20Install%20link%20for%20a%20GitHub%20app%0D%0A&component=Github%3A%20Administration&product=mozilla.org&short_desc=Assess%20use%20of%20external%20addon%20NAME_HERE%20in%20Mozilla%27s%20GitHub%20organization%20ORG_NAME_HERE bug template] | ||
* Include answers to these questions: | * Include answers to these questions: | ||
** Which repositories do you want to have access? (all or list) | ** Which repositories do you want to have access? (all or list) | ||
** Are any of those repositories private? | ** Are any of those repositories private? | ||
** Provide link to vendor's description of permissions needed and why | ** Provide link to vendor's description of permissions needed and why | ||
** Provide installation instructions (both may be needed): | |||
*** For GitHub Apps, the "install" link | |||
*** For OAuth apps, request the approval of the app for the organization (part of their workflow). | |||
==== | ==== GitHub Apps ==== | ||
GitHub Apps (formerly called "integrations") are "Installed" into either the entire organization, or into individual repositories. Each integration has a documented, granular, access to various of the repository resources. This is good. | |||
However, the installation can only be done by an organization owner, who may have to do additional housekeeping. This is not so good, so please plan accordingly (you may need to coordinate with [[#contact|GitHub owners]]). | However, the GitHub App installation can only be done by an organization owner, who may have to do additional housekeeping. This is not so good, so please plan accordingly (you may need to coordinate with [[#contact|GitHub owners]]). | ||
===== Initial Installation ===== | ===== Initial Installation ===== | ||
If this is the first time this | If this is the first time this GitHub App is being installed in the organization, a few extra checks and coordination are needed. An organization owner will need to perform these steps: | ||
* Determine if the | * Determine if the GitHub App previously had an OAUTH version. | ||
** If so, it is likely that installing the integration will disable all repositories in the organization using the OAUTH version of the application. | ** If so, it is likely that installing the integration will disable all repositories in the organization using the OAUTH version of the application. | ||
** Find all current repositories using the classic OAUTH application (this is non-trivial, scripts exist to help) | ** Find all current repositories using the classic OAUTH application (this is non-trivial, scripts exist to help) | ||
** Install the Integration for all current repositories, and the new one (organization owner permissions needed.) | ** Install the Integration for all current repositories, and the new one (organization owner permissions needed.) | ||
**Please do not install | **Please do not install GitHub apps with organization wide scope without first discussing with [[#contact|GitHub owners]].** | ||
===== Additional Installations or Removals ===== | ===== Additional Installations or Removals ===== | ||
If the | If the GitHub App has already been installed in the organization, the new repository simply needs to be added or removed from the list. An organization owner has to make this change. | ||
==== OAUTH (classic) Applications ==== | ==== OAUTH (classic) Applications ==== | ||
* Authorizing an application to work with GitHub utilizes the permissions your account has -- so, any repositories you have access to the application will have access to as well (including private ones). If you want to grant access to an application that no one else has used with the Mozilla organization yet you'll see a "Request access" button during the set up flow. You'll need to click that button to request approval. See below for an example: | * Authorizing an application to work with GitHub utilizes the permissions your account has -- so, any repositories you have access to the application will have access to as well (including private ones). If you want to grant access to an application that no one else has used with the Mozilla organization yet you'll see a "Request access" button during the set up flow. You'll need to click that button to request approval. See below for an example: | ||
| Line 67: | Line 66: | ||
* In some cases, the application does not need to be "approved" to function correctly, as it has read only access to any public repository. (Some applications only want write access to help you configure the application first time.) | * In some cases, the application does not need to be "approved" to function correctly, as it has read only access to any public repository. (Some applications only want write access to help you configure the application first time.) | ||
* In other cases, the application does need write permission, and/or permission to read a private repository. In these cases, it is helpful to send the details to the owner's team, either by [https://bugzilla.mozilla.org/enter_bug.cgi?comment=I% | * In other cases, the application does need write permission, and/or permission to read a private repository. In these cases, it is helpful to send the details to the owner's team, either by [https://bugzilla.mozilla.org/enter_bug.cgi?cc=gene%40mozilla.com&comment=I%20want%20to%20use%20the%20NAME_HERE%20addon%20in%20ORG_NAME_HERE%20for%20the%20following%20reasons%3A%0D%0A%0D%0ABelow%20are%20my%20answers%20to%20your%20stock%20questions%3A%0D%0A%0D%0A%2A%2A%20Which%20repositories%20do%20you%20want%20to%20have%20access%3F%20%28all%20or%20list%29%0D%0A%0D%0A%2A%2A%20Are%20any%20of%20those%20repositories%20private%3F%0D%0A%0D%0A%2A%2A%20Provide%20link%20to%20vendor%27s%20description%20of%20permissions%20needed%20and%20why%0D%0A%0D%0A%2A%2A%20Provide%20the%20Install%20link%20for%20a%20GitHub%20app%0D%0A&component=Github%3A%20Administration&product=mozilla.org&short_desc=Assess%20use%20of%20external%20addon%20NAME_HERE%20in%20Mozilla%27s%20GitHub%20organization%20ORG_NAME_HERE opening a bug] or [[#contact|email]]. | ||
=== Reviewing owners and permissions === | === Reviewing owners and permissions === | ||