Platform updates: New API permissions, installation requirements changes, and offline_access for Apps

[hpsin]

We've got more GitHub App improvements that shipped this week! See the changelog for expanded details.

In short:

• New API permissions to create repos and add them to installations without using a classic PAT or hihg-powered permissions.
• Easier app installation by repo admins if the app is already approved
• Per-request opt-in for expiring tokens, in advance of enabling it for your app
• Easier app-to-app visibility for auditing
• A new credentials UX in advance of our workload federation updates

New repository creation and installation management permissions

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.

Create a repository without repository_administration

The new repository_creation:write permission unlocks the following APIs:

• Repository creation in organizations
• From a template
• For the current user
• With a fork
• Creation via GraphQL

This is a repository permission, and may help you stop using the high-powered repository_administration:write permission.

Manage installation repositories without a Classic PAT

The Add a repository to an installation organization-level API and its corresponding removal API now support GitHub Apps and fine-grained PATs using 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.

Repository administrators can more easily add approved GitHub Apps to repositories

Repository administrators can now install apps that use sensitive permissions, as long as the organization owner has already installed the app in the organization. This change relaxes the installation requirements, which previously prevented the repository administrator from ever adding the app to their repository, regardless of whether it was installed or not for the organization.

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

• 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".

Use offline_access with GitHub Apps to gradually reenable short-lived, rotating tokens

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.

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 fetch details about other private and internal apps

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.

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

A new credential management tab for GitHub Apps

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.