apps

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:

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’.

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

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