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

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

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

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

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

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

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

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

Previously, some branch protections only allowed exceptions to be granted to users and teams. Now, GitHub Apps can also be granted exceptions to any branch protection that supports exceptions.

Admins can create branch protection rules to enforce certain workflows for branches, such as requiring a pull request before changes can be merged to a branch. This is a good practice, but you may want to make exceptions to a rule for specific people, teams, or GitHub Apps. For example, if you have a GitHub App that calls GitHub APIs to make changes in a repository, you may want to permit that App to make changes without creating a pull request. Previously, these exceptions could be granted to people and teams, but only some protections allowed GitHub Apps.

Now, branch protections that previously only allowed exceptions for people and teams also support GitHub Apps. When admins configure these branch protections, they can choose from a list of GitHub Apps that are installed and authorized for the repository, as shown here:

Image of adding a GitHub App as an exception to a branch protection setting

For information about branch protection rules, visit Managing a branch protection rule.

For information about GitHub Apps, visit About GitHub Apps.

We appreciate feedback on this and other topics in GitHub's public feedback discussions.

See more

From today the OAuth Device Authorization flow feature must be manually enabled for all OAuth and GitHub Apps. This change reduces the likelihood of Apps being used in phishing attacks against GitHub users by ensuring integrators are aware of the risks and make a conscious choice to support this form of authentication.

If you own or manage an OAuth App or GitHub App that makes use of the OAuth Device Authorization flow, you can enable it for your App via its settings page:

Enable device flow

The OAuth Device Authorization flow API endpoints will respond with status code 400 to Apps that have not enabled this feature.

Learn more about the OAuth Device Authorization flow.

See more

On March 16 2022 the OAuth Device Authorization flow will become an "opt in" feature for all OAuth and GitHub Apps. This change reduces the likelihood of Apps being used in phishing attacks against GitHub users.

If you own or manage an OAuth App or GitHub App that makes use of the OAuth Device Authorization flow, you should enable it for your Apps via its settings page:

Enable device flow

The OAuth Device Authorization flow API endpoints will respond with status code 400 to Apps that have not opted in to this feature.

Learn more about the OAuth Device Authorization flow.

See more

The new GraphQL mutation createCommitOnBranch makes it easier to add, update, and delete files in a branch of a repository.

This new API offers a simpler way to commit changes compared to the existing Git database REST APIs. With the new createCommitOnBranch mutation, you do not need to manually create blobs and trees before creating the commit. This allows you to add, update, or delete multiple files in a single API call.

Commits authored using the new API are automatically GPG signed and are marked as verified in the GitHub UI. GitHub Apps can use the mutation to author commits directly or on behalf of users.


See the GraphQL API reference for more information on using createCommitOnBranch. You can also try it in the GraphQL API Explorer! If you need a refresher on how to use the GraphQL API, see our guide.

See more

API requests made by a GitHub App on behalf of a user that has authorized the app are known as user-to-server requests.

The resources that can be accessed by these requests are constrained to the set of private resources that both the App and the authorizing user can access.

GitHub is now extending this access model, allowing user-to-server requests to also read public resources over the REST API. This includes, for example, the ability to list a public repository's issues and pull requests, and to access a public repository's comments and content.

Read more about authorizing GitHub Apps.

See more