Enterprise-level access for GitHub Apps and installation automation APIs

GitHub Apps can now be installed onto enterprise accounts, with new permissions that let them call enterprise management APIs. The public preview of this new access pattern has a limited set of permissions that unblock significant automation opportunities. With this release we’re also introducing a new set of enterprise APIs that allow you to manage which GitHub Apps are installed, and what they can access, across the organizations in your enterprise. This will allow you to automatically install, audit, or manage apps in every single organization. Say goodbye to clicking on hundreds of installation buttons!

Additionally, enterprise-owned GitHub Apps can now be managed individually by users. An enterprise owner can assign an enterprise member to be the manager of an enterprise-owned app. To learn more about enterprise app managers, see “Adding and removing GitHub App managers in your enterprise“.

Enterprise installations

Apps owned by an enterprise or enterprise-owned organization can now request a new “Enterprise” set of permissions. Enterprise owners will now see their enterprise listed as a valid installation target during app installation for apps owned within their enterprise.

Currently, enterprises can only install apps owned by the enterprise or organizations in the enterprise. We’ll lift this limitation in the future as we expand controls around these applications.

Access patterns for enterprise installations

Enterprise installations grant the app access to the enterprise account itself, but do not act as installations within each organization or repository. If you need to access organization or repository data, your app needs to be installed directly on those organizations. Fortunately, this preview comes with tools that will help with this exact need!

You can use the standard installation token pattern to get a token for your app targeting an enterprise, or sign in a user via OAuth to act on their behalf wherever your app is installed. For apps installed on both an enterprise and organizations, a user token is able to access both sets of resources without issue, assuming the user has the appropriate permissions as well.

Enterprise installations have their own rate limit budget separate from organization or user installations. Each installation is budgeted 15,000 requests or 10,000 points per hour, the same budget that an enterprise-plan organization installation recieves.

Enterprise installations cannot subscribe for webhooks at this time. If your application requires enterprise webhooks, consider creating an enterprise webhook subscription and having your application respond to that.

Enterprise App permissions

Like organizations and repositories, enterprise access is gated by fine-grained permissions that the application must be granted in order to access or manage resources. Each API has a corresponding set of permissions required to access it. This public preview launches with five new enterprise permission sets that unlock highly used APIs, plus a new API for automating the installation of GitHub Apps across your enterprise.

We’ll continue to add fine-grained permissions to enterprise APIs on GitHub to ensure that you can use GitHub Apps with all of them. Our goals are to increase support for necessary automation scenarios and to continue to move away from requiring PATs (Classic).

GitHub App installation management

A new /organization-installations REST API allows you to view and control each GitHub App installation your enterprise’s organizations. You can install new GitHub Apps onto an organization, control which repositories apps have access to, and uninstall them as well. Two permissions control these APIs:

• Enterprise organization installations (read/write): Allows your app to view, create, edit, and remove installations in each organization in your enterprise. This is a very powerful write permission as it can be used to install applications with organization administration permissions and read-write access to every repository. When granted as a read-only permission it’s very useful for auditing applications across your enterprise. This permission includes the corresponding Enterprise organization installation repositories read or write permission.
• Enterprise organization installation repositories (read/write): This is a subset of the Enterprise organization installation permission, only granting the app the ability to change which repositories an installation has access to, but not the ability to install new apps or uninstall other apps. If you have access patterns that rely on apps getting access to specific repositories, this can help automate that work without the use of PATs and without the risk of new apps being installed.

To learn how to put these permissions to use, see the API documentation for /organization-installations.

Enterprise custom properties

The enterprise custom properties APIs support GitHub Apps. Your app can use these APIs with the custom properties permission to manage custom repository properties set at the enterprise level.

Enterprise SSO and SCIM management

Enterprise access management via OIDC, SAML, and SCIM can now be managed by a GitHub App. The SCIM permission is only available to Enterprise Managed User (EMU) enterprises at time time, while the SSO permission is available to all enterprises.

• Enterprise single sign-on (read/write): This permission works with the EnterpriseIdentityProvider (SAML) and OIDCProvider(OIDC) objects in GraphQL, as well as the mutations to control the SAML identity provider: setEnterpriseIdentityProvider and removeEnterpriseIdentityProvider. With the write permission you can also use the regenerateEnterpriseIdentityProviderRecoveryCodes recovery codes mutation.
• Enterprise SCIM (read/write): For EMU enterprises, this allows an app to call the SCIM APIs for their enterprise. For auditing purposes, it’s useful for an enterprise to have multiple apps reading from the SCIM APIs. However, you should only write to the SCIM APIs with a single application or IDP to ensure consistency over time.

Note: For EMUs, the SSO setup still needs to be completed by the initial admin setup user. The new enterprise permissions do not replace this requirement. The SCIM permission is currently only shown for EMUs as SCIM is not yet supported in non-EMU GHEC enterprises.

Enterprise people management

GitHub Apps can now automate the invitation of users into your enterprise and control whether they’re an enterprise owner or not. You can use this to build a JIT elevation system that makes a user an enterprise owner for a short period of time, or just use it to query over your enterprise members.

The GraphQL edges and mutations these permissions work with are:

• The Enterprise.members field to list enterprise members.
• inviteEnterpriseAdmin or inviteEnterpriseMember.
• updateEnterpriseAdministratorRole to add or remove the owner role for a user.
• removeEnterpriseAdmin to evict an enterprise owner entirely.
• removeEnterpriseMember to remove someone from all your orgs and the enterprise.

Create and remove organizations for your enterprise

GitHub Apps can now create organizations within your enterprise, as well as remove them. This permission only comes in a write version as it does not support any read functionality.

The GraphQL mutations these permissions work with are:

• createEnterpriseOrganization
• removeEnterpriseOrganization

When an app creates an organization, it still must provide a user as the first owner of that organization. In addition, it gets no permissions against that new organization—management of the organization needs to be done with an application that is then installed on that organization.

Using enterprise installations and providing feedback

We’ll continue to announce new API support for GitHub Apps as new permissions come online. If you need just one more API supported to finish your automation, or you find that a permission isn’t giving you quite the access you were hoping for, we’d love to hear your feedback in our Community Discussions thread. We’re prioritizing the APIs that see the most traffic as well as core scenarios for enterprise management.

To learn more about enterprise installations, see “Installing a GitHub App on your enterprise“.