Merge pull request #25791 from github/repo-sync

repo sync

content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md

@@ -94,7 +94,11 @@ You can also create an OAuth token with an {% data variables.product.prodname_oa
 
 ### Authenticating to the API in a {% data variables.product.prodname_actions %} workflow
 
-If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
+If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key.
+
+Note that `GITHUB_TOKEN` can only access resources within the repository that contains the workflow. If you need to make changes to resources outside of the workflow repository, you will need to use a {% data variables.product.pat_generic %} or {% data variables.product.prodname_github_app %}.
+
+For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
 
 ## Authenticating with the command line
 

content/authentication/keeping-your-account-and-data-secure/index.md

@@ -16,7 +16,7 @@ children:
   - /about-authentication-to-github
   - /creating-a-strong-password
   - /updating-your-github-access-credentials
-  - /creating-a-personal-access-token
+  - /managing-your-personal-access-tokens
   - /reviewing-your-ssh-keys
   - /reviewing-your-deploy-keys
   - /token-expiration-and-revocation
@@ -31,3 +31,4 @@ children:
   - /viewing-and-managing-your-sessions
 shortTitle: Account security
 ---
+

content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md

@@ -1,6 +1,7 @@
 ---
-title: Creating a personal access token
-intro: 'Use a {% data variables.product.pat_generic %} in place of a password when authenticating to GitHub in the command line or with the API.'
+title: Managing your personal access tokens
+shortTitle: 'Manage {% data variables.product.pat_generic %}s'
+intro: 'You can use a {% data variables.product.pat_generic %} in place of a password when authenticating to GitHub in the command line or with the API.'
 redirect_from:
   - /articles/creating-an-oauth-token-for-command-line-use
   - /articles/creating-an-access-token-for-command-line-use
@@ -9,6 +10,7 @@ redirect_from:
   - /github/authenticating-to-github/creating-a-personal-access-token
   - /github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
   - /github/extending-github/git-automation-with-oauth-tokens
+  - /authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
 versions:
   fpt: '*'
   ghes: '*'
@@ -17,7 +19,6 @@ versions:
 topics:
   - Identity
   - Access management
-shortTitle: 'Create a {% data variables.product.pat_generic %}'
 ---
 
 {% warning %}
@@ -79,6 +80,8 @@ If these options are not possible, and you must create a {% data variables.produ
 
 When using a {% data variables.product.pat_generic %} in a script, you can store your token as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."{%- ifversion ghec or fpt %} You can also store your token as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)."{% endif %}
 
+For more information about best practices, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
+
 ## Creating a {% data variables.product.pat_v2 %}
 
 {% note %}
@@ -142,9 +145,24 @@ If you selected an organization as the resource owner and the organization requi
    ![Screenshot of the "{% data variables.product.pat_generic_caps_plural %}" page. Next to a blurred-out token, an icon of two overlapping squares is outlined in orange.](/assets/images/help/settings/personal_access_tokens.png){% ifversion fpt or ghec %}
 1. To use your token to access resources owned by an organization that uses SAML single sign-on, authorize the token. For more information, see "[AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}."{% endif %}{% endif %}
 
+## Deleting a {% data variables.product.pat_generic %}
+
+{% data reusables.user-settings.access_settings %}
+{% data reusables.user-settings.developer_settings %}
+{% ifversion pat-v2 %}1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click either **Fine-grained tokens** or **Tokens (classic)**, depending on which type of {% data variables.product.pat_generic %} you'd like to delete.{% else %}{% data reusables.user-settings.personal_access_tokens %}{% endif %}
+1. To the right of the {% data variables.product.pat_generic %} you want to delete, click **Delete**.
+
 ## Using a {% data variables.product.pat_generic %} on the command line
 
-{% data reusables.command_line.providing-token-as-password %}
+Once you have a {% data variables.product.pat_generic %}, you can enter it instead of your password when performing Git operations over HTTPS.
+
+For example, to clone a repository on the command line you would enter the following `git clone` command. You would then be prompted to enter your username and password. When prompted for your password, enter your {% data variables.product.pat_generic %} instead of a password.
+
+```shell
+$ git clone https://{% data variables.command_line.codeblock %}/USERNAME/REPO.git
+Username: YOUR_USERNAME
+Password: YOUR_PERSONAL_ACCESS_TOKEN
+```
 
 {% data variables.product.pat_generic_caps %}s can only be used for HTTPS Git operations. If your repository uses an SSH remote URL, you will need to [switch the remote from SSH to HTTPS](/get-started/getting-started-with-git/managing-remote-repositories#switching-remote-urls-from-ssh-to-https).
 

content/rest/guides/getting-started-with-the-rest-api.md

@@ -104,6 +104,8 @@ If you want to use the API on behalf of an organization or another user, {% data
 
 If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
 
+For more information about best practices you can use to keep your tokens secure, see "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."
+
 ### Authentication example
 
 {% cli %}

content/rest/index.md

@@ -19,7 +19,7 @@ featuredLinks:
     - /rest/overview/other-authentication-methods
     - /rest/overview/troubleshooting
     - /rest/guides/scripting-with-the-rest-api-and-javascript
-    - /rest/overview/openapi-description
+    - /rest/overview/keeping-your-api-credentials-secure
   guideCards:
     - /rest/guides/delivering-deployments
     - /rest/guides/using-the-rest-api-to-interact-with-checks

content/rest/overview/authenticating-to-the-rest-api.md

@@ -89,3 +89,7 @@ curl --request GET \
 Authentication with username and password is not supported. If you try to authenticate with user name and password, you will receive a 4xx error.
 
 {% endif %}
+
+## Further reading
+
+- "[AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure)."

content/rest/overview/endpoints-available-for-fine-grained-personal-access-tokens.md

@@ -3,7 +3,7 @@ title: Endpoints available for fine-grained personal access tokens
 intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.'
 versions:
   feature: pat-v2
-shortTitle: '{% data variables.product.pat_v2_caps %}-enabled endpoints'
+shortTitle: 'Endpoints for fine-grained PATs'
 ---
 
 ## actions

content/rest/overview/endpoints-available-for-github-apps.md

@@ -12,7 +12,7 @@ versions:
   ghec: '*'
 topics:
   - API
-shortTitle: GitHub App-enabled endpoints
+shortTitle: Endpoints for GitHub Apps
 autogenerated: github-apps
 ---
 

content/rest/overview/index.md

@@ -15,15 +15,15 @@ children:
   - /api-versions
   - /media-types
   - /authenticating-to-the-rest-api
+  - /keeping-your-api-credentials-secure
   - /troubleshooting
   - /libraries
   - /openapi-description
   - /endpoints-available-for-github-apps
   - /endpoints-available-for-fine-grained-personal-access-tokens
   - /permissions-required-for-github-apps
-  - /breaking-changes
   - /permissions-required-for-fine-grained-personal-access-tokens
+  - /breaking-changes
 redirect_from:
   - /developers/overview
 ---
-

content/rest/overview/keeping-your-api-credentials-secure.md

@@ -0,0 +1,75 @@
+---
+title: Keeping your API credentials secure
+shortTitle: Keeping API credentials secure
+intro: 'Follow these best practices to keep your API credentials and tokens secure.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+topics:
+  - API
+---
+
+## Choose an appropriate authentication method
+
+You should choose an authentication method that is appropriate for the task you want to accomplish.
+
+- To use the API for personal use, you can create a {% data variables.product.pat_generic %}.
+- To use the API on behalf of an organization or another user, you should create a {% data variables.product.prodname_github_app %}.
+- To use the API in a {% data variables.product.prodname_actions %} workflow, you should authenticate with the built-in `GITHUB_TOKEN`.
+
+For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-api)."
+
+## Limit the permissions of your credentials
+
+{% ifversion pat-v2 %}
+
+When creating a {% data variables.product.pat_generic %}, only select the minimum permissions or scopes needed, and set an expiration date for the minimum amount of time you'll need to use the token. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %}. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens)."
+
+{% else %}
+
+When creating a {% data variables.product.pat_generic %}, only select the minimum scopes needed, and set an expiration date for the minimum amount of time you'll need to use the token. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
+
+{% endif %}
+
+When creating a {% data variables.product.prodname_github_app %}, select the minimum permissions that your {% data variables.product.prodname_github_app %} will need. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+When authenticating with `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow, only give the minimum amount of permissions needed. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)."
+
+## Store your authentication credentials securely
+
+Treat authentication credentials the same way you would treat your passwords or other sensitive credentials.
+
+- Don't share authentication credentials using an unencrypted messaging or email system.
+- Don't pass your {% data variables.product.pat_generic %} as plain text in the command line. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#keeping-your-personal-access-tokens-secure)."
+- Don't push unencrypted authentication credentials like tokens or keys to any repository, even if the repository is private. Instead consider using a {% data variables.product.prodname_actions %} secret{% ifversion fpt or ghec %} or Codespaces secret{% endif %}. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion fpt or ghec %} and "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)"{% endif %}.
+- You can use secret scanning to discover tokens, private keys, and other secrets that were pushed to a repository, or to block future pushes that contain secrets. For more information, see "[AUTOTITLE](/code-security/secret-scanning/about-secret-scanning)."
+
+## Limit who can access your authentication credentials
+
+Don't share your {% data variables.product.pat_generic %} with others. Instead of sharing a {% data variables.product.pat_generic %}, consider creating a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps)."
+
+If you need to share credentials with a team, store the credentials in a secure shared system. For example, you could store and share passwords securely using [1Password](https://1password.com/), or you could store keys in [Azure KeyVault](https://azure.microsoft.com/en-gb/products/key-vault) and manage access with your IAM (Identity and access management).
+
+If you're creating a {% data variables.product.prodname_actions %} workflow that needs to access the API, you can store your credentials in an encrypted secret, and access the encrypted secret from the workflow. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion projects-v2 %} and "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)"{% endif %}.
+
+## Use authentication credentials securely in your code
+
+Never hardcode authentication credentials like tokens, keys, or app-related secrets into your code. Instead, consider using a secret manager such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault) or [HashiCorp Vault](https://www.hashicorp.com/products/vault). For more information about securing {% data variables.product.prodname_github_app %} credentials, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+When using a {% data variables.product.pat_generic %} in a script, consider storing your token as a {% data variables.product.prodname_actions %} secret and running your script through {% data variables.product.prodname_actions %}.{% ifversion fpt or ghec %}  You can also store your token as a Codespaces secret and run your script in Codespaces.{% endif %} For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)"{% ifversion fpt or ghec %} and "[AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces)"{% endif %}.
+
+If none of these options are possible, you can store authentication credentials in a `.env` file. Make sure to encrypt your `.env` file, and never push it to any repository.
+
+## Prepare a remediation plan
+
+You should create a plan to handle any security breaches in a timely manner. In the event that your token or other authentication credential is leaked, you will need to:
+
+- Generate a new credential.
+- Replace the old credential with the new one everywhere that you are storing or accessing the credential.
+- Delete the old compromised credential.
+
+For information about rotating compromised credentials for a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
+
+For information about creating and deleting {% data variables.product.pat_generic %}s, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."

content/rest/overview/permissions-required-for-fine-grained-personal-access-tokens.md

@@ -3,7 +3,7 @@ title: Permissions required for fine-grained personal access tokens
 intro: 'You can find the required permissions for each {% data variables.product.pat_v2 %}-compatible endpoint.'
 versions:
   feature: pat-v2
-shortTitle: '{% data variables.product.pat_v2_caps %} permissions'
+shortTitle: 'Permissions for fine-grained PATs'
 ---
 
 ## About permissions required for {% data variables.product.pat_v2 %}

content/rest/overview/permissions-required-for-github-apps.md

@@ -11,7 +11,7 @@ versions:
   ghec: '*'
 topics:
   - API
-shortTitle: GitHub App permissions
+shortTitle: Permissions for GitHub Apps
 ---
 
 ## About {% data variables.product.prodname_github_app %} permissions

content/site-policy/other-site-policies/github-account-recovery-policy.md

@@ -0,0 +1,35 @@
+---
+title: GitHub Account Recovery Policy
+versions:
+  fpt: '*'
+topics:
+  - 2FA
+  - Policy
+  - Legal
+---
+
+GitHub provides [a number of account recovery methods](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials) including an [automated recovery process](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials#authenticating-with-a-verified-device-ssh-token-or-personal-access-token) if you have lost access to your GitHub.com account. **If you cannot use any of the provided recovery methods, you have permanently lost access to your account.**  
+
+You can, however, [unlink email addresses](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account) from a locked account in order to create a new account or use the email on another existing account.
+
+## Can I open a support ticket to recover my account?
+
+For security reasons, **GitHub Support will not restore access to accounts with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.** You must use existing [account recovery methods](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials).
+
+GitHub does not support any other means of account recovery, including social or ID verification, by members of GitHub’s staff. This policy is in place to protect your account from unauthorized access through social engineering.
+
+## How can I retrieve my email from a locked account?
+
+See [Unlinking your email address from a locked account](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account).
+
+## How can I remove a payment method from a locked account?
+
+Please contact Support to request removal of a payment method from a locked out account. Remember, **GitHub Support will not restore your account** if you lose access to your account recovery methods.
+
+## Can I recover the contents of a user or organization account I lost access to?
+
+If you have lost access to a user account, you may [clone](/repositories/creating-and-managing-repositories/cloning-a-repository) or [fork](/get-started/quickstart/fork-a-repo) any content that is public.
+
+If you have lost access to an organization account, you may clone or fork any content that is public and you may be able to request that remaining members of the organization clone or fork any private content.
+
+GitHub Support will not recover the contents of a user or organization account that is locked.

content/site-policy/other-site-policies/index.md

@@ -12,5 +12,6 @@ children:
   - /github-government-takedown-policy
   - /github-username-policy
   - /guidelines-for-legal-requests-of-user-data
+  - /github-account-recovery-policy
 ---
 

data/reusables/command_line/providing-token-as-password.md

@@ -1,9 +0,0 @@
-Once you have a token, you can enter it instead of your password when performing Git operations over HTTPS.
-
-For example, on the command line you would enter the following:
-
-```shell
-$ git clone https://{% data variables.command_line.codeblock %}/USERNAME/REPO.git
-Username: YOUR_USERNAME
-Password: YOUR_TOKEN
-```

data/reusables/two_fa/support-may-not-help.md

@@ -1 +1 @@
-For security reasons, {% data variables.product.product_name %} Support may not be able to restore access to accounts with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.
+For security reasons, {% data variables.product.product_name %} Support [will not be able to restore access to accounts](/free-pro-team@latest/site-policy/other-site-policies/github-account-recovery-policy) with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.