apps

Subscribe to all “apps” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

→ ~ cd github-changelog
→ ~/github-changelog|main git log main
showing all changes successfully

Updated limits for GitHub App private keys and scoped tokens

GitHub Apps are now subject to a limit of 25 private keys per application and can create scoped tokens with access to more repositories. These changes support safer key management and access practices in your applications.

25 key limit for GitHub Apps

There is now a limit (25) on the number of private keys a GitHub App can have registered at one time. 99.99%+ of apps are below this limit – the ones above this limit will be unable to create more keys until they have deleted all but 24 of their keys.

Use of multiple keys for zero-downtime key rotation is encouraged. However, sharing keys among multiple parties is not recommended, which an unlimited number of keys lead developers towards. This new limit should help app developers look for safe alternatives earlier in the development lifecycle.

See our documentation on GitHub App key management for more details and best practices.

No limit on repositories for permissions-scoped tokens

In February 2024, GitHub placed a limit on the complexity of the scoped tokens that apps could request. Now, part of this limit no longer applies. Apps can now be installed on any number of repositories in an organization and request a scoped token for all those repositories. The limitation on tokens that request a subset of both permissions and tokens remains.

To learn about scoped tokens, and how they can improve the least-privilege access of your App’s tokens, see our GitHub App authentication documentation.

See more

View an organization’s REST API activity with API insights in public preview

As a GitHub Enterprise Cloud organization owner, you and your designated users can now use API insights to visualize REST API activity for your entire organization or specific apps and users. This new feature, currently in public preview, helps you understand the sources of your REST API activity and manage against your primary rate limits—giving you visibility into the timeframe, apps, and API endpoints involved.

Who can access it

The API insights feature is available only at the organization level. By default, only organization owners can access it. However, organization owners can grant access to non-owners by creating a custom role at the organization level, assigning the permission named View organization API insights to the custom role, and then assigning the custom role to an organization member or team. See the documentation for managing organization custom roles.

Where to find it

The API insights public preview feature is enabled for all GitHub Enterprise Cloud organizations. To access it on your organization home page, select Insights near the top of the page, and then select REST API on the left side of the page.

An image of an organization homepage where selecting Insights and then REST API will navigate to the new API insights feature.

How to use it

Use the Period and Interval drop-downs to choose the range of time displayed in the chart and how granularly to display REST API requests on the chart. These drop-downs also set the time range for the “Total REST requests,” the “Primary-rate-limited requests,” and the Actors table below the chart.

An image of the API insights feature page showing the Period drop-down expanded for selecting the time period of REST API activity to include.

The Actors table displays the GitHub Apps and users that made REST API requests in the current organization within the selected time period. Select a GitHub App to display its REST API activity and any primary-rate-limiting. Select a user to display their personal REST API activity from personal access tokens (PATs) and OAuth apps acting on their behalf.

An image of the API insights feature page showing a table of actors, including GitHub Apps and users, that created REST API activity in the selected time period.

Tell us what you think

We welcome your feedback in this community discussion.

Refer to the documentation for API insights for more details about understanding your organization’s REST API activity and investigating primary-rate-limiting.

See more

Enterprises can create GitHub Apps for use within the Enterprise

Enterprise owners can now create GitHub Apps owned by their enterprise, with access restricted to just the organizations and members in the enterprise. Previously, if you wanted to share an app across multiple organizations within your enterprise, you had to either:

  • Duplicate the app for each organization, leading to management overhead and potential inconsistencies, or
  • Make the app public, potentially exposing it to users outside your enterprise.

With this update, you can now safely share an app across your entire enterprise without exposing it to the rest of GitHub.com, and manage your critical apps in a more secure and centralized location.

This also simplifies distribution and management for Copilot Extensions. You can now build custom extensions and share them across your enterprise without making them public – allowing you to create tools specific to your company’s needs and workflows, while keeping them private. Use of a single app across your enterprise ensures consistency and makes it easier to update extensions across all of your teams.

A screenshot of the GitHub app creation page, showing a single visibility option that reads "Only avocado-corp-owned organizations"

These apps can only be installed on organizations in your enterprise, and only members of your enterprise can sign in to them. To ensure the security of your app, user accounts cannot install these apps, only sign in to them. When users or organizations leave your enterprise, they immediately lose access to enterprise-owned apps, and the apps lose access to those users and organizations.

Besides the limitations on where they can be installed and who can sign in, these are standard GitHub Apps. Organization and repository administrators can install them depending on the permissions requested, and they have access to all of the organization and repository APIs that other apps do. Like other apps, they support Copilot Extensions and can be used in Copilot Chat.

Today, only enterprise owners can create and manage these applications. In the future we’ll add support for the App Manager role that exists for organization-owned applications as well, to make it easier for administrators to delegate access to apps in a secure manner.

To learn more about this public beta, see our documentation on GitHub Apps and the enterprise.

See more

Client IDs are now included in App API responses

The client_id field is now included in all API responses that describe a GitHub App. We are shifting to use the client ID as the primary identifier for an app, as client IDs are globally unique while application IDs and names are not.

Historically GitHub has used the app_name (aka slug) or the app_id (a database ID) to identify applications in our APIs. However, the app name is not immutable and the app ID is not sufficiently globally unique. We are gradually moving all App-related APIs to support the use of the client_id of an application as their primary identifier instead of the name or database ID – this was first seen in our change to support using the client ID to mint JWTs used for installation tokens.

We are making this change to prepare for upcoming features that allow programmatic management of applications in your enterprise. This additional data will make it easier to find the client ID of an application that you are interested in.

For more information about how to get application information, see our REST API documentation.

See more

GitHub Private Mirrors App – Public Beta

Today, we’re releasing a beta version of an open source GitHub App that manages private mirrors of public upstream repositories. The Private Mirrors App (PMA) enables organizations with regulatory or policy code review requirements to conduct their reviews in private, before contributing changes upstream. The app manages the lifecycle and synchronization of these private mirrors and automatically configures rulesets to manage PRs made to the mirrors.

The main benefits of working on private mirrors through PMA are:

  • Branch protection rules can enforce PR reviews by people on particular teams to ensure proper signoffs
  • If commits include code/keys/docs that should not be made public, there’s the opportunity to remove them and squash merge without leaking history
  • Initial development can happen inside an Enterprise Managed Users (EMU) organization, whose users ordinarily can’t interact with public GitHub repos. Once the app syncs a change, the public fork and upstream PR use normal github.com identities.

If this is interesting to you, check out the Private Mirrors App repo. If you’ve got questions or feedback, feel free to file an issue in the repostitory or join the conversation in the GitHub Community Discussions.

See more

Account picker updates for OAuth and GitHub App sign-in

For security and convenience, we’ve updated how the account picker can be triggered during sign-in to an OAuth or GitHub Application. Some apps will see it all of the time, while all apps are able to trigger it manually.

Native apps (an app with a callback URI that doesn’t lead to an https:// destination) will now always receive the account picker to ensure that users get an opportunity to verify the application and change accounts if need be.

image

We’ve also added support for the standard prompt parameter with the select_account argument, which an app can provide during the OAuth authorization request to /authorize. This parameter forces the account picker to appear during authentication, interrupting what can otherwise be an instant authentication flow. We recommend using this parameter to better support multiple accounts at once in your app, if a user indicates they want to use another account in your app.

To force the account picker, append the following alongside your client ID and redirect URI parameters when you send the user to GitHub to sign in: &prompt=select_account.

As before, users with multiple signed in accounts will always see the account picker on each authentication.

To learn more about query parameters in the OAuth flow, see Authorizing OAuth Apps and Generating a user access token for a GitHub App.

See more

GitHub Apps can now use the client ID to fetch installation tokens

Developers of GitHub Apps can simplify their application by using the client ID for both OAuth flows and the installation token flow.

To date, GitHub Apps have had two different IDs to manage – the application ID and the client ID. The application ID was only used to mint a JWT, subsequently used to fetch an installation token. The client ID is used with the OAuth flow to sign in users and request installations. These two values equally identify the application and the question of which one to use where caused unnecessary developer friction. You can now use the client ID in the place of the application ID when minting JWTs.

The application ID is not being deprecated at this time, nor are their plans to remove it. However, compatibility with future features will rely on use of the client ID, so updating is recommended.

The specific change allowed here is that when minting the JWT that proves your app is in posession of an application’s private key, you can use the client ID for the iss claim. Note that application IDs are ints, while client IDs are strings, if using a typed language.

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
 payload = {
 # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
--- # GitHub App's App ID
--- iss: "12345"
+++ # GitHub App's Client ID
+++ iss: "Iv23f8doAlphaNumer1c"
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

Note that Octokit still expects the use of the App ID in its setup – the Octokit SDK will be updated in the future to support use of the client ID.

You can find the client ID for your application in its settings page:

A screenshot of an app's settings, showing both the client ID and the application ID

Client IDs and application IDs are not secrets, and are expected to be visible to the end user – you do not need to change how you handle your IDs when making this update.

For more information about minting JWTs to get an installation token, see ‘Generating a JWT for a GitHub App’.

See more

Updated GitHub App visibility for Enterprise Managed Users

We’ve clarified the GitHub App creation experience for Enterprise Managed Users (EMUs), updating it for both users and organizations that would like to create an app.

GitHub Apps created within an EMU enterprise are only accessible within the enterprise – they’re blocked for anyone else. In addition, EMU user accounts are unable to install GitHub applications.

To reflect this limitation, we’ve updated the creation UI to disable the “Private” option for EMU users, which prevents users from creating apps that no one can install. We’ve also updated the “Public” option to instead read “This enterprise”, more accurately reflecting where the app can actually be installed.

image

For more information about EMUs, see “About Enterprise Managed Users“. For more about GitHub Apps, see “About GitHub Apps“.

See more

X-Accepted-GitHub-Permissions header for fine-grained permission actors

A new header will be sent back to API callers that use the fine-grained permission model (GitHub Apps and fine-grained PATs) to help developers discover which permissions are needed to call an API route. This new header, x-accepted-github-permissions, contains the list of permissions required to access the endpoint.

In the fine-grained permission model more than one permission may be needed to access an endpoint. Multiple sets of permissions may also be valid, since there are multiple ways to access data within GitHub. All valid sets are included in the header, each set separated by a semicolon (;).

For example, when calling "List project collaborators", you'll recieve the header x-accepted-github-permissions: repository_projects=write; organization_projects=admin. This indicates that to get the list of collaborators on a project, you need either the repository_projects Write permission or the organization_projects Admin permission.

This header is used in the same way as the x-accepted-oauth-scopes header for coarse-grained scope actors (OAuth apps and PATs (Classic)).

To learn more about troubleshooting permissions issues with GitHub Apps and fine-grained PATs and to get more information about this header, see "Insufficient permission errors". To see the permissions needed for each endpoint, see "Permissions required for GitHub Apps" and "Permissions required for fine-grained PATs".

See more

Updates to GitHub App installation management APIs

The "Remove a repository from an app installation" API has been updated to fail early if attempting to remove a repository from an application that is installed on all repositories.

To switch an application InstallationState from the all to some state in your organization, an organization owner or application manager must make this change within the UI, while picking up to 50 repositories for the app to continue to have access to. From there, additional repositories can be added via the UI or the "Add a repository to an app installation" API.

To learn more about managing application installations, see "Modifying repository access". For details on the GitHub App REST API, see "GitHub Apps".

See more

GraphQL improvements for fine-grained PATs and GitHub Apps

Fine-grained PATs can now call the GitHub GraphQL API. This was a limitation at the start of the public beta, and is now supported.

Like with the REST API, the resource owner set for the token must match the owner of the resource being accessed. For example, when you want to look up a specific repository in GraphQL:

query {
  repository(owner:"octocat", name:"Hello-World") {
  ...

The resource owner would need to be octocat to succesfully run the query.

In addition, GitHub Apps now have read access to public resources via GraphQL by default when using user-to-server tokens. This is true even if they are not installed on the organization or user that owns the resource.

This change brings consistency to the access control between REST APIs and GraphQL APIs for GitHub Apps. We made similar changes previously for REST APIs which you can read more about here.

To learn more about GraphQL, see "About the GraphQL API". For more details about fine-grained PATs, see "Creating a fine-grained personal access token". And finally, to learn more about GitHub apps, see "Setting permissions for GitHub apps".

See more

Organization APIs for fine-grained PATs management

Organization owners can now automate the approval and auditing of fine-grained personal access tokens (PATs) in their organization using a GitHub app. New APIs and webhook events allow a GitHub app to be notified of new PAT requests in an organization, review the request, and then approve or deny the PAT. They also provide a view of all approved fine-grained PATs for an organization, with the ability to revoke their authorization as well. These APIs and events are part of the ongoing fine-grained PAT public beta that launched last year.

Mermaid diagram indicating how a request from a user triggers a webhook event to an app, who can then review the request and choose to approve it. Later, the application can review all approved PATs, and choose to revoke one, resulting in an email notification to the user who created the PAT.

Details included in the webhook event and API listings include the repositories and permissions requested, the expiration time of the token, and the user's explanation for what they plan to do with the PAT. The personal_access_token_request events are generated when a request is created, approved or denied by an administrator or application, or cancelled by the requesting user.

Only a GitHub app is able to call these APIs, either acting on its own or on behalf of a signed-in organization administrator.
The organization_personal_access_tokens permission is needed to manage the active tokens, while the organization_personal_access_token_requests permission enables the app to recieve webhooks about requests and call the request management APIs.

Organizations must have the personal access token approval flow enabled in order to manage these requests, otherwise fine-grained personal access tokens are automatically approved for the organization (which generates a personal_access_token_request: approved event).

To learn more about these APIs, see "List requests to access organization resources with fine-grained PATs" and the "personal_access_token_request webhook event". To learn more about fine-grained PATs, and how to enable them for your organization, see "Setting a personal access token policy for your organization".

If you have feedback or bugs to report about fine-grained PATs, please let us know in the dedicated feedback discussion.

See more

SSH Certificate requirement update

The "Require SSH certificates" policy now allows GitHub apps to call Git APIs using a user-to-server token, bringing them up to parity with OAuth app support.

The SSH certificate requirement mandates that users in your organization call Git APIs using an SSH certificate issued by your organization, in place of their own SSH key or a PAT.
To support automation, it has an exception in place for OAuth apps and GitHub app server-to-server tokens, which allows applications you've approved to call Git APIs for your organization.
With this change, we are extending that exception to GitHub app user-to-server tokens, for when a user has signed into a GitHub app that's installed in your organization.

Screenshot of the SSH Certificate requirement checkbox

This change also applies when the enterprise-level setting requires SSH certificates across all organizations in the enterprise.

To learn more, see "Managing your organization's SSH certificate authorities" or "Managing SSH certificate authorities for your enterprise".

See more
View more changes