GitHub App improvements for least privilege and management

We’re releasing several GitHub Apps improvements today that help developers move off of classic PATs, improve GitHub App management, and request fewer sensitive permissions. We’ve also made it easier for repository administrators to use apps that their administrators have approved and updated the GitHub App credential management UI in advance of our planned workload federation features.

Two new repository fine-grained permissions have been added, available to both fine-grained PATs and GitHub Apps.

• repository_creation:write: Allows the caller to create a repository in the account where it’s granted.
• installation_repositories: write: Allows the caller to add or remove that repository from an installation in the organization.

You can now use the repository_creation:write permission to create repositories without needing the broader repository_administration:write permission.

Previously, an app or PAT needed repository_administration:write to create a repository. That permission also grants other repository administration features like deletion and transfer. This could lead to administrators rejecting apps, banning PATs with this permission, or having to accept the over-privilege risk.

The new permission supports a least-privilege approach by granting only the ability to create repositories. When the repository is created, the app or user that created it will be given access to it. An app using this permission still requires an organization administrator to install the app.

See the API docs for repository creation in organizations, from a template, for the current user, with a fork, and via GraphQL.

The Add a repository to an installation organization-level API and its corresponding removal API now support GitHub Apps and fine-grained PATs. Previously, these APIs only supported the coarse-grained repo scope.

These APIs support a new repository-level fine-grained permission:installation_repositories:write. Having this permission on a repository allows the caller to add or remove that repository from any installation in the organization. If the caller is a user, they must also be an organization owner or an administrator on the repository in question.

This allows organizations to build automation that controls which repositories are accessible to which GitHub Apps without relying on an administrator’s PAT with broad permissions.

Historically, all apps that requested organization-level access were blocked from being installed on a repository by a repository administrator, no matter what. This restriction has been relaxed in the case where the app is already installed in the organization, meaning it’s been approved by an organization owner for that organization-level access. Repository administrators can now edit an existing installation to add their repositories to an app without requiring organization owner approval. The apps already have the organization-level access, so adding them to another repository in the organization doesn’t increase that access or give the repository administrator additional privileges.

With the addition of the repository_creation permission above, there are now three sensitive permission sets that require organization owner approval:

• All organization-level permissions
• Repository administration
• Repository creation

This change allows repository administrators to better use apps that are already approved for use in their organization.

If you’d like to prevent repository administrators from adding apps to their repositories, see “Restricting GitHub App Installation to Organization Owners” in the docs. For more details on adding an app to a repository, see “Installing a GitHub App“.

GitHub Apps now support the offline_access scope, like OAuth apps. While GitHub Apps use short-lived, rotating tokens by default, some developers have disabled expiration for convenience and now struggle to reenable it.

This support helps app developers gradually migrate to expiring user access tokens. Developers can enable token expiration for testing and rollout without having to switch every user to expiring tokens at the same time, which would break existing clients.

When offline_access is requested, the app receives a refresh token in addition to the expiring access token. It only changes that specific authentication and doesn’t impact future sessions.

The scope parameter is still otherwise unused for GitHub Apps—permissions are still statically selected on the application registration. For more details, see “Refreshing user access tokens“.

This is available in GHES 3.23.

GitHub Apps can now use the Get an app API to fetch details about private and internal GitHub Apps, as long as they share some ownership.

The permitted access patterns are:

1. Public apps: Any other app can fetch the app’s details. This was the previously enabled level of access.
2. Apps in the same organization: Apps can fetch each other’s details regardless of visibility, if they share the same owner.
3. Internal apps in the same enterprise: An internal app’s details can be fetched by another app in the same enterprise, even across organization boundaries.
4. Enterprise-to-organization access: An enterprise-owned app can fetch details about apps owned by organizations in the same enterprise.

This enables organizations and enterprises to automate more of their GitHub App auditing and administration.

For more details about app visibility, see “Making a GitHub App public or private“.

GitHub App credentials are now managed from a dedicated Credentials tab instead of appearing inline with the rest of the app configuration. This makes credentials easier to find and manage, and sets aside space for our upcoming workload federation credentials.

These improvements will be available in GHES 3.24, with the exception of offline_access support, which will be included in GHES 3.23.

Let us know what you think in the GitHub Community.