Enterprise installations for GitHub Apps and enterprise app managers (#56338)
Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Co-authored-by: isaacmbrown <isaacmbrown@github.com>
This commit is contained in:
Hirsch Singhal
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Adding and removing GitHub App managers in your enterprise
|
||||
intro: 'Enterprise owners can grant or revoke access for a user to manage individual {% data variables.product.prodname_github_apps %} owned by the enterprise.'
|
||||
versions:
|
||||
feature: enterprise-app-manager
|
||||
type: how_to
|
||||
topics:
|
||||
- Enterprise
|
||||
- GitHub Apps
|
||||
permissions: Enterprise owners.
|
||||
shortTitle: Enterprise App managers
|
||||
---
|
||||
|
||||
## About {% data variables.product.prodname_github_app %} managers
|
||||
|
||||
Enterprise owners can designate other users in their enterprise as {% data variables.product.prodname_github_app %} managers for individual apps. {% data variables.product.prodname_github_app %} managers can manage the settings of specific {% data variables.product.prodname_github_app %} registrations that are owned by the enterprise. The {% data variables.product.prodname_github_app %} manager role does not grant recipients access to install and uninstall {% data variables.product.prodname_github_apps %} on an enterprise or organization. For more information about the specific app settings that {% data variables.product.prodname_github_app %} managers can control, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app).
|
||||
|
||||
When an enterprise app manager adds permissions to a {% data variables.product.prodname_github_app %}, the update is automatically accepted in all organizations where the app manager is also an organization owner. When an enterprise owner adds permissions to a {% data variables.product.prodname_github_app %}, the update is automatically accepted in all organizations regardless of their organization membership.
|
||||
|
||||
## Granting the ability to manage an individual {% data variables.product.prodname_github_app %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.github-apps-tab %}
|
||||
|
||||
1. Under "{% data variables.product.prodname_github_apps %}", click on the avatar of the app you'd like to add a {% data variables.product.prodname_github_app %} manager for.
|
||||
1. In the left sidebar, click **App managers**.
|
||||
1. At the bottom of the "App managers" section, in the search field, type the username of the person you want to designate as a GitHub App manager for the app, then click **Grant**.
|
||||
|
||||
The user must be a member of the enterprise to be granted {% data variables.product.prodname_github_app %} manager permissions.
|
||||
|
||||
## Removing managers from an individual {% data variables.product.prodname_github_app %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.settings-tab %}
|
||||
{% data reusables.enterprise-accounts.github-apps-tab %}
|
||||
|
||||
1. Under "{% data variables.product.prodname_github_apps %}", click on the avatar of the app you'd like to remove a {% data variables.product.prodname_github_app %} manager from.
|
||||
1. In the left sidebar, click **App managers**.
|
||||
1. Under "App managers", next to the person you want to remove {% data variables.product.prodname_github_app %} manager permissions from, click **Revoke**.
|
||||
|
||||
## Further reading
|
||||
|
||||
* [AUTOTITLE](/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise)
|
||||
* [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers)
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Creating GitHub Apps for your enterprise
|
||||
intro: 'Learn how to create a {% data variables.product.prodname_github_app %} for organizations within your enterprise.'
|
||||
intro: 'Learn how to create a {% data variables.product.prodname_github_app %} for your enterprise.'
|
||||
versions:
|
||||
feature: enterprise-apps-public-beta
|
||||
type: how_to
|
||||
@@ -10,13 +10,18 @@ permissions: Enterprise owners.
|
||||
shortTitle: Create a GitHub App
|
||||
---
|
||||
|
||||
You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts.
|
||||
You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on{% ifversion enterprise-installed-apps %} your enterprise or{% endif %} organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts.
|
||||
|
||||
## Step 1: Registering a {% data variables.product.prodname_github_app %}
|
||||
|
||||
To create a {% data variables.product.prodname_github_app %}, you must first register the app. See [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
|
||||
|
||||
Apps can also be transferred to an enterprise from a member or organization. To transfer an app, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app).
|
||||
{%- ifversion enterprise-app-manager %}
|
||||
|
||||
### Step 1a: Adding an enterprise app manager
|
||||
|
||||
Enterprise owners can add enterprise members to an app as an app manager. App managers can manage the app's settings and credentials, but cannot install the app. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).{% endif %}
|
||||
|
||||
## Step 2: Building a {% data variables.product.prodname_github_app %}
|
||||
|
||||
@@ -30,11 +35,11 @@ After registering a {% data variables.product.prodname_github_app %}, you will w
|
||||
|
||||
You should aim to follow best practices. See [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app).
|
||||
|
||||
## Step 3: Authorizing or sharing your {% data variables.product.prodname_github_app %}
|
||||
## Step 3: Authorizing or installing your {% data variables.product.prodname_github_app %}
|
||||
|
||||
Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available to organizations in your enterprise, either through **authorization** or **installation**, depending on the app’s purpose.
|
||||
Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available for use, either through **authorization** or **installation**, depending on the app’s purpose.
|
||||
|
||||
Enterprise owners can modify the permissions for apps owned by their enterprise at any time. Permissions changes will be automatically accepted by organizations in the enterprise.
|
||||
Enterprise owners {% ifversion enterprise-app-manager %}and app managers {% endif %}can modify the permissions for apps owned by their enterprise at any time. Permissions changes will be automatically accepted by organizations in the enterprise{% ifversion enterprise-app-manager %} if the change was made by the enterprise owner. Otherwise, the changes will be accepted only where the app manager is also an organization owner, and an organization owner must accept the update request for all other organizations{% endif %}.
|
||||
|
||||
### Step 3a: Authorizing your {% data variables.product.prodname_github_app %}
|
||||
|
||||
@@ -47,3 +52,5 @@ For apps that require installation to function, you can provide organization own
|
||||
## Step 4: Installing your {% data variables.product.prodname_github_app %} (if required)
|
||||
|
||||
If your {% data variables.product.prodname_github_app %} requires installation (not just authorization), organization owners can use the install link to install the app on their organization. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party).
|
||||
|
||||
{% ifversion enterprise-installed-apps %}If your app uses enterprise permissions, you can install it on your enterprise. To find the installation link, go to the app's settings page in your enterprise account. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-on-your-enterprise).{% endif %}
|
||||
|
||||
@@ -11,5 +11,6 @@ children:
|
||||
- /deleting-an-enterprise-account
|
||||
- /changing-the-url-for-your-enterprise
|
||||
- /creating-github-apps-for-your-enterprise
|
||||
- /adding-and-removing-github-app-managers-in-your-enterprise
|
||||
shortTitle: Manage enterprise account
|
||||
---
|
||||
|
||||
@@ -31,10 +31,10 @@ Common use cases for {% data variables.product.prodname_github_apps %} include:
|
||||
|
||||
Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} use OAuth 2.0 and can act on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can also act independently of a user.
|
||||
|
||||
{% data variables.product.prodname_github_apps %} can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions.
|
||||
{% data variables.product.prodname_github_apps %} can be installed directly on {% ifversion enterprise-installed-apps %}enterprises, {% endif %}organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions.
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}
|
||||
You can also create an enterprise-owned {% data variables.product.prodname_github_app %} that can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise).
|
||||
You can also create an enterprise-owned {% data variables.product.prodname_github_app %} that can only be installed on{% ifversion enterprise-installed-apps %} the enterprise itself or{% endif %} organizations within your enterprise, and can only be authorized by members of your enterprise. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise).
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.apps.app_manager_role %}
|
||||
@@ -47,11 +47,11 @@ Then, you need to write code to add functionality to your {% data variables.prod
|
||||
|
||||
Once you have written the code for your {% data variables.product.prodname_github_app %}, your app needs to run somewhere. If your app is a website or web app, you might host your app on a server like [Azure App Service](https://azure.microsoft.com/products/app-service/). If your app is a client-side app, it might run on a user's device.
|
||||
|
||||
To use your {% data variables.product.prodname_github_app %}, you need to install it on your organization or personal account.
|
||||
To use your {% data variables.product.prodname_github_app %}, you need to install it on your {% ifversion enterprise-installed-apps %}enterprise, {% endif %}organization or personal account.
|
||||
|
||||
* If your {% data variables.product.prodname_github_app %} is **private**, you can only install it on the account that owns the app. {% ifversion restrictive-app-authz %}If it's owned by an organization, only members of the organization can sign in to it. If it's owned by your user account, only you can sign in to it.{% endif %}
|
||||
* If your {% data variables.product.prodname_github_app %} is **public**, other users and organizations can also install it. Anyone can sign in to it.{% ifversion enterprise-apps-public-beta %}
|
||||
* If your {% data variables.product.prodname_github_app %} is owned by an **enterprise**, you can install it on any organization within that enterprise.{% ifversion restrictive-app-authz %} Only members of the enterprise can sign in to it.{% endif %}{% endif %}
|
||||
* If your {% data variables.product.prodname_github_app %} is **private**, you can only install it on the account that owns the app.
|
||||
* If your {% data variables.product.prodname_github_app %} is **public**, other accounts can also install it.{% ifversion enterprise-apps-public-beta %}
|
||||
* If your {% data variables.product.prodname_github_app %} is owned by an **enterprise**, you can install it on {% ifversion enterprise-installed-apps %}the enterprise itself or {% endif %}any organization within that enterprise.{% endif %}{% ifversion restrictive-app-authz %} Only members of the enterprise can sign in to it.{% endif %}
|
||||
|
||||
For more information, see [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app) and [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app).
|
||||
|
||||
@@ -80,6 +80,10 @@ Some examples of automations you could create with a {% data variables.product.p
|
||||
|
||||
If you want your app to respond to events on {% data variables.product.prodname_dotcom %}, your app should subscribe to webhooks. For example, you may want your app to leave a comment when a pull request is opened. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps).
|
||||
|
||||
{% ifversion enterprise-installed-apps %}
|
||||
Apps installed on enterprises do not currently support webhooks, and must be installed on an organization to receive them.
|
||||
{% endif %}
|
||||
|
||||
### {% data variables.product.prodname_github_apps %} that can take certain actions
|
||||
|
||||
When you set up your {% data variables.product.prodname_github_app %}, you can select specific permissions for the app. These permissions determine what the app can do via the {% data variables.product.prodname_dotcom %} API, what they can do on behalf of a signed in user, and what webhooks the app can receive. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app).
|
||||
|
||||
@@ -53,7 +53,7 @@ The rate limit for {% data variables.product.prodname_github_apps %} using an in
|
||||
In general, {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} can make the same API requests. However, there are some differences:
|
||||
|
||||
* The REST API to manage check runs and check suites is only available to {% data variables.product.prodname_github_apps %}.
|
||||
* Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_apps %}. This means that {% data variables.product.prodname_github_apps %} cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available.
|
||||
* {% ifversion enterprise-installed-apps %}Not every enterprise-level API supports {% data variables.product.prodname_github_apps %} at this time. New permissions are being added to support more APIs. Check [AUTOTITLE](/enterprise-cloud@latest/rest/authentication/permissions-required-for-github-apps) to review the list of supported enterprise permissions and APIs.{% else %}Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_apps %}. This means that {% data variables.product.prodname_github_apps %} cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available.{% endif %}
|
||||
* Some requests may return incomplete data depending on the permissions and repository access that was granted to an {% data variables.product.prodname_github_app %}. For example, if your app makes a request to get all repositories that a user can access, the response will only include the repositories that the app was also granted access to.
|
||||
|
||||
For more information about the REST API endpoints that are available to {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/rest/overview/endpoints-available-for-github-apps).
|
||||
@@ -62,7 +62,7 @@ For more information about the REST API endpoints that are available to {% data
|
||||
|
||||
If you want to access {% data variables.product.prodname_dotcom %} resources on behalf of a user or in an organization, or you anticipate a long-lived integration, we recommend building a {% data variables.product.prodname_github_app %}.
|
||||
|
||||
You can use {% data variables.product.pat_generic_plural %} for API testing or short-lived scripts. Since a {% data variables.product.pat_generic %} is associated with a user, your automation could break if the user no longer has access to the resources you need. A {% data variables.product.prodname_github_app %} installed in an organization is not dependent on a user. Additionally, unlike a user, a {% data variables.product.prodname_github_app %} does not consume a {% data variables.product.company_short %} {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}.
|
||||
You can use {% data variables.product.pat_generic_plural %} for API testing or short-lived scripts. Since a {% data variables.product.pat_generic %} is associated with a user, your automation could break if the user no longer has access to the resources you need. A {% data variables.product.prodname_github_app %} installed on an {% ifversion enterprise-installed-apps %}enterprise or {% endif %}organization is not dependent on a user. Additionally, unlike a user, a {% data variables.product.prodname_github_app %} does not consume a {% data variables.product.company_short %} {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}.
|
||||
|
||||
{% data variables.product.company_short %} supports two types of {% data variables.product.pat_generic_plural %}, but recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible. For more information about {% data variables.product.pat_generic_plural %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#types-of-personal-access-tokens).
|
||||
|
||||
@@ -72,7 +72,7 @@ For more information about the REST API endpoints that are available to {% data
|
||||
|
||||
_{% data variables.product.prodname_actions %}_ provide automation that can perform jobs like continuous integration, deployment tasks, and project management in a repository. They run directly on {% data variables.product.prodname_dotcom %}-hosted runner machines or self-hosted runners that your administrator sets up. {% data variables.product.prodname_actions %} do not run persistently. {% data variables.product.prodname_actions %} workflows run in response to events that occur in their repository, and only have access to the resources of the repository that they are set up for. However, custom actions can be shared across repositories and organizations, allowing developers to reuse and modify existing actions to meet their needs. {% data variables.product.prodname_actions %} also come with built-in secret management, which you can use to securely interact with third-party services and manage deploy keys safely.
|
||||
|
||||
_{% data variables.product.prodname_github_apps %}_ run persistently on a server or compute infrastructure that you provide or run on a user device. They can react to {% data variables.product.company_short %} webhook events as well as events from outside the {% data variables.product.prodname_dotcom %} ecosystem. They are a good option for operations that span multiple repositories or organizations, or for providing hosted services to other organizations. A {% data variables.product.prodname_github_app %} is the best choice when building a tool with functions that occur primarily outside of {% data variables.product.prodname_dotcom %} or require more execution time or permissions than what a {% data variables.product.prodname_actions %} workflow is allotted.
|
||||
_{% data variables.product.prodname_github_apps %}_ run persistently on a server or compute infrastructure that you provide or run on a user device. They can react to {% data variables.product.company_short %} webhook events as well as events from outside the {% data variables.product.prodname_dotcom %} ecosystem. They are a good option for operations that span multiple repositories or organizations, or for providing hosted services to other organizations and enterprises. A {% data variables.product.prodname_github_app %} is the best choice when building a tool with functions that occur primarily outside of {% data variables.product.prodname_dotcom %} or require more execution time or permissions than what a {% data variables.product.prodname_actions %} workflow is allotted.
|
||||
|
||||
For more information about comparing {% data variables.product.prodname_actions %} to {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#comparing-github-actions-to-github-apps).
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ To make an API request as an installation, you must first generate an installati
|
||||
|
||||
Some REST API endpoints do not accept installation access tokens, and most REST API endpoints require your app to have certain permissions to use an endpoint. To see whether a REST API endpoint accepts installation access tokens and to see what permissions are required, refer to the documentation for the endpoint.
|
||||
|
||||
App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test that your app has the required permissions for the GraphQL queries and mutations that you want to make.
|
||||
App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test that your app has the required permissions for the GraphQL queries and mutations that you want to make.{% ifversion enterprise-installed-apps %} For example, if you want to use the `createEnterpriseOrganization` mutation to create an organization in your enterprise, your app must have the `enterprise_organizations:write` permission.{% endif %}
|
||||
|
||||
You can also use an installation access token to authenticate for HTTP-based Git access. Your app must have the "Contents" repository permission. You can then use the installation access token as the HTTP password. Replace `TOKEN` with the installation access token: `git clone https://x-access-token:TOKEN@github.com/owner/repo.git`.
|
||||
|
||||
|
||||
@@ -12,9 +12,9 @@ shortTitle: Authenticate as an app
|
||||
|
||||
## About authentication as a {% data variables.product.prodname_github_app %}
|
||||
|
||||
You must authenticate as a {% data variables.product.prodname_github_app %} in order to make REST API requests as the application. For example, if you want to use the API to generate an installation access token for accessing organization resources, list installations across organizations for your app, or suspend an app installation, you must authenticate as an app.
|
||||
You must authenticate as a {% data variables.product.prodname_github_app %} in order to make REST API requests as the application. For example, if you want to use the API to generate an installation access token for accessing organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %} resources, list installations across accounts for your app, or suspend an app installation, you must authenticate as an app.
|
||||
|
||||
If a REST API endpoint requires you to authenticate as an app, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint. The GraphQL API does not support any queries or mutations that require you to authenticate as an app.
|
||||
If a REST API endpoint requires you to authenticate as an app, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint. The GraphQL API does not support any queries or mutations that require you to authenticate with a JWT.
|
||||
|
||||
## Using a JSON Web Token (JWT) to authenticate as a {% data variables.product.prodname_github_app %}
|
||||
|
||||
|
||||
@@ -23,12 +23,18 @@ Your app can make API requests on behalf of a user. API requests made by an app
|
||||
|
||||
Similarly, if the request triggers a corresponding entry in the audit logs and security logs, the logs will list the user as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token".
|
||||
|
||||
To make an API request on behalf of a user, the user must authorize your app. If an app is installed on an organization that includes multiple members, each member will need to authorize the app before the app can act on their behalf. An app does not need to be installed in order for a user to authorize the app.
|
||||
To make an API request on behalf of a user, the user must authorize your app. If an app is installed on an organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %} that includes multiple members, each member will need to authorize the app before the app can act on their behalf. An app does not need to be installed in order for a user to authorize the app.
|
||||
|
||||
When a user installs an app on their account or organization, they grant the app permission to access the organization and repository resources that it requested. During the installation process, they will also see a list of account permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested.
|
||||
When a user installs an app on an account, they grant the app permission to access the resources that it requested. During the installation process, they will also see a list of account permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested.
|
||||
|
||||
Once a user has authorized your app, you can generate a user access token, which is a type of OAuth token. You should send the user access token in the `Authorization` header of your subsequent API requests. For more information about prompting a user to authorize your app and generating a user access token, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
|
||||
|
||||
When operating on behalf of a user, your app's access is limited to ensure secure and appropriate access:
|
||||
|
||||
* The app can only access resources that the user has access to. If a user does not have access to a repository, your app cannot access that repository on their behalf even if the app is installed on that repository.
|
||||
* The app can only access resources that it has permission to access. If your app does not have the `Issues` permission, it cannot create or read issues for the user, even if the user has access to the repository.
|
||||
* The app can only access resources in an account where it is installed. If your app is only installed on a user's personal account, it cannot access resources in an organization that the user is a member of unless the app is also installed on that organization.
|
||||
|
||||
Requests made with a user access token are sometimes called "user-to-server" requests.
|
||||
|
||||
{% data reusables.user-settings.token_access_capabilities %}
|
||||
|
||||
@@ -25,7 +25,7 @@ In order to use a {% data variables.product.prodname_github_app %} to make authe
|
||||
1. Register a {% data variables.product.prodname_github_app %}. Give your {% data variables.product.prodname_github_app %} registration the necessary permissions to access the desired resources. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app).
|
||||
1. Store the app ID of your {% data variables.product.prodname_github_app %} as a {% data variables.product.prodname_actions %} configuration variable. You can find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). For more information about storing configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows).
|
||||
1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets).
|
||||
1. Install the {% data variables.product.prodname_github_app %} on your user account or organization and grant it access to any repositories that you want your workflow to access. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository).
|
||||
1. Install the {% data variables.product.prodname_github_app %} on the right account and grant it permissions and access to any repositories that you want your workflow to access. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository).
|
||||
1. In your {% data variables.product.prodname_actions %} workflow, create an installation access token, which you can use to make API requests.
|
||||
|
||||
To do this, you can use a {% data variables.product.company_short %}-owned action as demonstrated in the following example. If you prefer to not use this action, you can fork and modify the [`actions/create-github-app-token` action](https://github.com/actions/create-github-app-token), or you can write a script to make your workflow create an installation token manually. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
|
||||
|
||||
@@ -25,9 +25,19 @@ topics:
|
||||
|
||||
Although {% data variables.product.prodname_github_apps %} don't have any permissions by default, they do have implicit permissions to read public resources when acting on behalf of a user. When a user authorizes the app to act on their behalf, the {% data variables.product.prodname_github_app %} can use the resulting user access token to make requests to the REST API and the GraphQL API to read public resources. To learn more about acting on behalf of a user, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).
|
||||
|
||||
App permissions are classified as repository, organization, or account permissions. Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed. Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account. Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).
|
||||
App permissions are classified as repository, organization,{% ifversion enterprise-installed-apps %} enterprise,{% endif %} or account permissions.
|
||||
|
||||
When a user installs an app on their account or organization, they see and grant the repository and organization permissions that the app requested. They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested.
|
||||
* Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed.
|
||||
* Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account.
|
||||
{%- ifversion enterprise-installed-apps %}
|
||||
* Enterprise permissions allow the app to manage an enterprise, if it is installed on an enterprise account.{%- endif %}
|
||||
* Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).
|
||||
|
||||
{% ifversion enterprise-installed-apps %}
|
||||
|
||||
Enterprise permissions are only available if you are creating the app in an enterprise account or an organization that is enterprise-owned. An app with enterprise permissions must be `public` or `internal` to be installed on an enterprise account. The only enterprise it can be installed on is the enterprise that owns the app or the organization that owns the app, but there are no additional restrictions on which organizations or personal accounts it can be installed on.{% endif %}
|
||||
|
||||
When a user installs an app on their user account or organization, they see and grant the repository and organization permissions that the app requested.{% ifversion enterprise-installed-apps %} When they install it on their enterprise, they see and grant only the enterprise permissions that the app requested. {% endif %}They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested.
|
||||
|
||||
The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions.
|
||||
|
||||
@@ -39,7 +49,8 @@ Some webhooks and API access requires "Administration" permissions. If your app
|
||||
|
||||
You can modify the permissions for apps you own or manage at any time.{% ifversion enterprise-apps-public-beta %}
|
||||
|
||||
* When you modify the permissions of an app owned by an **enterprise account**, the changes are automatically accepted by organizations in the enterprise.
|
||||
* When an enterprise owner modifies the permissions of an app owned by an **enterprise account**, the changes are automatically accepted by organizations in the enterprise.{% ifversion enterprise-app-manager %}
|
||||
* When an enterprise app manager modifies the permissions of an app owned by an **enterprise account**, the changes are automatically accepted by organizations in the enterprise where the app manager is also an organization owner.{% endif %}
|
||||
* When you modify the permissions of an app owned by a **user or organization**,{% else %} When you do so,{% endif %} the owner of each account where the app was installed will be prompted to approve the new permissions. If the account owner does not approve the new permissions, their installation will continue to use the old permissions.
|
||||
|
||||
For more information about modifying permissions, see [AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Making a GitHub App public or private
|
||||
intro: 'When registering a {% data variables.product.prodname_github_app %}, you can make it public so that other GitHub users or organizations can install the app, or private so that you can only install it on the account that owns the app.'
|
||||
intro: 'When registering a {% data variables.product.prodname_github_app %}, you can make it public so that other GitHub accounts can install the app, or private so that you can only install it on the account that owns the app.'
|
||||
redirect_from:
|
||||
- /apps/building-integrations/setting-up-and-registering-github-apps/about-installation-options-for-github-apps
|
||||
- /apps/building-github-apps/installation-options-for-github-apps
|
||||
@@ -27,8 +27,10 @@ A {% data variables.product.prodname_github_app %} can be {% ifversion fpt %}pub
|
||||
{% elsif ghes %} If you set your {% data variables.product.prodname_github_app %} registration to public, anyone on your {% data variables.product.prodname_ghe_server %} instance can install it, but the app is not available outside of your instance. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app. {% endif %}
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}
|
||||
{% data variables.product.prodname_github_apps %} owned by an enterprise account{% ifversion ghec %}, or by a {% data variables.enterprise.prodname_managed_user %} in an enterprise,{% endif %} have "internal" visibility. Internal apps can only be installed by organizations within the enterprise and authorized by users within the enterprise. Members of the enterprise and unaffiliated users can authorize these apps, but outside collaborators cannot.
|
||||
{% endif %}
|
||||
{% data variables.product.prodname_github_apps %} owned by an enterprise account{% ifversion ghec %}, or by a {% data variables.enterprise.prodname_managed_user %} in an enterprise,{% endif %} have "internal" visibility. Internal apps can only be installed by{% ifversion enterprise-installed-apps %} that enterprise and{% endif %} organizations within the enterprise and can only be authorized by users within the enterprise. Members of the enterprise and unaffiliated users can authorize these apps, but outside collaborators cannot.
|
||||
{% endif %}{% ifversion enterprise-installed-apps %}
|
||||
|
||||
If you want your organization-owned application to be installed on your enterprise, transfer it to the enterprise or make it `public` or `internal`. If it is `private` it can only be installed on the organization.{% endif %}
|
||||
|
||||
If you want your {% data variables.product.prodname_github_app %} to be available to organizations in a {% data variables.product.prodname_ghe_server %} instance that you are not part of, then you need to take additional steps. For more information, see [AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server).
|
||||
|
||||
@@ -38,16 +40,16 @@ For information about changing the visibility of a {% data variables.product.pro
|
||||
|
||||
### Public installation flow
|
||||
|
||||
Public {% data variables.product.prodname_github_apps %} have a landing page with an **Install** button, so that other people can install the app in their repositories. {% ifversion fpt or ghec %}If your {% data variables.product.prodname_github_app %} is public to all users on {% data variables.product.github %}, you can also choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace).{% endif %}
|
||||
Public {% data variables.product.prodname_github_apps %} have a landing page with an **Install** button, so that other people can install the app on their accounts. {% ifversion fpt or ghec %}If your {% data variables.product.prodname_github_app %} is public to all users on {% data variables.product.github %}, you can also choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace).{% endif %}
|
||||
|
||||
### Private installation flow
|
||||
|
||||
Private {% data variables.product.prodname_github_apps %} can only be installed on the user or organization account of the app owner. Limited information about the app will exist on a landing page for the app, but the **Install** button will only be available to organization owners and app managers for the organization that owns the app, or the personal account if the {% data variables.product.prodname_github_app %} is owned by an individual account.
|
||||
Private {% data variables.product.prodname_github_apps %} can only be installed on the user or organization account of the app owner. Limited information about the app will exist on a landing page for the app, and the **Install** button will only be available to organization owners and app managers for the organization that owns the app, or the personal account if the {% data variables.product.prodname_github_app %} is owned by an individual account.
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}
|
||||
|
||||
### "Internal" installation flow
|
||||
|
||||
Enterprise-owned {% data variables.product.prodname_github_apps %}{% ifversion ghec %} and apps owned by {% data variables.enterprise.prodname_managed_users %}{% endif %} can only be installed by organization owners of organizations within the enterprise by using the installation URL. The app can not be installed on user accounts.
|
||||
Enterprise-owned {% data variables.product.prodname_github_apps %}{% ifversion ghec %} and apps owned by {% data variables.enterprise.prodname_managed_users %}{% endif %} can only be installed on {% ifversion enterprise-installed-apps %}that enterprise and{% endif %} organizations within the enterprise by using the installation URL. The app can not be installed on user accounts.
|
||||
|
||||
{% endif %}
|
||||
|
||||
@@ -26,7 +26,7 @@ You can register a {% data variables.product.prodname_github_app %} in a few dif
|
||||
* Under your **personal account**.
|
||||
* Under an **organization you own**.
|
||||
* Under an **organization** that has granted you permission to manage all its apps. See [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization).{% ifversion enterprise-apps-public-beta %}
|
||||
* Under your **enterprise**, but it can only be installed on organizations within the enterprise.
|
||||
* Under your **enterprise**, but it can only be installed on{% ifversion enterprise-installed-apps %} that enterprise and{% endif %} organizations within the enterprise.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.apps.maximum-github-apps-allowed %}
|
||||
@@ -40,8 +40,8 @@ You can register a {% data variables.product.prodname_github_app %} in a few dif
|
||||
|
||||
The name must be unique across {% data variables.product.company_short %}. You cannot use the same name as an existing {% data variables.product.company_short %} account, unless it is your own user or organization name.
|
||||
|
||||
1. Optionally, under "Description", type a description of your app. Users and organizations will see this description when they install your app.
|
||||
1. Under "Homepage URL", type the full URL to your app's website. If you don’t have a dedicated URL and your app's code is stored in a public repository, you can use that repository URL. Or, you can use the URL of the organization or user that owns the app.
|
||||
1. Optionally, under "Description", type a description of your app. Users will see this description when they install your app.
|
||||
1. Under "Homepage URL", type the full URL to your app's website. If you don’t have a dedicated URL and your app's code is stored in a public repository, you can use that repository URL. Or, you can use the URL of the account that owns the app.
|
||||
1. Optionally, under "Callback URL", enter the full URL to redirect to after a user authorizes the installation.
|
||||
|
||||
You can enter up to 10 callback URLs. To add additional callback URLs, click **Add callback URL**.
|
||||
|
||||
@@ -23,7 +23,9 @@ To receive webhook events in your {% data variables.product.prodname_github_app
|
||||
|
||||
If your {% data variables.product.prodname_github_app %} does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function for your {% data variables.product.prodname_github_app %} registration. You do not need to specify a webhook URL.
|
||||
|
||||
For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). For more information about changing the webhooks that a {% data variables.product.prodname_github_app %} registration subscribes to, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app).
|
||||
For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). For more information about changing the webhooks that a {% data variables.product.prodname_github_app %} registration subscribes to, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app).{% ifversion enterprise-installed-apps %}
|
||||
|
||||
Apps installed on an enterprise do not support webhooks at this time. They must be installed on organizations in order to receive webhooks.{% endif %}
|
||||
|
||||
## Choosing a webhook URL
|
||||
|
||||
|
||||
@@ -1,15 +1,18 @@
|
||||
---
|
||||
title: About GitHub App managers
|
||||
intro: 'Organization owners can grant or revoke access for a user to manage some or all of the {% data variables.product.prodname_github_app %} registrations owned by the organization.'
|
||||
intro: 'App managers can manage some or all of the {% data variables.product.prodname_github_app %} registrations owned by an account.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Organizations
|
||||
- Enterprise
|
||||
- Teams
|
||||
- GitHub Apps
|
||||
shortTitle: GitHub App managers
|
||||
---
|
||||
|
||||
{% data reusables.apps.github-app-managers %} For more information about how to designate someone as a {% data variables.product.prodname_github_app %} manager, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization).
|
||||
{% data reusables.apps.github-app-managers %}
|
||||
|
||||
For more information about how to designate someone as a {% data variables.product.prodname_github_app %} manager in an organization, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization). {% ifversion enterprise-app-manager %} For more information about how to designate someone as a {% data variables.product.prodname_github_app %} manager in an enterprise, see [AUTOTITLE](/admin/managing-your-enterprise-account/adding-and-removing-github-app-managers-in-your-enterprise).{% endif %}
|
||||
|
||||
@@ -41,4 +41,4 @@ When you delete a {% data variables.product.prodname_github_app %} registration,
|
||||
1. In the confirmation box, type the name of the {% data variables.product.prodname_github_app %} to confirm you want to delete it.
|
||||
1. Click **I understand the consequences, delete this {% data variables.product.prodname_github_app %}**.
|
||||
|
||||
These steps only delete your {% data variables.product.prodname_github_app %} registration, and all of the organization and account installations it may have. They do not delete any code that you wrote for your app. However, any code that relies on your {% data variables.product.prodname_github_app %}'s credentials will no longer function.
|
||||
These steps only delete your {% data variables.product.prodname_github_app %} registration, and all of the installations it may have. They do not delete any code that you wrote for your app. However, any code that relies on your {% data variables.product.prodname_github_app %}'s credentials will no longer function.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Managing allowed IP addresses for a GitHub App
|
||||
intro: 'You can add an IP allow list to your {% data variables.product.prodname_github_app %} registration to prevent your app from being blocked by an organization''s own allow list.'
|
||||
intro: 'You can add an IP allow list to your {% data variables.product.prodname_github_app %} registration to prevent your app from being blocked by an enterprise or organization''s own allow list.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
@@ -13,16 +13,16 @@ redirect_from:
|
||||
|
||||
## About IP address allow lists for {% data variables.product.prodname_github_apps %}
|
||||
|
||||
Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that are allowed to connect. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise).
|
||||
Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that actors can use to access their resources. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise).
|
||||
|
||||
When an organization has an allow list, third-party applications that connect via a {% data variables.product.prodname_github_app %} will be denied access unless either of the following condition sets are true:
|
||||
When an organization or enterprise has an allow list, third-party applications that connect via a {% data variables.product.prodname_github_app %} will be denied access unless either of the following condition sets are true:
|
||||
|
||||
* The creator of the {% data variables.product.prodname_github_app %} has configured an allow list for the application that specifies the IP addresses at which their application runs. See below for details of how to do this, and
|
||||
* The organization owner has chosen to permit the addresses in the {% data variables.product.prodname_github_app %}'s allow list to be added to their own allow list. For more information, see [Managing allowed IP addresses for your organization](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}
|
||||
* The creator of the {% data variables.product.prodname_github_app %} has configured an allow list for the application that specifies the IP addresses at which their application runs. See below for details of how to do this, **and**
|
||||
* The organization or enterprise owner has chosen to permit the addresses in the {% data variables.product.prodname_github_app %}'s allow list to be added to their own allow list. For more information, see [Managing allowed IP addresses for your organization](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}
|
||||
|
||||
or
|
||||
|
||||
* The organization owner has added an IP allow list entry for the IP addresses from which the application runs. See [Adding an allowed IP address](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}
|
||||
* The organization or enterprise owner has added an IP allow list entry for the IP addresses from which the application runs. See [Adding an allowed IP address](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}
|
||||
|
||||
{% data reusables.apps.ip-allow-list-only-apps %}
|
||||
|
||||
|
||||
@@ -77,7 +77,13 @@ If you select **Request user authorization (OAuth) during installation**, you wi
|
||||
|
||||
You can change the access permissions that are granted to your {% data variables.product.prodname_github_app %} using the following steps.
|
||||
|
||||
When you change the **repository** or **organization** permissions of an app, each account where the app is installed will need to approve the new permissions. When you change the **account** permissions of an app, each user that has authorized the app will need to approve the permission changes. In both cases, {% data variables.product.prodname_dotcom %} will send an email to each organization owner or user, notifying them of the request to update the app's permissions. Updated permissions won't take effect on an installation or user authorization until the new permissions are approved. You can use the [installation webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to find out when people accept new permissions for your app.
|
||||
When you add new **repository**{% ifversion enterprise-installed-apps %}, **organization**, or **enterprise**{% else %} or **organization**{% endif %} permissions for an app, each account where the app is installed will need to approve the new permissions. When you add **account** permissions for an app, each user that has authorized the app will need to approve the permission changes. In both cases, {% data variables.product.prodname_dotcom %} will send an email to each organization owner or user, notifying them of the request to update the app's permissions. Updated permissions won't take effect on an installation or user authorization until the new permissions are approved. You can use the [installation webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to find out when people accept new permissions for your app.
|
||||
|
||||
If you remove permissions or webhooks from your {% data variables.product.prodname_github_app %}, the changes will take effect immediately. If you remove permissions that were previously granted to your app, the app will no longer be able to access those resources.
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}If you change the permissions of an app owned by an enterprise, the changes will take effect immediately for all installations of the app within the enterprise{% ifversion enterprise-app-manager %} if you are an enterprise owner. If you are an app manager, the changes will only be automatically accepted in organizations where you are an organization owner{% endif %}.
|
||||
|
||||
Updates cannot be automatically accepted if you add repository permissions to an app for the first time. In that case, each organization owner will need to approve the update so that they can choose which repositories the app has access to.{% endif %}
|
||||
|
||||
Changing the permissions of an app may also change the webhooks that your app can subscribe to and the actions that your app can take with the API. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app).
|
||||
|
||||
@@ -114,7 +120,7 @@ You can change the webhook events that a {% data variables.product.prodname_gith
|
||||
You can change the visibility settings of your {% data variables.product.prodname_github_app %} to control who can install it. Public apps cannot be made private if they're installed on other accounts. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private).
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}
|
||||
You can't change the visibility of an {% data variables.product.prodname_github_app %} owned by an enterprise. {% data variables.product.prodname_github_apps %} owned by an enterprise can only be installed on organizations within the enterprise.
|
||||
You can't change the visibility of an {% data variables.product.prodname_github_app %} owned by an enterprise. {% data variables.product.prodname_github_apps %} owned by an enterprise can only be installed on organizations within the enterprise{% ifversion enterprise-installed-apps %} or the enterprise itself{% endif %}.
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.apps.navigate-to-app-settings-this-article %}
|
||||
|
||||
@@ -19,8 +19,8 @@ shortTitle: Suspend an installation
|
||||
|
||||
When a {% data variables.product.prodname_github_app %} is suspended for an installation, the {% data variables.product.prodname_github_app %} cannot access resources owned by that installation account. For example, you might want to suspend your {% data variables.product.prodname_github_app %} if you are worried that your app's credentials were leaked.
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can suspend the {% data variables.product.prodname_github_app %} for a specific installation. If an organization has designated any app managers for an app owned by the organization, the app managers can also suspend the {% data variables.product.prodname_github_app %} for a specific installation. {% data variables.product.prodname_github_app %} owners and managers can only use the API to suspend their app, and they must suspend the app individually for each installation. For more information, see [AUTOTITLE](/rest/apps/apps#suspend-an-app-installation).
|
||||
The owner of a {% data variables.product.prodname_github_app %} and designated app managers can suspend the {% data variables.product.prodname_github_app %} for a specific installation. {% data variables.product.prodname_github_app %} owners and managers can only use the API to suspend their app, and they must suspend the app individually for each installation. For more information, see [AUTOTITLE](/rest/apps/apps#suspend-an-app-installation).
|
||||
|
||||
Users who installed a {% data variables.product.prodname_github_app %} on their personal account or organization can also suspend a {% data variables.product.prodname_github_app %} from accessing resources owned by their account. People who have installed a {% data variables.product.prodname_github_app %} can only use the {% data variables.product.company_short %} web interface to suspend their app. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).
|
||||
Users who installed a {% data variables.product.prodname_github_app %} on their personal account or an account they own can also suspend a {% data variables.product.prodname_github_app %} from accessing resources owned by their account. People who have installed a {% data variables.product.prodname_github_app %} can only use the {% data variables.product.company_short %} web interface to suspend their app. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).
|
||||
|
||||
A {% data variables.product.prodname_github_app %} must be unsuspended in the same way it was suspended. If an owner or manager of a {% data variables.product.prodname_github_app %} suspended the app, they can also unsuspend it, but the owner of an account where the app is installed cannot unsuspend it. Similarly, if the owner of an account where a {% data variables.product.prodname_github_app %} is installed suspended the app, they can also unsuspend it, but an owner or manager of the app cannot unsuspend it.
|
||||
|
||||
@@ -17,7 +17,7 @@ shortTitle: Transfer ownership
|
||||
|
||||
## About transferring {% data variables.product.prodname_github_apps %}
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} registration can transfer ownership of the {% data variables.product.prodname_github_app %} registration to another account. If an organization has designated any app managers for an app owned by the organization, the app managers can also transfer ownership of the {% data variables.product.prodname_github_app %} registration. For more information about app managers, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization).
|
||||
The owner of a {% data variables.product.prodname_github_app %} registration can transfer ownership of the {% data variables.product.prodname_github_app %} registration to another account. App managers can also transfer ownership of the {% data variables.product.prodname_github_app %} registration. For more information about app managers, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).
|
||||
|
||||
You can transfer apps from a user or organization to another account. You cannot transfer ownership to a team.
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ shortTitle: App manifest
|
||||
## About {% data variables.product.prodname_github_app %} Manifests
|
||||
|
||||
{% ifversion enterprise-apps-public-beta %}
|
||||
>[!NOTE] {% data variables.product.prodname_github_app %} Manifests are not available for enterprise-owned {% data variables.product.prodname_github_apps %}.
|
||||
>[!NOTE] {% data variables.product.prodname_github_app %} Manifests are not available for enterprise-owned {% data variables.product.prodname_github_apps %}.{% ifversion enterprise-installed-apps %} They do not support enterprise permissions at this time.{% endif %}
|
||||
{% endif %}
|
||||
|
||||
When someone registers a {% data variables.product.prodname_github_app %} from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the {% data variables.product.prodname_github_app %} registration and generates the app's webhook secret, private key (PEM file), client secret, and {% data variables.product.prodname_github_app %} ID. The person who creates the {% data variables.product.prodname_github_app %} registration from the manifest will own the {% data variables.product.prodname_github_app %} registration and can choose to edit the registration's settings, delete it, or transfer it to another person on {% data variables.product.prodname_dotcom %}.
|
||||
@@ -179,7 +179,7 @@ You must complete this step of the {% data variables.product.prodname_github_app
|
||||
|
||||
For more information about the endpoint's response, see [Create a {% data variables.product.prodname_github_app %} from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest).
|
||||
|
||||
When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered {% data variables.product.prodname_github_app %} that they can install on any of their personal repositories. They can choose to extend the app using the {% data variables.product.prodname_dotcom %} APIs, transfer ownership to someone else, or delete it at any time.
|
||||
When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered {% data variables.product.prodname_github_app %} that they can install on any of their accounts. They can choose to extend the app using the {% data variables.product.prodname_dotcom %} APIs, transfer ownership to someone else, or delete it at any time.
|
||||
|
||||
## Using Probot to implement the {% data variables.product.prodname_github_app %} Manifest flow
|
||||
|
||||
|
||||
@@ -36,8 +36,7 @@ To create a custom configuration URL for a {% data variables.product.prodname_gi
|
||||
|
||||
* To register an app on a personal account, add URL parameters to: `{% data variables.product.oauth_host_code %}/settings/apps/new`
|
||||
* To register an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to register the app. {% ifversion enterprise-apps-public-beta %}
|
||||
|
||||
>[!NOTE] The URL parameters for registering a {% data variables.product.prodname_github_app %} are also available for apps owned by enterprises. Since you can only install enterprise-owned apps on organizations within that enterprise, you can use the custom configuration URL for organizations.{% endif %}
|
||||
* To register an app on an enterprise account, add URL parameters to: `{% data variables.product.oauth_host_code %}/enterprises/ENTERPRISE/settings/apps/new`. Replace `ENTERPRISE` with the name of the enterprise where you'd like the customer to register the app.{% endif %}
|
||||
|
||||
On the app registration page, the person registering the app can edit the preselected values before submitting the app. If you do not include parameters for required values (like `name`) in the URL query string, the person registering the app will need to input a value before they can register the app.
|
||||
|
||||
@@ -71,7 +70,9 @@ Parameter name | Type | Description
|
||||
|
||||
You can use query parameters to select the permissions for the {% data variables.product.prodname_github_app %} registration. For the URL query parameter, use the permission name as the query parameter name, and set the query value to one of the possible values for that permission set.
|
||||
|
||||
For example, to select "Read & write" permissions in the user interface for `contents`, your query string would include `contents=write`. To select "Read-only" permissions in the user interface for `blocking`, your query string would include `blocking=read`. To select "No access" in the user interface for `checks`, your query string would not include the `checks` permission.
|
||||
For example, to select "Read & write" permissions in the user interface for `contents`, your query string would include `contents=write`. To select "Read-only" permissions in the user interface for `blocking`, your query string would include `blocking=read`. To select "No access" in the user interface for `checks`, your query string would not include the `checks` permission.{% ifversion enterprise-installed-apps %}
|
||||
|
||||
If the owning account is not an enterprise or an enterprise-owned organization, it cannot request enterprise permissions.{% endif %}
|
||||
|
||||
For more information about permissions and {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app).
|
||||
|
||||
|
||||
@@ -25,9 +25,9 @@ For more information about how users can install your app from {% data variables
|
||||
## Sharing your {% data variables.product.prodname_github_app %} via an install link
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
If your {% data variables.product.prodname_github_app %} is public, other users and organizations {% ifversion ghec %}within your enterprise {% endif %}can install your app. For more information about making your app public, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private).
|
||||
If your {% data variables.product.prodname_github_app %} is public, other users and organizations can install your app. For more information about making your app public, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private).
|
||||
|
||||
{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}, you can only share your app with users or organizations within your enterprise.{% endif %}
|
||||
{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}{% ifversion enterprise-apps-public-beta %} or your app is owned by your enterprise account{% endif %}, you can only share your app with accounts within your enterprise.{% endif %}
|
||||
|
||||
{% else %}
|
||||
{% endif %}
|
||||
|
||||
@@ -17,7 +17,7 @@ topics:
|
||||
## Finding {% data variables.product.prodname_github_apps %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
You can discover {% data variables.product.prodname_github_apps %} on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). {% else %}You cannot install third-party applications on your enterprise. If you want to use the functionality of a third-party app, you can contact the app developer about creating an app from a manifest or from URL parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters).{% endif %}
|
||||
You can discover {% data variables.product.prodname_github_apps %} on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). {% else %}You cannot install third-party applications on your enterprise. If you want to use the functionality of a third-party app, you can contact the app developer about creating an app from a manifest or from URL parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters).{% endif %}{% ifversion enterprise-installed-apps %} You cannot install third-party applications on your enterprise account—they must be owned by your enterprise or an organization in your enterprise.{% endif %}
|
||||
|
||||
{% data reusables.data-residency.github-marketplace-apps-unsupported %}
|
||||
|
||||
@@ -25,9 +25,11 @@ You can also build your own {% data variables.product.prodname_github_app %}. Fo
|
||||
|
||||
## Using {% data variables.product.prodname_github_apps %}
|
||||
|
||||
In order to use a {% data variables.product.prodname_github_app %}, you must install the app on your user or organization account. When you install the app, you grant the app permission to read or modify your repository and organization data. The specific permissions depends on the app, and {% data variables.product.company_short %} will tell you what permissions the app requested before you install the app. When you install the app, you will also specify what repositories the app can access. If the app requires any additional configuration, the app will direct you to do so. For more information, see {% ifversion ghec or fpt %}[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations),{% endif %} [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party) and [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app).
|
||||
In order to use a {% data variables.product.prodname_github_app %}, you must install the app on your {% ifversion enterprise-installed-apps %}enterprise, {% endif %}user or organization account. When you install the app, you grant the app permission to read or modify your account's data. The specific permissions depends on the app, and {% data variables.product.company_short %} will tell you what permissions the app requested before you install the app. When you install the app on your organization or user account, you will also specify what repositories the app can access.{% ifversion enterprise-installed-apps %} Apps installed on an enterprise account can only manage the enterprise itself, and are not granted organization or repository permissions.{% endif %}
|
||||
|
||||
You may also need to authorize a {% data variables.product.prodname_github_app %} to verify your identity, know what resources you can access, or take actions on your behalf. If you need to authorize the app, the app will prompt you to do so. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
If the app requires any additional configuration, the app will direct you to do so. For more information, see {% ifversion ghec or fpt %}[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations),{% endif %} [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party) and [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app).
|
||||
|
||||
You may also need to authorize a {% data variables.product.prodname_github_app %} to verify your identity, know what resources you can access, or take actions on your behalf. If you need to authorize the app, the app will prompt you to do so. When an app acts on your behalf, it has access to the same resources that you do as long as the app is installed on the account that owns the resources and you have given it the right permissions. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
|
||||
Occasionally, the {% data variables.product.prodname_github_app %} will request updated permissions. {% data variables.product.company_short %} will notify you when this occurs. In order for the app to continue to function, you will need to review and approve the updated permissions. For more information, see [AUTOTITLE](/apps/using-github-apps/approving-updated-permissions-for-a-github-app).
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ shortTitle: Approve new permissions
|
||||
|
||||
Occasionally, a {% data variables.product.prodname_github_app %} that you have installed will request additional permissions. This may happen if the {% data variables.product.prodname_github_app %} owner wants the app to make additional API requests or respond to additional webhook events. For more information about what different permissions enable a {% data variables.product.prodname_github_app %} to do, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app).
|
||||
|
||||
When a {% data variables.product.prodname_github_app %} requests additional organization or repository permissions, {% data variables.product.company_short %} will notify you if the app is installed on your personal account or on an organization that you own.
|
||||
When a {% data variables.product.prodname_github_app %} requests additional permissions, {% data variables.product.company_short %} will notify you if the app is installed on your personal account or on an account that you own.
|
||||
|
||||
You can choose whether to accept the additional permissions. If you do not approve the additional permissions, the {% data variables.product.prodname_github_app %} will still retain its current permissions. The {% data variables.product.prodname_github_app %} may not function as expected if you do not approve the additional permissions.
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ You can review and revoke your authorization at any time. For more information,
|
||||
{% ifversion ghec %}
|
||||
|
||||
> [!NOTE]
|
||||
> If your organization uses SAML SSO and you cannot see your organization's resources after you authorize a {% data variables.product.prodname_github_app %}, you may need to reauthorize the app after starting an active SAML session for your organization. For more information, see [AUTOTITLE](/apps/using-github-apps/saml-and-github-apps).
|
||||
> If your organization uses SSO and you cannot see your organization's resources after you authorize a {% data variables.product.prodname_github_app %}, you may need to reauthorize the app after starting an active SSO session for your organization. For more information, see [AUTOTITLE](/apps/using-github-apps/saml-and-github-apps).
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
@@ -16,6 +16,7 @@ children:
|
||||
- /installing-a-github-app-from-github-marketplace-for-your-organizations
|
||||
- /installing-a-github-app-from-a-third-party
|
||||
- /installing-your-own-github-app
|
||||
- /installing-a-github-app-on-your-enterprise
|
||||
- /requesting-a-github-app-from-your-organization-owner
|
||||
- /authorizing-github-apps
|
||||
- /approving-updated-permissions-for-a-github-app
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Installing a GitHub App from a third party
|
||||
intro: 'You can install {% data variables.product.prodname_github_apps %} directly from the app owner to use on your personal account or organizations.'
|
||||
intro: 'You can install {% data variables.product.prodname_github_apps %} directly from the app owner to use on your account.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
@@ -38,21 +38,24 @@ For more information about authorizing {% data variables.product.prodname_github
|
||||
|
||||
## Requirements to install a {% data variables.product.prodname_github_app %}
|
||||
|
||||
Anyone can install {% data variables.product.prodname_github_apps %} on their personal account.
|
||||
Anyone can install {% data variables.product.prodname_github_apps %} on their personal account{% ifversion ghec %}, unless they are an {% data variables.product.prodname_emu %}{% endif %}.
|
||||
|
||||
Organization owners can install {% data variables.product.prodname_github_apps %} on their organization.
|
||||
Organization owners can install {% data variables.product.prodname_github_apps %} on their organization.{% ifversion enterprise-installed-apps %}
|
||||
|
||||
Enterprise owners can install {% data variables.product.prodname_github_apps %} on their enterprise accounts, if the application requests enterprise permissions and is owned by the enterprise or one of its organizations.
|
||||
{% endif %}
|
||||
|
||||
Admins of repositories that are owned by an organization can also install {% data variables.product.prodname_github_apps %} on the organization if they only grant the app access to repositories that they are an admin of and if the app does not request any organization permissions or the "repository administration" permission. Organization owners can prevent outside collaborators who are repository admins from installing {% data variables.product.prodname_github_apps %}.
|
||||
|
||||
Organization members who are not organization owners or repository admins can still select the organization during the install process. Instead of installing the app, {% data variables.product.company_short %} will send a notification to the organization owner to request the organization owner to install the app.
|
||||
|
||||
The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. See [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).
|
||||
The "app manager" role does not give a person the ability to install a {% data variables.product.prodname_github_app %} on the organization{% ifversion enterprise-app-manager %} or enterprise{% endif %}. See [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).
|
||||
|
||||
## Installing a {% data variables.product.prodname_github_app %}
|
||||
|
||||
During the installation process, the app owner will direct you to a {% data variables.product.company_short %} URL to install the {% data variables.product.prodname_github_app %}. The URL will look something like `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}.
|
||||
|
||||
1. Select the location where you want to install the {% data variables.product.prodname_github_app %}. You can select your personal account or an organization that you are a member of.
|
||||
1. Select the location where you want to install the {% data variables.product.prodname_github_app %}. You can select your personal account or an organization that you are a member of.{% ifversion enterprise-installed-apps %} If you are an enterprise owner, you can also choose to install the app on your enterprise, if the app supports enterprises.{% endif %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
@@ -68,6 +71,6 @@ During the installation process, the app owner will direct you to a {% data vari
|
||||
|
||||
If the app creates any repositories, the app will automatically be granted access to those repositories as well.
|
||||
1. Review the permissions that the app is requesting. For more information about the REST API requests the {% data variables.product.prodname_github_app %} can make with those permissions, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps).
|
||||
1. Click **Install**, **Install and request**, or **Request**. The button that is presented depends on whether your organization owner must approve none, some, or all of the requested access for the app. For more information, see [Requirements to install a {% data variables.product.prodname_github_app %}](#requirements-to-install-a-github-app).
|
||||
1. Click **Install**, **Install and request**, or **Request**. The button that is presented depends on whether your organization owner must approve none, some, or all of the requested access for the app.{% ifversion enterprise-installed-apps %} Enterprise installations cannot be requested—the enterprise owner must install the app directly.{% endif %} For more information, see [Requirements to install a {% data variables.product.prodname_github_app %}](#requirements-to-install-a-github-app).
|
||||
|
||||
{% endif %}
|
||||
|
||||
@@ -48,7 +48,7 @@ For enterprises that pay by credit card, enterprise owners who are also organiza
|
||||
|
||||
Admins of repositories that are owned by an organization can also install {% data variables.product.prodname_github_apps %} on the organization if they only grant the app access to repositories that they are an admin of and if the app does not request any organization permissions or the "repository administration" permission. Organization owners can prevent outside collaborators who are repository admins from installing {% data variables.product.prodname_github_apps %}.
|
||||
|
||||
The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).
|
||||
The "app manager" role does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization{% ifversion enterprise-app-manager %} or enterprise{% endif %}. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers).
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Installing a GitHub App on your enterprise
|
||||
intro: 'You can install {% data variables.product.prodname_github_apps %} on your enterprise to manage your enterprise account and perform enterprise-level operations.'
|
||||
versions:
|
||||
feature: enterprise-installed-apps
|
||||
shortTitle: Install apps on your enterprise
|
||||
permissions: 'Enterprise owners can install {% data variables.product.prodname_github_apps %} on their enterprise. App managers cannot install apps at the enterprise level.'
|
||||
---
|
||||
|
||||
> [!NOTE]
|
||||
> Enterprise-installed {% data variables.product.prodname_github_apps %} are in {% data variables.release-phases.public_preview %} and subject to change.
|
||||
|
||||
## About installing {% data variables.product.prodname_github_apps %} on your enterprise
|
||||
|
||||
Enterprise-installed {% data variables.product.prodname_github_apps %} are apps that request enterprise-level permissions and can perform operations on your enterprise account. Unlike organization or user installations, they do not have access to any organization or repository permissions—they only manage the enterprise itself.
|
||||
|
||||
When an enterprise owner installs a {% data variables.product.prodname_github_app %} on your enterprise, the app will be granted the enterprise permissions it requested. These permissions allow the app to perform operations such as creating organizations in the enterprise, installing applications across organizations, and managing SCIM provisioning.
|
||||
|
||||
## Requirements to install a {% data variables.product.prodname_github_app %} on your enterprise
|
||||
|
||||
The {% data variables.product.prodname_github_app %} must request enterprise-level permissions. It can request other permissions as well, but only the enterprise permissions will be granted during installation.
|
||||
|
||||
The app must be owned by your enterprise or an organization within your enterprise. You cannot install apps owned by an account outside your enterprise.
|
||||
|
||||
## Installing a {% data variables.product.prodname_github_app %} on your enterprise
|
||||
|
||||
To install an app on your enterprise, navigate to the {% data variables.product.prodname_github_app %} installation page. This may be provided by the app developer as an installation link, or you can find it in the app's registration. The URL will look something like `{% data variables.product.oauth_host_code %}/apps/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}.
|
||||
|
||||
If the app can be installed, the list of available installation locations will include your enterprise. You can select your enterprise to install the app.
|
||||
|
||||
After installation, the app will be able to create an installation token for your enterprise or sign in enterprise members in order to act on their behalf at the enterprise level. Acting on a user's behalf requires the user to be able to perform the desired operations within the enterprise. For example, if the app needs to invite a user to an enterprise, the user must have permission to invite members to the enterprise as well.
|
||||
|
||||
## What enterprise-installed apps can do
|
||||
|
||||
Enterprise-installed {% data variables.product.prodname_github_apps %} cannot call every enterprise API, but several APIs have already been updated to support GitHub Apps. These APIs and GraphQL mutations include:
|
||||
|
||||
* [List and create organizations in your enterprise](/graphql/reference/mutations#createenterpriseorganization)
|
||||
* [Manage users in your enterprise](/graphql/reference/objects#enterprise)
|
||||
* Create and manage {% data variables.product.prodname_github_app %} installations in your organizations
|
||||
* Manage enterprise custom repository properties
|
||||
* Call the enterprise SCIM APIs
|
||||
|
||||
Check the [changelog](https://github.blog/changelog/) for updates on new APIs and permissions for {% data variables.product.prodname_github_apps %}.
|
||||
|
||||
For more information about available permissions and API endpoints, see [AUTOTITLE](/rest/authentication/permissions-required-for-github-apps).
|
||||
|
||||
{% ifversion not ghes %}
|
||||
|
||||
## Rate limits for enterprise-installed {% data variables.product.prodname_github_apps %}
|
||||
|
||||
The installation token for an enterprise-installed {% data variables.product.prodname_github_apps %} has the same rate limit as a {% data variables.product.prodname_ghe_cloud %} organization. Rate limits are per installation. For example, if an app is installed on an enterprise and two organizations, it will require 3 installation tokens to access them and have a full, independent rate limit budget for each installation. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/graphql/overview/resource-limitations).
|
||||
{% endif %}
|
||||
|
||||
## Current limitations
|
||||
|
||||
Enterprise-installed {% data variables.product.prodname_github_apps %} are currently in {% data variables.release-phases.public_preview %} with the following limitations.
|
||||
|
||||
### API support
|
||||
|
||||
Not all APIs support enterprise-installed {% data variables.product.prodname_github_apps %} yet. As more permissions are built and APIs updated, support will become broader. For more information about the APIs and permissions that support enterprise-installed {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/rest/authentication/permissions-required-for-github-apps).
|
||||
|
||||
### Webhook support
|
||||
|
||||
Enterprise installations do not currently support webhooks. Apps installed at the enterprise level cannot receive webhook events for enterprise-level activities. Install them on organizations or repositories to receive webhook events for those resources.
|
||||
|
||||
### Organization access
|
||||
|
||||
Enterprise installations are not granted access to organizations or repositories within your enterprise, with the exception of the organization installations API. To access organization or repository resources, you must install the app separately on each organization where access is needed.
|
||||
|
||||
## Next steps
|
||||
|
||||
* To grant the app access to specific organizations, install it on those organizations. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party).
|
||||
* Learn about managing apps installed in your organizations. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Installing your own GitHub App
|
||||
intro: 'You can install a {% data variables.product.prodname_github_app %} that you created on the personal or organization account that owns the app. If your app is public, the {% data variables.product.prodname_github_app %} can also be installed on other accounts.'
|
||||
intro: 'You can install a {% data variables.product.prodname_github_app %} that you created on the account that owns the app. If your app is public, the {% data variables.product.prodname_github_app %} can also be installed on other accounts.'
|
||||
redirect_from:
|
||||
- /apps/installing-github-apps
|
||||
- /developers/apps/installing-github-apps
|
||||
@@ -20,9 +20,9 @@ shortTitle: Install your own app
|
||||
|
||||
After creating a {% data variables.product.prodname_github_app %}, you can install it based on its visibility.
|
||||
|
||||
* **Only on this account:** The {% data variables.product.prodname_github_app %} can only be installed on the organization or user account that created it.{% ifversion ghec %} If you are an {% data variables.product.prodname_emu %}, this option is not available for apps you create.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise.{% endif %}{% endif %}
|
||||
* **Any account:** You can install this {% data variables.product.prodname_github_app %} on your user account or any organization account where you are an organization owner.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise.
|
||||
* **Only enterprise organizations:** If the {% data variables.product.prodname_github_app %} is owned by an enterprise, you can only install the app on organizations within the enterprise. Organizations where you are an organization owner will appear in the installation options.{% endif %}{% ifversion ghec %}
|
||||
* **Only on this account:** The {% data variables.product.prodname_github_app %} can only be installed on the account that created it.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps{% ifversion ghec %} created by a {% data variables.enterprise.prodname_managed_user %} or{% endif %} registered by an enterprise.{% endif %}
|
||||
* **Any account:** You can install this {% data variables.product.prodname_github_app %} on any account you control.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise.
|
||||
* **Only enterprise organizations:** If the {% data variables.product.prodname_github_app %} is owned by an enterprise, you can only install the app on{% ifversion enterprise-installed-apps %} that enterprise or{% endif %} organizations within the enterprise. Organizations where you are an organization owner will appear in the installation options.{% endif %}{% ifversion ghec %}
|
||||
|
||||
If you are an {% data variables.product.prodname_emu %}, you cannot install a {% data variables.product.prodname_github_app %} on your user account.{% endif %}
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ topics:
|
||||
|
||||
## About installed {% data variables.product.prodname_github_apps %}
|
||||
|
||||
{% data variables.product.company_short %} users can install {% data variables.product.prodname_github_apps %} on their personal account or organizations. When you install a {% data variables.product.prodname_github_app %}, you grant the app the organization-level and repository-level permissions that it requested. You also specify which repositories the {% data variables.product.prodname_github_app %} can access.
|
||||
{% data variables.product.company_short %} users can install {% data variables.product.prodname_github_apps %} on their personal account or accounts they own. When you install a {% data variables.product.prodname_github_app %}, you grant the app the {% ifversion enterprise-installed-apps %}enterprise or {% endif %}organization and repository permissions that it requested. If the app requested repository permissions, you also specify which repositories the {% data variables.product.prodname_github_app %} can access.{% ifversion enterprise-installed-apps %} Installing an app on an enterprise only grants enterprise permissions. To grant organization and repository permissions, install the app on an organization.{% endif %}
|
||||
|
||||
You should periodically review the {% data variables.product.prodname_github_apps %} that you have installed. You can review the permissions that you granted and change the repositories that the {% data variables.product.prodname_github_app %} can access. If you no longer use an app, consider suspending or deleting the {% data variables.product.prodname_github_app %} to block its access to resources owned by the account where it is installed.
|
||||
|
||||
@@ -20,6 +20,14 @@ In addition to reviewing {% data variables.product.prodname_github_apps %} that
|
||||
|
||||
## Navigating to the {% data variables.product.prodname_github_app %} you want to review or modify
|
||||
|
||||
{% ifversion enterprise-installed-apps %}* For a {% data variables.product.prodname_github_app %} installed on an enterprise:
|
||||
1. In the top right corner of {% data variables.product.prodname_dotcom %}, click your profile photo, then click **Your enterprises**.
|
||||
1. Next to your enterprise name, click **Settings**.
|
||||
1. In the top navigation bar, click **Settings**.
|
||||
1. In the side bar, click **GitHub Apps**. A list of the {% data variables.product.prodname_github_apps %} owned by your enterprise will be displayed.
|
||||
1. Switch to the **Installed Apps** tab to see a list of the apps installed on your enterprise.
|
||||
1. Next to the {% data variables.product.prodname_github_app %} you want to review or modify, click **Configure**.{% endif %}
|
||||
|
||||
* For a {% data variables.product.prodname_github_app %} installed on an organization:
|
||||
1. In the top right corner of {% data variables.product.prodname_dotcom %}, click your profile photo, then click **Your organizations**.
|
||||
1. Next to your organization name, click **Settings**.
|
||||
@@ -62,12 +70,12 @@ In addition to reviewing {% data variables.product.prodname_github_apps %} that
|
||||
1. Navigate to the {% data variables.product.prodname_github_app %} you want to modify. For more information, see [Navigating to the GitHub App you want to review or modify](#navigating-to-the-github-app-you-want-to-review-or-modify).
|
||||
1. To keep the {% data variables.product.prodname_github_app %} installed for future use but temporarily block it from accessing resources owned by your account, click **Suspend**.
|
||||
|
||||
When you suspend a {% data variables.product.prodname_github_app %}, your authorization of the app (if the app is installed on your personal account) or the authorization of the app by members of your organization (if the app is installed on an organization) will not be affected. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
When you suspend a {% data variables.product.prodname_github_app %}, your authorization of the app (if the app is installed on your personal account) or the authorization of the app by members of your account (if the app is installed on an organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %}) will not be affected. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
|
||||
If the {% data variables.product.prodname_github_app %} was previously suspended, you can unsuspend the app by clicking **Unsuspend**. If the {% data variables.product.prodname_github_app %} was suspended by the {% data variables.product.prodname_github_app %} owner, then you cannot unsuspend the app.
|
||||
1. To uninstall a {% data variables.product.prodname_github_app %} and block it from accessing resources owned by your account, click **Uninstall**.
|
||||
|
||||
When you uninstall a {% data variables.product.prodname_github_app %} from an account, the app will lose access to the resources in that account. The app might still be authorized to access organizations on your behalf, if it has installations in those organizations.
|
||||
When you uninstall a {% data variables.product.prodname_github_app %} from an account, the app will lose access to the resources in just that account. The app might still be authorized to access other accounts on your behalf, if it has installations in those accounts.
|
||||
|
||||
If you want to stop an app from acting on your behalf anywhere on {% data variables.product.github %}, also de-authorize the app in the "Authorized {% data variables.product.prodname_github_apps %}" tab of your user account. This will fully deactivate any tokens issued to the app on your behalf. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ You may authorize a {% data variables.product.prodname_github_app %} to give the
|
||||
|
||||
You should periodically review the {% data variables.product.prodname_github_apps %} that you have authorized. If you no longer use an app, consider revoking your authorization for that app.
|
||||
|
||||
The authorization can only be revoked by the person who authorized the {% data variables.product.prodname_github_app %}. Organization owners cannot revoke {% data variables.product.prodname_github_app %} authorizations for their organization members. However, organization owners can uninstall the {% data variables.product.prodname_github_app %} from their organization, which will prevent the app from accessing organization-owned resources. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).
|
||||
The authorization can only be revoked by the person who authorized the {% data variables.product.prodname_github_app %}. Organization{% ifversion enterprise-installed-apps %} and enterprise{% endif %} owners cannot revoke {% data variables.product.prodname_github_app %} authorizations for their members. However, organization{% ifversion enterprise-installed-apps %} and enterprise{% endif %} owners can uninstall the {% data variables.product.prodname_github_app %} from the account, which will prevent the app from accessing resources in that account. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).
|
||||
|
||||
## Reviewing your authorized {% data variables.product.prodname_github_apps %}
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: SAML and GitHub Apps
|
||||
shortTitle: SAML with apps
|
||||
intro: "If your organization is SSO protected, you may need to start an active SSO session for your organization before authorizing, installing, or requesting a {% data variables.product.prodname_github_app %}."
|
||||
intro: "If your organization or enterprise is SSO protected, you may need to start an active SSO session for your organization before authorizing, installing, or requesting a {% data variables.product.prodname_github_app %}."
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
@@ -13,17 +13,20 @@ topics:
|
||||
|
||||
If your organization or enterprise uses SSO, you may not be able to see your organization's resources or enterprise's `internal` resources after you authorize a {% data variables.product.prodname_github_app %}. For example, if the app displays a list of repositories, you may not see repositories owned by your organization. To resolve this issue, follow these steps:
|
||||
|
||||
1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` or `https://github.com/enterprises/ENTERPRISE_NAME/sso` to start an active SSO session for that account. Replace `ORGANIZATION-NAME` or `ENTERPRISE-NAME` with the name of the appropriate account. Attempting to access any resources owned by the account will aso trigger SSO if you don't have a session already.
|
||||
1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` to start an active SAML session for your organization. Replace `ORGANIZATION-NAME` with the name of your organization.
|
||||
* If your enterprise manages SSO for your organization, you can also go to `https://github.com/enterprises/ENTERPRISE-NAME/sso` to start an active SSO session for your enterprise. Replace `ENTERPRISE-NAME` with the name of your enterprise. This works as an SSO session for all organizations in the enterprise that you're a member of.
|
||||
* Attempting to access any resources owned by the account will also trigger SSO if you don't have a session already.
|
||||
1. Revoke your authorization of the {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps).
|
||||
1. Reauthorize the {% data variables.product.prodname_github_app %}. {% data variables.product.prodname_github_app %} authorization is initiated by the app and varies based on the app. For example, some {% data variables.product.prodname_github_apps %} may have you click on a link or enter a command in your terminal. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps).
|
||||
|
||||
SSO can be enforced at the organization or enterprise level. If it's enforced at the enterprise level, having an SSO session with any organization allows access to all organizations. This will appear as a credential authorization on the token for each organization you are a member of at the time of the application authorization.
|
||||
When you sign in to an app, a credential authorization is created for each organization that you have an SSO session for. SSO can be enforced at the organization or enterprise level. If it's enforced at the enterprise level, having an SSO session with any organization counts as an SSO session for each organization you're a member of. This will appear as a credential authorization on the token for each organization you are a member of at the time of the application authorization.
|
||||
|
||||
For access to `internal` data in an enterprise, such as repositories, projects, or packages, you must have an SSO session for any organization within that enterprise. Even if the organizations do not use the same SSO provider (for instance, as a result of a merger or acquisition), any organization's SSO session is sufficient for `internal` access.
|
||||
The SSO credential authorization is tied to the specific sign-in session with the app. If you plan to sign in to the app again on another device or after your SSO sessions expire, you will need to start new SSO sessions before you sign in to ensure the app can access your organization's resources.
|
||||
|
||||
## Installing or requesting {% data variables.product.prodname_github_apps %} for organizations with SSO
|
||||
|
||||
If your organization or enterprise uses SSO, you may not see your organization listed when you try to install or request an {% data variables.product.prodname_github_app %} for your organization. To resolve this issue, follow these steps:
|
||||
|
||||
1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` or `https://github.com/enterprises/ENTERPRISE_NAME/sso` to start an active SSO session for that account. Replace `ORGANIZATION-NAME` or `ENTERPRISE-NAME` with the name of the appropriate account.
|
||||
1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` to start an active SAML session for your organization. Replace `ORGANIZATION-NAME` with the name of your organization.
|
||||
* If your enterprise manages SSO for your organization, you can also go to `https://github.com/enterprises/ENTERPRISE-NAME/sso` to start an active SSO session for your enterprise. Replace `ENTERPRISE-NAME` with the name of your enterprise. This works as an SSO session for all organizations in the enterprise that you're a member of.
|
||||
1. Try to install or request the {% data variables.product.prodname_github_app %} again. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations), and [AUTOTITLE](/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner).
|
||||
|
||||
@@ -148,8 +148,8 @@ The REST API also has a separate primary rate limit. For more information, see [
|
||||
In general, you can calculate your primary rate limit for the GraphQL API based on your method of authentication:
|
||||
|
||||
* _For users_: 5,000 points per hour per user. This includes requests made with a {% data variables.product.pat_generic %} as well as requests made by a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} on behalf of a user that authorized the app. Requests made on a user's behalf by a {% data variables.product.prodname_github_app %} that is owned by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 10,000 points per hour. Similarly, requests made on your behalf by an {% data variables.product.prodname_oauth_app %} that is owned or approved by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 10,000 points per hour if you are a member of the {% data variables.product.prodname_ghe_cloud %} organization.
|
||||
* _For {% data variables.product.prodname_github_app %} installations not on a {% data variables.product.prodname_ghe_cloud %} organization_: 5,000 points per hour per installation. Installations that have more than 20 repositories receive another 50 points per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 points per hour for each user. The rate limit cannot increase beyond 12,500 points per hour. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users.
|
||||
* _For {% data variables.product.prodname_github_app %} installations on a {% data variables.product.prodname_ghe_cloud %} organization_: 10,000 points per hour per installation. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users.
|
||||
* _For {% data variables.product.prodname_github_app %} installations not on a {% data variables.product.prodname_ghe_cloud %} organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %}_: 5,000 points per hour per installation. Installations that have more than 20 repositories receive another 50 points per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 points per hour for each user. The rate limit cannot increase beyond 12,500 points per hour. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users.
|
||||
* _For {% data variables.product.prodname_github_app %} installations on a {% data variables.product.prodname_ghe_cloud %} organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %}_: 10,000 points per hour per installation. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users.
|
||||
* _For {% data variables.product.prodname_oauth_apps %}_: 5,000 points per hour, or 10,000 points per hour if the app is owned by a {% data variables.product.prodname_ghe_cloud %} organization. This only applies when the app uses their client ID and client secret to request public data. The rate limit for OAuth access tokens generated by a {% data variables.product.prodname_oauth_app %} are dictated by the primary rate limit for users.
|
||||
* _For `GITHUB_TOKEN` in {% data variables.product.prodname_actions %} workflows_: 1,000 points per hour per repository. For requests to resources that belong to an enterprise account on GitHub.com, the limit is 15,000 points per hour per repository.
|
||||
|
||||
|
||||
@@ -25,6 +25,8 @@ shortTitle: GitHub App managers
|
||||
|
||||
{% data reusables.apps.github-app-managers %}
|
||||
|
||||
For more information about {% data variables.product.prodname_github_app %} manager permissions, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers).
|
||||
|
||||
## Granting the ability to manage all {% data variables.product.prodname_github_apps %} owned by the organization
|
||||
|
||||
{%- ifversion org-app-manager-teams %}
|
||||
|
||||
@@ -17,7 +17,7 @@ autogenerated: rest
|
||||
|
||||
## About {% data variables.product.prodname_github_app %} installations
|
||||
|
||||
A {% data variables.product.prodname_github_app %} installation refers to any user or organization account that has installed the app. For information on how to authenticate as an installation and limit access to specific repositories, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
|
||||
A {% data variables.product.prodname_github_app %} installation refers to the installation of the app on an {% ifversion enterprise-installed-apps %}enterprise, {% endif %}organization or user account. For information on how to authenticate as an installation and limit access to specific repositories, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).
|
||||
|
||||
To list all {% data variables.product.prodname_github_app %} installations for an organization, see [AUTOTITLE](/rest/orgs/orgs#list-app-installations-for-an-organization).
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Redelivering {% data variables.product.prodname_github_app %} webhooks
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can redeliver webhooks for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also redeliver webhooks.
|
||||
The owner of a {% data variables.product.prodname_github_app %} can redeliver webhooks for the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also redeliver webhooks.
|
||||
|
||||
You can use the {% data variables.product.company_short %} web interface or the REST API to redeliver webhooks for a {% data variables.product.prodname_github_app %}. For more information about using the REST API redeliver, see [AUTOTITLE](/rest/apps/webhooks).
|
||||
|
||||
@@ -59,7 +59,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Redelivering {% data variables.product.prodname_marketplace %} webhooks
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can redeliver {% data variables.product.prodname_marketplace %} webhooks for that app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also redeliver webhooks.
|
||||
The owner of a {% data variables.product.prodname_github_app %} can redeliver {% data variables.product.prodname_marketplace %} webhooks for that app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also redeliver webhooks.
|
||||
|
||||
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
|
||||
1. Next to the {% data variables.product.prodname_marketplace %} listing for which you want to redeliver webhooks, click **Manage listing**.
|
||||
|
||||
@@ -50,7 +50,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Viewing deliveries for {% data variables.product.prodname_github_app %} webhooks
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can view recent webhook deliveries for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also view recent webhook deliveries.
|
||||
The owner of a {% data variables.product.prodname_github_app %} can view recent webhook deliveries for the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also view recent webhook deliveries.
|
||||
|
||||
You can use the {% data variables.product.company_short %} web interface or the REST API to view recent webhook deliveries for a {% data variables.product.prodname_github_app %}. For more information about using the REST API to view recent deliveries, see [AUTOTITLE](/rest/apps/webhooks).
|
||||
|
||||
@@ -64,7 +64,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Viewing deliveries for {% data variables.product.prodname_marketplace %} webhooks
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can view recent {% data variables.product.prodname_marketplace %} webhook deliveries for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also view recent webhook deliveries.
|
||||
The owner of a {% data variables.product.prodname_github_app %} can view recent {% data variables.product.prodname_marketplace %} webhook deliveries for the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also view recent webhook deliveries.
|
||||
|
||||
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
|
||||
1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**.
|
||||
|
||||
@@ -59,7 +59,7 @@ You can use the {% data variables.product.github %} web interface to manage glob
|
||||
|
||||
## {% data variables.product.prodname_marketplace %} webhooks
|
||||
|
||||
You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. You can only create one webhook for each app in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can create and manage a {% data variables.product.prodname_marketplace %} webhook.
|
||||
You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. You can only create one webhook for each app in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager with access to the app, can create and manage a {% data variables.product.prodname_marketplace %} webhook.
|
||||
|
||||
A {% data variables.product.prodname_marketplace %} webhook cannot be deleted, but you can deactivate it to stop receiving webhook deliveries.
|
||||
|
||||
@@ -77,7 +77,7 @@ You can use the {% data variables.product.github %} web interface to manage {% d
|
||||
|
||||
## {% data variables.product.prodname_github_app %} webhooks
|
||||
|
||||
You can configure a {% data variables.product.prodname_github_app %} to receive webhooks when specific events occur in a repository or organization that the app has been granted access to.
|
||||
You can configure a {% data variables.product.prodname_github_app %} to receive webhooks when specific events occur in a repository or organization that the app has been granted access to.{% ifversion enterprise-installed-apps %}Apps installed on an enterprise cannot receive webhooks at this time - they must be installed on each organization in the enterprise to get the events.{% endif %}
|
||||
|
||||
Each {% data variables.product.prodname_github_app %} has a single webhook that is automatically created by {% data variables.product.github %}. By default, the webhook is not subscribed to any events. You can configure the events that the webhook subscribes to. A {% data variables.product.prodname_github_app %} webhook cannot be deleted, but you can deactivate it to stop receiving webhook deliveries.
|
||||
|
||||
|
||||
@@ -98,7 +98,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Creating a {% data variables.product.prodname_marketplace %} webhook
|
||||
|
||||
You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can create a {% data variables.product.prodname_marketplace %} webhook.
|
||||
You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the app, can create a {% data variables.product.prodname_marketplace %} webhook.
|
||||
|
||||
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
|
||||
1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**.
|
||||
@@ -127,7 +127,7 @@ You can create a webhook to subscribe to events relating to your sponsorships. O
|
||||
|
||||
## Creating webhooks for a {% data variables.product.prodname_github_app %}
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can subscribe the app to webhook events to receive notifications whenever certain events occur. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also subscribe the app to webhook events. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps).
|
||||
The owner of a {% data variables.product.prodname_github_app %} can subscribe the app to webhook events to receive notifications whenever certain events occur. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also subscribe the app to webhook events. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps).
|
||||
|
||||
Each {% data variables.product.prodname_github_app %} has one webhook. You can configure the webhook when you register a {% data variables.product.prodname_github_app %}, or you can edit the webhook configuration for an existing {% data variables.product.prodname_github_app %} registration.
|
||||
|
||||
|
||||
@@ -68,7 +68,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Disabling a {% data variables.product.prodname_marketplace %} webhook
|
||||
|
||||
You can deactivate a webhook that was previously enabled for events relating to an app that you published on {% data variables.product.prodname_marketplace %}. You cannot delete the webhook. Only the owner of the app can deactivate the {% data variables.product.prodname_marketplace %} webhook for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also deactivate the {% data variables.product.prodname_marketplace %} webhook.
|
||||
You can deactivate a webhook that was previously enabled for events relating to an app that you published on {% data variables.product.prodname_marketplace %}. You cannot delete the webhook. Only the owner of the app can deactivate the {% data variables.product.prodname_marketplace %} webhook for the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also deactivate the {% data variables.product.prodname_marketplace %} webhook.
|
||||
|
||||
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
|
||||
1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**.
|
||||
@@ -89,7 +89,7 @@ You can disable webhooks that were previously enabled for events relating to {%
|
||||
|
||||
## Disabling webhooks for a {% data variables.product.prodname_github_app %}
|
||||
|
||||
Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can deactivate the webhook. The owner of a {% data variables.product.prodname_github_app %} can deactivate the webhook the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also deactivate the webhook for the app.
|
||||
Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can deactivate the webhook. The owner of a {% data variables.product.prodname_github_app %} can deactivate the webhook the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also deactivate the webhook for the app.
|
||||
|
||||
{% data reusables.apps.settings-step %}
|
||||
{% data reusables.apps.enterprise-apps-steps %}
|
||||
|
||||
@@ -65,7 +65,7 @@ You can use the {% data variables.product.company_short %} web interface or the
|
||||
|
||||
## Editing a {% data variables.product.prodname_marketplace %} webhook
|
||||
|
||||
You can edit a webhook that was created for an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can edit a {% data variables.product.prodname_marketplace %} webhook. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api).
|
||||
You can edit a webhook that was created for an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the app, can edit a {% data variables.product.prodname_marketplace %} webhook. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api).
|
||||
|
||||
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
|
||||
1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**.
|
||||
@@ -90,7 +90,7 @@ You can edit a webhook that was created for a {% data variables.product.prodname
|
||||
|
||||
Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can activate or deactivate the webhook, change the webhook events that the webhook subscribes to, or make changes to other basic settings for the webhook.
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can edit the webhook configuration for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also edit the webhook configuration. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps).
|
||||
The owner of a {% data variables.product.prodname_github_app %} can edit the webhook configuration for the app. If the app owner has designated any app managers for a {% data variables.product.prodname_github_app %}, the app managers can also edit the webhook configuration. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps).
|
||||
|
||||
{% data reusables.apps.settings-step %}
|
||||
{% data reusables.user-settings.developer_settings %}
|
||||
|
||||
4
data/features/enterprise-app-manager.yml
Normal file
4
data/features/enterprise-app-manager.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
# https://github.com/github/releases/issues/6053
|
||||
# Allows enterprise owners to designate app managers for enterprise-owned GitHub Apps
|
||||
versions:
|
||||
ghec: '*'
|
||||
4
data/features/enterprise-installed-apps.yml
Normal file
4
data/features/enterprise-installed-apps.yml
Normal file
@@ -0,0 +1,4 @@
|
||||
# Reference: #docs-content/issues/16388
|
||||
# GitHub Apps can now be installed at the enterprise level in addition to organizations
|
||||
versions:
|
||||
ghec: '*'
|
||||
@@ -1,8 +1,8 @@
|
||||
In order to use a {% data variables.product.prodname_github_app %} on your repositories or organization, you must install the app on your organization or personal account. You can install the same {% data variables.product.prodname_github_app %} on multiple accounts. For example, if you install the app on your personal account and on a few organizations that you own, you'll be able to use the app on your personal repositories, on the organizations where you installed the app, and on repositories owned by those organizations.
|
||||
In order to use a {% data variables.product.prodname_github_app %} on your resources, you must install the app on your{% ifversion enterprise-installed-apps %} enterprise,{% endif %} organization or personal account. You can install the same {% data variables.product.prodname_github_app %} on multiple accounts. For example, if you install the app on your personal account and on a few organizations that you own, you'll be able to use the app on your personal repositories, on the organizations where you installed the app, and on repositories owned by those organizations.
|
||||
|
||||
When you install an app, you grant the app permission to access the organization and repository resources that it requested. During the installation process, {% data variables.product.company_short %} will tell you which permissions the {% data variables.product.prodname_github_app %} requested. For more information about the REST API requests the {% data variables.product.prodname_github_app %} can make with those permissions, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps).
|
||||
When you install an app, you grant the app permission to access the {% ifversion enterprise-installed-apps %}enterprise or {% endif %}organization and repository resources that it requested. During the installation process, {% data variables.product.company_short %} will tell you which permissions the {% data variables.product.prodname_github_app %} requested. For more information about the REST API requests the {% data variables.product.prodname_github_app %} can make with those permissions, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps).
|
||||
|
||||
When you install an app, you will also choose which repositories to grant the {% data variables.product.prodname_github_app %} access to.
|
||||
When you install an app that requests repository permissions, you will also choose which repositories to grant the {% data variables.product.prodname_github_app %} access to.
|
||||
|
||||
Before installing a {% data variables.product.prodname_github_app %}, you should ensure you trust the owner of the {% data variables.product.prodname_github_app %}. You should also review the permissions that the {% data variables.product.prodname_github_app %} is requesting and make sure you are comfortable granting those permissions. For more information about the REST API requests the {% data variables.product.prodname_github_app %} can make with those permissions, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps).
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
If you are responding to a webhook event, the webhook payload will include the installation ID.
|
||||
|
||||
You can also use the REST API to find the ID for an installation of your app. For example, you can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, `GET /orgs/{org}/installation`, or `GET /app/installations` endpoints. For more information, see [AUTOTITLE](/rest/apps/apps).
|
||||
You can also use the REST API to find the ID for an installation of your app. For example, you can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, `GET /orgs/{org}/installation`, or `GET /app/installations` endpoints.{% ifversion enterprise-installed-apps %} The latter is required to find installations on an enterprise account.{% endif %} For more information, see [AUTOTITLE](/rest/apps/apps).
|
||||
|
||||
You can also find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).
|
||||
|
||||
@@ -23,9 +23,11 @@
|
||||
|
||||
Optionally, use the `permissions` body parameter to specify the permissions that the installation access token should have. If `permissions` is not specified, the installation access token will have all of the permissions that were granted to the app. The installation access token cannot be granted permissions that the app was not granted.
|
||||
|
||||
{% ifversion ghes > 3.13 and ghes < 3.16 %}When using the `permissions` parameters to reduce the access of the token, the complexity of the token is increased due to the number of permissions in the request and the number of repositories the token will have access to. If the complexity is too large, you will get an error message that indicates the maximum number of repositories that can be supported. In this case, you should request fewer permissions with the `permissions` parameter, use the `repositories` or `repository_ids` parameter to request fewer repositories, or install the app on `all` repositories in your organization.{% endif %}
|
||||
{% ifversion ghes > 3.13 and ghes < 3.16 %}When using the `permissions` parameters to reduce the access of the token, the complexity of the token is increased due to the number of permissions in the request and the number of repositories the token will have access to. If the complexity is too large, you will get an error message that indicates the maximum number of repositories that can be supported. In this case, you should request fewer permissions with the `permissions` parameter, use the `repositories` or `repository_ids` parameter to request fewer repositories, or install the app on `all` repositories in your organization.{% endif %}{% ifversion enterprise-installed-apps %}
|
||||
|
||||
The response will include an installation access token, the time that the token expires, the permissions that the token has, and the repositories that the token can access. The installation access token will expire after 1 hour.
|
||||
Installation tokens for enterprises cannot be scoped down. They only have access to the enterprise permissions they have been granted and always receive all of those permissions.{% endif %}
|
||||
|
||||
The response will include an installation access token, the time that the token expires, the permissions that the token has, and the repositories that the token can access, if applicable. The installation access token will expire after 1 hour.
|
||||
|
||||
For more information about this endpoint, see [AUTOTITLE](/rest/apps/apps).
|
||||
|
||||
|
||||
@@ -1,3 +1 @@
|
||||
Organization owners can designate other users{% ifversion org-app-manager-teams %} or teams{% endif %} in their organization as {% data variables.product.prodname_github_app %} managers. {% data variables.product.prodname_github_app %} managers can manage the settings of some or all of the {% data variables.product.prodname_github_app %} registrations that are owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant recipients access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information about the specific app settings that {% data variables.product.prodname_github_app %} managers can control, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app).
|
||||
|
||||
For more information about {% data variables.product.prodname_github_app %} manager permissions, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers).
|
||||
Organization{% ifversion enterprise-app-manager %} and enterprise{% endif %} owners can designate other users{% ifversion org-app-manager-teams %} or organization teams{% endif %} as {% data variables.product.prodname_github_app %} managers. {% data variables.product.prodname_github_app %} managers can manage the settings of some or all of the {% data variables.product.prodname_github_app %} registrations that are owned by the account. The {% data variables.product.prodname_github_app %} manager role does not grant recipients access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization{% ifversion enterprise-app-manager %} or enterprise{% endif %}. For more information about the specific app settings that {% data variables.product.prodname_github_app %} managers can control, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app).
|
||||
|
||||
1
data/reusables/enterprise-accounts/github-apps-tab.md
Normal file
1
data/reusables/enterprise-accounts/github-apps-tab.md
Normal file
@@ -0,0 +1 @@
|
||||
1. In the left sidebar, click **{% octicon "apps" aria-hidden="true" %} GitHub Apps**.
|
||||
@@ -1,5 +1,5 @@
|
||||
{% data variables.product.prodname_github_apps %} authenticating with an installation access token use the installation's minimum rate limit of 5,000 requests per hour. If the installation is on a {% data variables.product.prodname_ghe_cloud %} organization, the installation has a rate limit of 15,000 requests per hour.
|
||||
{% data variables.product.prodname_github_apps %} authenticating with an installation access token use the installation's minimum rate limit of 5,000 requests per hour. If the installation is on a {% data variables.product.prodname_ghe_cloud %} organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %}, the installation has a rate limit of 15,000 requests per hour.
|
||||
|
||||
For installations that are not on a {% data variables.product.prodname_ghe_cloud %} organization, the rate limit for the installation will scale with the number of users and repositories. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 requests per hour for each user. The rate limit cannot increase beyond 12,500 requests per hour.
|
||||
For installations that are not on a {% data variables.product.prodname_ghe_cloud %} organization{% ifversion enterprise-installed-apps %} or enterprise{% endif %}, the rate limit for the installation will scale with the number of users and repositories. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 requests per hour for each user. The rate limit cannot increase beyond 12,500 requests per hour.
|
||||
|
||||
Primary rate limits for {% data variables.product.prodname_github_app %} user access tokens (as opposed to installation access tokens) are dictated by the primary rate limits for the authenticated user. This rate limit is combined with any requests that another {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} makes on that user's behalf and any requests that the user makes with a {% data variables.product.pat_generic %}. For more information, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api#primary-rate-limit-for-authenticated-users).
|
||||
|
||||
Reference in New Issue
Block a user