Confirm
1,351
edits
Changes
update GitHub App terminology and bug data needed
=== 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. "IntegrationsGitHub 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:
# via a manually configured webhook. This type of installation is not automatically affected by the other approaches.
# via an "IntegrationGitHub 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. (The old waySome 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):
* 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%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:
** Which repositories do you want to have access? (all or list)
** Are any of those repositories private?
** 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).
==== Integrations GitHub Apps ====
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 =====
If this is the first time this Integration 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 integration 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.
** 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.)
**Please do not install integrations GitHub apps with organization wide scope without first discussing with [[#contact|GitHub owners]].**
===== Additional Installations or Removals =====
If the integration 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 ====
* 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:
* 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?cc=gene%40mozilla.com&comment=I%27ve20want%20to%20use%20the%20NAME_HERE%20addon%20in%20ORG_NAME_HERE%20for%20the%20read20following%20https20reasons%3A%2F0D%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%2Fwiki.mozilla.org0D%0A%2A%2A%20Provide%20link%20to%20vendor%27s%20description%20of%2FGithub20permissions%2C20needed%20and%20need20why%20help0D%0A%0D%0A%20with2A%2A%20Provide%20the%20following.20Install%20link%20for%20a%0D20GitHub%0A20app%0D%0A&component=Github%3A%20Administration&form_name=enter_bug&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 ===
