Merge pull request #46233 from github/repo-sync

Repo sync

Author: docs-bot

assets/images/github-apps/github-apps-private-key-fingerprint-new.png

@@ -66,6 +66,7 @@ The models available for {% data variables.product.prodname_copilot_short %} var
 * {% data variables.copilot.copilot_gpt_56_terra %}
 * {% data variables.copilot.copilot_gpt_6_astra %}
 * {% data variables.copilot.copilot_claude_haiku_45 %}
+* {% data variables.copilot.copilot_claude_haiku_55 %}
 * {% data variables.copilot.copilot_claude_opus_48 %}
 * {% data variables.copilot.copilot_claude_opus_5 %}
 * {% data variables.copilot.copilot_claude_opus_55 %}

content/admin/data-residency/github-copilot-with-data-residency.md

@@ -103,6 +103,12 @@ After signing in a user, app developers must take additional steps to ensure tha
 
 {% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps).
 
+{% ifversion github-app-offline-access %}
+
+To test and gradually roll out support for expiring tokens, request the `offline_access` scope when you sign in a user. This scope gives you an expiring user access token and a refresh token for an individual authorization, even if your app is configured not to use expiring tokens. To confirm that you received an expiring token, check for the `expires_in` field in the token response.
+
+{% endif %}
+
 Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see [`DELETE /installation/token`](/rest/apps/installations#revoke-an-installation-access-token) to revoke an installation access token and [`DELETE /applications/{client_id}/token`](/rest/apps/oauth-applications#delete-an-app-token) to revoke a user access token.
 
 ## Cache tokens

content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md

@@ -19,7 +19,7 @@ category:
 > {% data reusables.enterprise-data-residency.access-domain %}
 {% endif %}
 
-A user access token is a type of OAuth token. Unlike a traditional OAuth token, the user access token does not use scopes. Instead, it uses fine-grained permissions. A user access token only has permissions that both the user and the app have. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents.
+A user access token is a type of OAuth token. Unlike OAuth apps, GitHub Apps do not request scopes during authorization to decide which resources the resulting token can access. Instead, they use fine-grained permissions set on the application registration. A GitHub App user access token only has permissions that both the user and the app have. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents.
 
 Similarly, a user access token can only access resources that both the user and app can access. For example, if an app is granted access to repository `A` and `B`, and the user can access repository `B` and `C`, the user access token can access repository `B` but not `A` or `C`. You can use the REST API to check which installations and which repositories within an installation a user access token can access. For more information, see `GET /user/installations` and `GET /user/installations/{installation_id}/repositories` in [AUTOTITLE](/rest/apps/installations).
 
@@ -42,6 +42,7 @@ If your app runs in the browser, you should use the web application flow to gene
    `client_id` | `string` | Required | The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).
    `redirect_uri` | `string` | Strongly recommended |  The URL in your application where users will be sent after authorization. This must be a match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url).
    `state` | `string` | Strongly recommended |  When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data.
+{% ifversion github-app-offline-access %}   `scope` | `string` | Optional | To receive an expiring user access token and a refresh token for this authorization, set this value to `offline_access`. No other scopes are supported for {% data variables.product.prodname_github_apps %}. This parameter does not control permissions for the user access token.{% endif %}
 {% ifversion pkce_support %}   `code_challenge` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge_method` is included. Must be a 43 character SHA-256 hash of a random string generated by the client. See the [PKCE RFC](https://datatracker.ietf.org/doc/html/rfc7636) for more details about this security extension.
    `code_challenge_method` | `string` | Strongly recommended | Used to secure the authentication flow with PKCE (Proof Key for Code Exchange). Required if `code_challenge` is included. Must be `S256` - the `plain` code challenge method is not supported.{% endif %}
    `login` | `string` | Optional | When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app.
@@ -66,7 +67,9 @@ Before you can use the device flow, you must first enable it in your app's setti
 
 The device flow uses the [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628).
 
-1. Send a `POST` request to `{% data variables.product.oauth_host_code %}/login/device/code` along with a `client_id` query parameter. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).
+1. Send a `POST` request to `{% data variables.product.oauth_host_code %}/login/device/code` along with a `client_id` query parameter. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).{% ifversion github-app-offline-access %} 
+
+   To get to an expiring user access token and a refresh token for this authorization even if your app has them disabled, you can also send the `scope` query parameter with the value `offline_access`. No other scopes are supported for {% data variables.product.prodname_github_apps %}.{% endif %}
 1. {% data variables.product.company_short %} will give a response that includes the following query parameters:
 
    Response parameter | Type | Description
@@ -128,10 +131,16 @@ You can generate a user access token with this method regardless of whether the
 
 ## Using a refresh token to generate a user access token
 
-By default, user access tokens expires after 8 hours. If you receive a user access token with an expiration, you will also receive a refresh token. The refresh token expire after 6 months. You can use this refresh token to regenerate a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
+By default, user access tokens expire after 8 hours. If you receive a user access token with an expiration, you will also receive a refresh token. The refresh token expires after 6 months. You can use this refresh token to regenerate a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
 
 {% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps).
 
+{% ifversion github-app-offline-access %}
+
+To test your app's support for expiring tokens before you re-enable token expiration for the entire app, request the `offline_access` scope when you request a user access token. To confirm that you received an expiring token, check for the `expires_in` field in the token response.
+
+{% endif %}
+
 ## Troubleshooting
 
 The following sections outline some errors you may receive when generating a user access token.
@@ -159,7 +168,7 @@ To resolve this error, you should start the device flow again to get a new code.
 
 If the refresh token that you specified is invalid or expired, you will receive a `bad_refresh_token` error.
 
-To resolve this error, you must restart the web application flow or device flow to get a new user access token and refresh token. You will only receive a refresh token if your {% data variables.product.prodname_github_app %} has opted in to expiring user access tokens. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
+To resolve this error, you must restart the web application flow or device flow to get a new user access token and refresh token. You will only receive a refresh token if your {% data variables.product.prodname_github_app %} has opted in to expiring user access tokens{% ifversion github-app-offline-access %} or uses the `offline_access` scope{% endif %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens).
 
 ### Unsupported grant type
 

content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md

@@ -29,7 +29,9 @@ To generate a private key:
 {% data reusables.apps.settings-step %}
 {% data reusables.apps.enterprise-apps-steps %}
 1. Next to the {% data variables.product.prodname_github_app %} that you want to generate a private key for, click **Edit**.
-1. Under "Private keys", click **Generate a private key**.
+{% ifversion github-app-repository-permission-improvements %}1. In the left sidebar, click **{% octicon "key" aria-hidden="true" aria-label="code" %} Credentials**, then click **{% octicon "key" aria-hidden="true" aria-label="code" %} Key pairs**.
+1. Click **New key**.{% else %}
+1. Under "Private keys", click **Generate a private key**.{% endif %}
 1. You will see a private key in PEM format downloaded to your computer. Make sure to store this file because GitHub only stores the public portion of the key. For more information about securely storing your key, see [Storing private keys](#storing-private-keys).
 
 > [!NOTE]
@@ -41,9 +43,10 @@ To generate a private key:
 
 To verify a private key:
 
-1. Find the fingerprint for the private and public key pair you want to verify in the "Private keys" section of the settings page for your {% data variables.product.prodname_github_app %}. For more information, see [Generating private keys](#generating-private-keys).
+1. Find the fingerprint for the private and public key pair you want to verify in the {% ifversion github-app-repository-permission-improvements %}"Credentials"{% else %}"Private keys"{% endif %} section of the settings for your {% data variables.product.prodname_github_app %}. For more information, see [Generating private keys](#generating-private-keys).
 
-   ![Screenshot of a private key in a {% data variables.product.prodname_github_app %} settings page. The fingerprint, the part of the private key after the colon, is outlined in dark orange.](/assets/images/github-apps/github-apps-private-key-fingerprint.png)
+{% ifversion github-app-repository-permission-improvements %}   ![Screenshot of a private key in a {% data variables.product.prodname_github_app %} settings page.](/assets/images/github-apps/github-apps-private-key-fingerprint-new.png){% else %}
+   ![Screenshot of a private key in a {% data variables.product.prodname_github_app %} settings page. The fingerprint, the part of the private key after the colon, is outlined in dark orange.](/assets/images/github-apps/github-apps-private-key-fingerprint.png){% endif %}
 1. Generate the fingerprint of your private key (PEM) locally by using the following command:
 
     ```shell
@@ -60,7 +63,9 @@ You can remove a lost or compromised private key by deleting it, but you must re
 {% data reusables.user-settings.developer_settings %}
 {% data reusables.user-settings.github_apps %}
 1. Next to the {% data variables.product.prodname_github_app %} that you want to delete a private key for, click **Edit**.
-1. Under "Private keys", to the right of the private key you want to delete, click **Delete**.
+{% ifversion github-app-repository-permission-improvements %}1. In the left sidebar, click **{% octicon "key" aria-hidden="true" aria-label="code" %} Credentials**, then click **{% octicon "key" aria-hidden="true" aria-label="code" %} Key pairs**.
+1. Under "Key pairs", to the right of the private key you want to delete, click **Delete**.{% else %}
+1. Under "Private keys", to the right of the private key you want to delete, click **Delete**.{% endif %}
 1. When prompted, confirm you want to delete the private key by clicking **Delete**. If your {% data variables.product.prodname_github_app %} has only one key, you will need to generate a new key before deleting the old key. For more information, see [Generating private keys](#generating-private-keys).
 
 ## Storing private keys

content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md

@@ -25,6 +25,14 @@ You can use the refresh token to generate a new user access token and a new refr
 
 If your refresh token expires before you use it, you can regenerate a user access token and refresh token by sending users through the web application flow or device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app).
 
+{% ifversion github-app-offline-access %}
+
+To test and gradually roll out support for expiring tokens, you can opt in for an individual user authorization by requesting the `offline_access` scope. When you request `offline_access`, you will receive an expiring user access token and a refresh token even if your app is configured not to use expiring user access tokens.
+
+The `scope` parameter does not grant permissions to a {% data variables.product.prodname_github_app %}. The only supported value is `offline_access`, which forces the user access token to expire.
+
+{% endif %}
+
 ## Configuring your app to use user access tokens that expire
 
 When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). You can also configure this setting after your app has been created.
@@ -37,7 +45,7 @@ When you create your app, expiration of user access tokens is enabled unless you
 
    {% data variables.product.company_short %} recommends that you opt in to this feature for improved security.
 
-If you opt into user access tokens that expire after you have already generated user access tokens, the previously generated user access tokens will not expire. You can delete these tokens by using the `DELETE /applications/CLIENT_ID/token` endpoint. For more information, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token).
+If you re-enable expiring user access tokens after you've already signed in users and gotten their access token, those pre-existing user access tokens will not expire. You should delete these tokens by using the `DELETE /applications/CLIENT_ID/token` endpoint or have the users reauthenticate so that they get an expiring token. For more information, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token).
 
 ## Refreshing a user access token with a refresh token
 

content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md

@@ -45,7 +45,13 @@ The success of an API request with a user access token depends on the user's per
 
 For more information about specifying permissions during {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
 
-Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission.
+Some webhooks and API access require "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission.
+
+{% ifversion github-app-repository-permission-improvements %}
+
+If your app only needs "Administration" permission to create repositories, request the "Repository creation" permission instead. This more limited permission lets your app create repositories without granting access to other repository administration features. Your app is automatically given access to repositories it creates.
+
+{% endif %}
 
 ## About changes to permissions
 

content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md

@@ -37,6 +37,20 @@ If you want your {% data variables.product.prodname_github_app %} to be availabl
 If it is important for {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} users to be able to use your tool, consider using {% data variables.product.prodname_actions %} instead of a {% data variables.product.prodname_github_app %}. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with GitHub Connect. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect) and [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %}
 
 For information about changing the visibility of a {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration).
+{% ifversion github-app-details-visibility %}
+
+### Accessing details of other {% data variables.product.prodname_github_apps %}
+
+A {% data variables.product.prodname_github_app %} can use the "Get an app" REST API endpoint to access details of another app when one of these are true:
+
+* The target app is public.
+* Both apps are owned by the same organization, regardless of the target app's visibility.
+* The target app is internal, and both apps belong to the same enterprise.
+* The requesting app is owned by an enterprise, and the target app is owned by an organization in that enterprise.
+
+For more information, see [AUTOTITLE](/rest/apps/apps#get-an-app).
+
+{% endif %}
 
 ### Public installation flow