jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Remove redundant 'pat-v2' versioning (#52362)

Browse Source
This commit is contained in:
Ben Ahmady
2024-09-25 13:58:24 +01:00
committed by GitHub
parent 18e48896e4
commit 272a9a35c6
26 changed files with 43 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners.md
View File

@@ -51,7 +51,7 @@ You can use the self-hosted runner application's `config` script with the `--che
In addition to `--check`, you must provide two arguments to the script: In addition to `--check`, you must provide two arguments to the script:
* `--url` with the URL to your {% data variables.product.company_short %} repository, organization, or enterprise. For example, `--url https://github.com/octo-org/octo-repo`. * `--url` with the URL to your {% data variables.product.company_short %} repository, organization, or enterprise. For example, `--url https://github.com/octo-org/octo-repo`.
* `--pat` with the value of a {% data variables.product.pat_v1 %}, which must have the `workflow` scope{% ifversion pat-v2%}, or a {% data variables.product.pat_v2 %} with workflows read and write access {% endif %}. For example, `--pat ghp_abcd1234`. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." * `--pat` with the value of a {% data variables.product.pat_v1 %}, which must have the `workflow` scope, or a {% data variables.product.pat_v2 %} with workflows read and write access. For example, `--pat ghp_abcd1234`. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
For example: For example:

2
content/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions.md
View File

@@ -297,7 +297,7 @@ This list describes the recommended approaches for accessing repository data wit
* {% data variables.product.prodname_github_apps %} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {% data variables.product.prodname_github_app %} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories. For more information, see "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)." * {% data variables.product.prodname_github_apps %} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {% data variables.product.prodname_github_app %} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories. For more information, see "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)."
1. **{% data variables.product.pat_generic %}s** 1. **{% data variables.product.pat_generic %}s**
* You should never use a {% data variables.product.pat_v1 %}. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. This indirectly grants broad access to all write-access users of the repository the workflow is in. * You should never use a {% data variables.product.pat_v1 %}. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. This indirectly grants broad access to all write-access users of the repository the workflow is in.
* If you do use a {% data variables.product.pat_generic %}, you should never use a {% data variables.product.pat_generic %} from your own account. If you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging. Instead, you should use a {% ifversion pat-v2%}{% data variables.product.pat_v2 %}s{% else %}{% data variables.product.pat_generic %}s{% endif %} for a new account that belongs to your organization and that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys. * If you do use a {% data variables.product.pat_generic %}, you should never use a {% data variables.product.pat_generic %} from your own account. If you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging. Instead, you should use a {% data variables.product.pat_v2 %}for a new account that belongs to your organization and that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys.
1. **SSH keys on a personal account** 1. **SSH keys on a personal account**
* Workflows should never use the SSH keys on a personal account. Similar to {% data variables.product.pat_v1_plural %}, they grant read/write permissions to all of your personal repositories as well as all the repositories you have access to through organization membership. This indirectly grants broad access to all write-access users of the repository the workflow is in. If you're intending to use an SSH key because you only need to perform repository clones or pushes, and do not need to interact with public APIs, then you should use individual deploy keys instead. * Workflows should never use the SSH keys on a personal account. Similar to {% data variables.product.pat_v1_plural %}, they grant read/write permissions to all of your personal repositories as well as all the repositories you have access to through organization membership. This indirectly grants broad access to all write-access users of the repository the workflow is in. If you're intending to use an SSH key because you only need to perform repository clones or pushes, and do not need to interact with public APIs, then you should use individual deploy keys instead.

4
content/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions.md
View File

@@ -61,9 +61,9 @@ You can also manage secrets using the REST API. For more information, see "[AUTO
When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible. When generating credentials, we recommend that you grant the minimum permissions possible. For example, instead of using personal credentials, use [deploy keys](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys) or a service account. Consider granting read-only permissions if that's all that is needed, and limit access as much as possible.
When generating a {% data variables.product.pat_v1 %}, select the fewest scopes necessary.{% ifversion pat-v2 %} When generating a {% data variables.product.pat_v2 %}, select the minimum permissions and repository access required.{% endif %} When generating a {% data variables.product.pat_v1 %}, select the fewest scopes necessary. When generating a {% data variables.product.pat_v2 %}, select the minimum permissions and repository access required.
Instead of using a {% data variables.product.pat_generic %}, consider using a {% data variables.product.prodname_github_app %}, which uses fine-grained permissions and short lived tokens{% ifversion pat-v2 %}, similar to a {% data variables.product.pat_v2 %}{% endif %}. Unlike a {% data variables.product.pat_generic %}, a {% data variables.product.prodname_github_app %} is not tied to a user, so the workflow will continue to work even if the user who installed the app leaves your organization. For more information, see "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)." Instead of using a {% data variables.product.pat_generic %}, consider using a {% data variables.product.prodname_github_app %}, which uses fine-grained permissions and short lived tokens, similar to a {% data variables.product.pat_v2 %}. Unlike a {% data variables.product.pat_generic %}, a {% data variables.product.prodname_github_app %} is not tied to a user, so the workflow will continue to work even if the user who installed the app leaves your organization. For more information, see "[AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)."
{% note %} {% note %}

2
content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md
View File

@@ -62,7 +62,7 @@ Some examples of automations you could create with a {% data variables.product.p
If you want your app to take actions on behalf of itself, rather than a user, you should use an installation access token for authentication. This type of request is sometimes called "server-to-server," and it means that the app will be limited by the permissions that have been given to the app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)." If you want your app to take actions on behalf of itself, rather than a user, you should use an installation access token for authentication. This type of request is sometimes called "server-to-server," and it means that the app will be limited by the permissions that have been given to the app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)."
Some examples of automations you could create with a {% data variables.product.prodname_github_app %}, where the app acts on its own behalf, include: Some examples of automations you could create with a {% data variables.product.prodname_github_app %}, where the app acts on its own behalf, include:
* A {% data variables.product.prodname_github_app %} that uses webhooks to react to an event given a certain set of criteria. {% ifversion pat-v2 %}For example, you could create an automation around the REST API endpoints for [reviewing requests for {% data variables.product.pat_v2 %}](/rest/orgs/personal-access-tokens?apiVersion=2022-11-28#review-requests-to-access-organization-resources-with-fine-grained-personal-access-tokens) that approves a request given a certain policy.{% else %}For example, you could create an automation that uses [the REST API endpoints for labels](/rest/issues/labels) to add a label to each new issue created in a repository, given a certain set of criteria.{% endif %} * A {% data variables.product.prodname_github_app %} that uses webhooks to react to an event given a certain set of criteria. For example, you could create an automation around the REST API endpoints for [reviewing requests for {% data variables.product.pat_v2 %}](/rest/orgs/personal-access-tokens?apiVersion=2022-11-28#review-requests-to-access-organization-resources-with-fine-grained-personal-access-tokens) that approves a request given a certain policy.
* A {% data variables.product.prodname_github_app %} that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment. * A {% data variables.product.prodname_github_app %} that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment.
* A {% data variables.product.prodname_github_app %} that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository. * A {% data variables.product.prodname_github_app %} that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository.

2
content/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.md
View File

@@ -12,7 +12,7 @@ topics:
- SSO - SSO
shortTitle: '{% data variables.product.pat_generic_caps %} with SAML' shortTitle: '{% data variables.product.pat_generic_caps %} with SAML'
--- ---
You must authorize your {% data variables.product.pat_v1 %} after creation before the token can access an organization that uses SAML single sign-on (SSO). For more information about creating a new {% data variables.product.pat_v1 %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."{% ifversion pat-v2 %} {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted.{% endif %} You must authorize your {% data variables.product.pat_v1 %} after creation before the token can access an organization that uses SAML single sign-on (SSO). For more information about creating a new {% data variables.product.pat_v1 %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted.
{% data reusables.saml.must-authorize-linked-identity %} {% data reusables.saml.must-authorize-linked-identity %}

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

@@ -91,7 +91,7 @@ You can authenticate with the API in different ways. For more information, see "
### Authenticating to the API with a {% data variables.product.pat_generic %} ### Authenticating to the API with a {% data variables.product.pat_generic %}
If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}.{% ifversion pat-v2 %} If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}.{% endif %} For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
### Authenticating to the API with an app ### Authenticating to the API with an app
@@ -139,10 +139,8 @@ To use a {% data variables.product.pat_generic %} or SSH key to access resources
| Token type | Prefix | More information | | Token type | Prefix | More information |
| :- | :- | :- | | :- | :- | :- |
| {% data variables.product.pat_v1_caps %} | `ghp_` | {% ifversion pat-v2 %}"[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic)"{% else %}"[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)"{% endif %} | | {% data variables.product.pat_v1_caps %} | `ghp_` | "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic)" |
| {% ifversion pat-v2 %} |
| {% data variables.product.pat_v2_caps %} | `github_pat_` | "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)" | | {% data variables.product.pat_v2_caps %} | `github_pat_` | "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)" |
| {% endif %} |
| OAuth access token | `gho_` | "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)" | | OAuth access token | `gho_` | "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)" |
| User access token for a {% data variables.product.prodname_github_app %} | `ghu_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)" | | User access token for a {% data variables.product.prodname_github_app %} | `ghu_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)" |
| Installation access token for a {% data variables.product.prodname_github_app %} | `ghs_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)" | | Installation access token for a {% data variables.product.prodname_github_app %} | `ghs_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)" |

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

@@ -22,8 +22,7 @@ topics:
{% warning %} {% warning %}
**Warning**: Treat your access tokens like passwords. {% ifversion pat-v2 %} **Warning**: Treat your access tokens like passwords. For more information, see "[Keeping your {% data variables.product.pat_generic %}s secure](#keeping-your-personal-access-tokens-secure)."
For more information, see "[Keeping your {% data variables.product.pat_generic %}s secure](#keeping-your-personal-access-tokens-secure)."{% endif %}
{% endwarning %} {% endwarning %}
@@ -35,20 +34,14 @@ For more information, see "[Keeping your {% data variables.product.pat_generic %
{% data reusables.user-settings.token_access_capabilities %} For example, a {% data variables.product.pat_generic %} can be configured with an `admin:org` scope, but if the owner of the token is not an organization owner, the token will not give administrative access to the organization. {% data reusables.user-settings.token_access_capabilities %} For example, a {% data variables.product.pat_generic %} can be configured with an `admin:org` scope, but if the owner of the token is not an organization owner, the token will not give administrative access to the organization.
{% ifversion pat-v2 %}
### Types of {% data variables.product.pat_generic %}s ### Types of {% data variables.product.pat_generic %}s
{% data variables.product.company_short %} currently supports two types of {% data variables.product.pat_generic %}s: {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible. {% data variables.product.company_short %} currently supports two types of {% data variables.product.pat_generic %}s: {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible.
Both {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} are tied to the user who generated them and will become inactive if the user loses access to the resource. Both {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} are tied to the user who generated them and will become inactive if the user loses access to the resource.
{% ifversion pat-v2 %}
Organization owners can set a policy to restrict the access of {% data variables.product.pat_v1_plural %} to their organization{% ifversion ghec or ghes %}, and enterprise owners can restrict the access of {% data variables.product.pat_v1_plural %} to the enterprise or organizations owned by the enterprise{% endif %}. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens-classic)." Organization owners can set a policy to restrict the access of {% data variables.product.pat_v1_plural %} to their organization{% ifversion ghec or ghes %}, and enterprise owners can restrict the access of {% data variables.product.pat_v1_plural %} to the enterprise or organizations owned by the enterprise{% endif %}. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens-classic)."
{% endif %}
#### {% data variables.product.pat_v2_caps %}s #### {% data variables.product.pat_v2_caps %}s
{% data variables.product.pat_v2_caps %}s have several security advantages over {% data variables.product.pat_v1_plural %}: {% data variables.product.pat_v2_caps %}s have several security advantages over {% data variables.product.pat_v1_plural %}:
@@ -66,13 +59,9 @@ Organization owners can set a policy to restrict the access of {% data variables
If you choose to use a {% data variables.product.pat_v1 %}, keep in mind that it will grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. If you choose to use a {% data variables.product.pat_v1 %}, keep in mind that it will grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account.
{% endif %}
{% ifversion fpt or ghec %}{% data reusables.user-settings.removes-personal-access-tokens %} {% ifversion fpt or ghec %}{% data reusables.user-settings.removes-personal-access-tokens %}
{% endif %} {% endif %}
{% ifversion pat-v2 %}
### Keeping your {% data variables.product.pat_generic %}s secure ### Keeping your {% data variables.product.pat_generic %}s secure
{% data variables.product.pat_generic_caps %}s are like passwords, and they share the same inherent security risks. Before creating a new {% data variables.product.pat_generic %}, consider if there is a more secure method of authentication available to you: {% data variables.product.pat_generic_caps %}s are like passwords, and they share the same inherent security risks. Before creating a new {% data variables.product.pat_generic %}, consider if there is a more secure method of authentication available to you:
@@ -114,35 +103,25 @@ For more information about best practices, see "[AUTOTITLE](/rest/overview/keepi
If you selected an organization as the resource owner and the organization requires approval for {% data variables.product.pat_v2 %}s, then your token will be marked as `pending` until it is reviewed by an organization administrator. Your token will only be able to read public resources until it is approved. If you are an owner of the organization, your request is automatically approved. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization)." If you selected an organization as the resource owner and the organization requires approval for {% data variables.product.pat_v2 %}s, then your token will be marked as `pending` until it is reviewed by an organization administrator. Your token will only be able to read public resources until it is approved. If you are an owner of the organization, your request is automatically approved. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization)."
{% endif %}
## Creating a {% data variables.product.pat_v1 %} ## Creating a {% data variables.product.pat_v1 %}
{% ifversion pat-v2 %}
{% note %} {% note %}
**Note**: Organization owners can restrict the access of {% data variables.product.pat_v1 %} to their organization. If you try to use a {% data variables.product.pat_v1 %} to access resources in an organization that has disabled {% data variables.product.pat_v1 %} access, your request will fail with a 403 response. Instead, you must use a {% data variables.product.prodname_github_app %}, {% data variables.product.prodname_oauth_app %}, or {% data variables.product.pat_v2 %}. **Note**: Organization owners can restrict the access of {% data variables.product.pat_v1 %} to their organization. If you try to use a {% data variables.product.pat_v1 %} to access resources in an organization that has disabled {% data variables.product.pat_v1 %} access, your request will fail with a 403 response. Instead, you must use a {% data variables.product.prodname_github_app %}, {% data variables.product.prodname_oauth_app %}, or {% data variables.product.pat_v2 %}.
{% endnote %} {% endnote %}
{% endif %}
{% ifversion pat-v2 %}
{% warning %} {% warning %}
**Note**: Your {% data variables.product.pat_v1 %} can access every repository that you can access. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead, which you can restrict to specific repositories. {% data variables.product.pat_v2_caps %}s also enable you to specify fine-grained permissions instead of broad scopes. **Note**: Your {% data variables.product.pat_v1 %} can access every repository that you can access. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead, which you can restrict to specific repositories. {% data variables.product.pat_v2_caps %}s also enable you to specify fine-grained permissions instead of broad scopes.
{% endwarning %} {% endwarning %}
{% endif %}
{% ifversion fpt or ghec %}1. [Verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address), if it hasn't been verified yet.{% endif %} {% ifversion fpt or ghec %}1. [Verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address), if it hasn't been verified yet.{% endif %}
{% data reusables.user-settings.access_settings %} {% data reusables.user-settings.access_settings %}
{% data reusables.user-settings.developer_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 **Tokens (classic)**.{% else %}{% data reusables.user-settings.personal_access_tokens %}{% endif %} 1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Tokens (classic)**.
{% ifversion pat-v2%}1. Select **Generate new token**, then click **Generate new token (classic)**.{% else %}{% data reusables.user-settings.generate_new_token %}{% endif %} 1. Select **Generate new token**, then click **Generate new token (classic)**.
1. In the "Note" field, give your token a descriptive name. 1. In the "Note" field, give your token a descriptive name.
1. To give your token an expiration, select **Expiration**, then choose a default option or click **Custom** to enter a date. 1. To give your token an expiration, select **Expiration**, then choose a default option or click **Custom** to enter a date.
1. Select the scopes you'd like to grant this token. To use your token to access repositories from the command line, select **repo**. A token with no assigned scopes can only access public information. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)." 1. Select the scopes you'd like to grant this token. To use your token to access repositories from the command line, select **repo**. A token with no assigned scopes can only access public information. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)."
@@ -158,7 +137,7 @@ You should delete a {% data variables.product.pat_generic %} if it is no longer
{% data reusables.user-settings.access_settings %} {% data reusables.user-settings.access_settings %}
{% data reusables.user-settings.developer_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. 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.
1. To the right of the {% data variables.product.pat_generic %} you want to delete, click **Delete**. 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 ## Using a {% data variables.product.pat_generic %} on the command line

2
content/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log.md
View File

@@ -49,9 +49,7 @@ The events listed in your security log are triggered by your actions. Actions ar
| {% ifversion fpt or ghec %} | | {% ifversion fpt or ghec %} |
| `payment_method` | Contains all activities related to paying for your {% data variables.product.prodname_dotcom %} subscription. | `payment_method` | Contains all activities related to paying for your {% data variables.product.prodname_dotcom %} subscription.
| {% endif %} | | {% endif %} |
| {% ifversion pat-v2%} |
| `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." | | `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." |
| {% endif %} |
| `profile_picture`| Contains all activities related to your profile picture. | | `profile_picture`| Contains all activities related to your profile picture. |
| `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}. | | `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}. |
| `public_key` | Contains all activities related to [your public SSH keys](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). | | `public_key` | Contains all activities related to [your public SSH keys](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). |

2
content/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program.md
View File

@@ -121,7 +121,7 @@ key to use based on the value of `Github-Public-Key-Identifier`.
{% note %} {% note %}
**Note**: When you send a request to the public key endpoint above, you may hit rate limits. To avoid hitting rate limits, you can use a {% data variables.product.pat_v1 %} (no scopes required){% ifversion pat-v2 %} or a {% data variables.product.pat_v2 %} (only the automatic public repositories read access required){% endif %} as suggested in the samples below, or use a conditional request. For more information, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#conditional-requests)." **Note**: When you send a request to the public key endpoint above, you may hit rate limits. To avoid hitting rate limits, you can use a {% data variables.product.pat_v1 %} (no scopes required) or a {% data variables.product.pat_v2 %} (only the automatic public repositories read access required) as suggested in the samples below, or use a conditional request. For more information, see "[AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#conditional-requests)."
{% endnote %} {% endnote %}

9
content/graphql/guides/forming-calls-with-graphql.md
View File

@@ -19,18 +19,13 @@ You can authenticate to the GraphQL API using a {% data variables.product.pat_ge
### Authenticating with a {% data variables.product.pat_generic %} ### Authenticating with a {% data variables.product.pat_generic %}
To authenticate with a {% data variables.product.pat_generic %}, follow the steps in "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." The data that you are requesting will dictate which scopes {% ifversion pat-v2 %}or permissions {% endif %}you will need. To authenticate with a {% data variables.product.pat_generic %}, follow the steps in "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." The data that you are requesting will dictate which scopes or permissions you will need.
{% ifversion pat-v2 %}
For example, select the "issues:read" permission to read all of the issues in the repositories your token has access to. For example, select the "issues:read" permission to read all of the issues in the repositories your token has access to.
All {% data variables.product.pat_v2 %}s include read access to public repositories. To access public repositories with a {% data variables.product.pat_v1 %}, select the "public_repo" scope. All {% data variables.product.pat_v2 %}s include read access to public repositories. To access public repositories with a {% data variables.product.pat_v1 %}, select the "public_repo" scope.
{% else %} If your token does not have the required scopes or permissions to access a resource, the API will return an error message that states the scopes or permissions your token needs.
For example, select the "read:user" scope to request data about users. Select the "public_repo" scope to request data about public repositories.
{% endif %}
If your token does not have the required scopes {% ifversion pat-v2 %}or permissions {% endif %}to access a resource, the API will return an error message that states the scopes {% ifversion pat-v2 %}or permissions {% endif %}your token needs.
### Authenticating with a {% data variables.product.prodname_github_app %} ### Authenticating with a {% data variables.product.prodname_github_app %}

3
content/graphql/guides/introduction-to-graphql.md
View File

@@ -120,8 +120,7 @@ GraphQL is [introspective](https://graphql.org/learn/introspection/). This means
{% note %} {% note %}
**Note**: If you get the response `"message": "Bad credentials"` or `401 Unauthorized`, check that you are using a valid token. {% ifversion pat-v2 %}If you receive a `403` error with `Resource not accessible by {% data variables.product.pat_generic %}`, ensure that your {% data variables.product.pat_v2 %} is targeted to the correct resource owner. For example, it must target the organization that owns the repository you are trying to access.{% endif %} **Note**: If you get the response `"message": "Bad credentials"` or `401 Unauthorized`, check that you are using a valid token. If you receive a `403` error with `Resource not accessible by {% data variables.product.pat_generic %}`, ensure that your {% data variables.product.pat_v2 %} is targeted to the correct resource owner. For example, it must target the organization that owns the repository you are trying to access.
{% endnote %} {% endnote %}
The results are in JSON, so we recommend pretty-printing them for easier reading and searching. You can use a command-line tool like [jq](https://stedolan.github.io/jq/) or pipe the results into `python -m json.tool` for this purpose. The results are in JSON, so we recommend pretty-printing them for easier reading and searching. You can use a command-line tool like [jq](https://stedolan.github.io/jq/) or pipe the results into `python -m json.tool` for this purpose.

2
content/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server.md
View File

@@ -166,7 +166,7 @@ The same process can be used to create mappings for each record that supports cu
1. Using the `ghe-migrator import` command, start the import process. You'll need: 1. Using the `ghe-migrator import` command, start the import process. You'll need:
* Your Migration GUID. For more information, see "[Preparing the migrated data for import to {% data variables.product.prodname_ghe_server %}](#preparing-the-migrated-data)." * Your Migration GUID. For more information, see "[Preparing the migrated data for import to {% data variables.product.prodname_ghe_server %}](#preparing-the-migrated-data)."
* Your {% data variables.product.pat_generic %} for authentication. The {% data variables.product.pat_generic %} that you use is only for authentication as a site administrator, and does not require any specific scope{% ifversion pat-v2 %} or permissions{% endif %}. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." * Your {% data variables.product.pat_generic %} for authentication. The {% data variables.product.pat_generic %} that you use is only for authentication as a site administrator, and does not require any specific scope or permissions. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
```shell ```shell
$ ghe-migrator import /home/admin/MIGRATION-GUID.tar.gz -g MIGRATION-GUID -u USERNAME -p TOKEN $ ghe-migrator import /home/admin/MIGRATION-GUID.tar.gz -g MIGRATION-GUID -u USERNAME -p TOKEN

4
content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md
View File

@@ -45,9 +45,7 @@ To search for specific events, use the `action` qualifier in your query. Actions
| `account` | Contains all activities related to your organization account. | `account` | Contains all activities related to your organization account.
| `advisory_credit` | Contains all activities related to crediting a contributor for a security advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see "[AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories)." | `advisory_credit` | Contains all activities related to crediting a contributor for a security advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see "[AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories)."
| {% endif %} | | {% endif %} |
| {% ifversion pat-v2%} |
| `auto_approve_personal_access_token_requests` | Contains activities related to your organization's approval policy for {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)." | `auto_approve_personal_access_token_requests` | Contains activities related to your organization's approval policy for {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)."
| {% endif %} |
| {% ifversion fpt or ghec %} | | {% ifversion fpt or ghec %} |
| `billing` | Contains all activities related to your organization's billing. | `billing` | Contains all activities related to your organization's billing.
| `business` | Contains activities related to business settings for an enterprise. | | `business` | Contains activities related to business settings for an enterprise. |
@@ -94,9 +92,7 @@ To search for specific events, use the `action` qualifier in your query. Actions
| {% ifversion fpt or ghec %} | | {% ifversion fpt or ghec %} |
| `payment_method` | Contains all activities related to how your organization pays for GitHub. | `payment_method` | Contains all activities related to how your organization pays for GitHub.
| {% endif %} | | {% endif %} |
| {% ifversion pat-v2%} |
| `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s in your organization. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." | `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s in your organization. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
| {% endif %} |
| `profile_picture`| Contains all activities related to your organization's profile picture. | `profile_picture`| Contains all activities related to your organization's profile picture.
| `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}. | `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}.
| `protected_branch` | Contains all activities related to protected branches. | `protected_branch` | Contains all activities related to protected branches.

6
content/organizations/managing-programmatic-access-to-your-organization/about-programmatic-access-in-your-organization.md
View File

@@ -1,6 +1,6 @@
--- ---
title: About programmatic access in your organization title: About programmatic access in your organization
intro: 'As an organization owner, you can control access to your organization by {% ifversion pat-v2%}{% data variables.product.pat_generic %}s, {% data variables.product.prodname_github_apps %}, and {% data variables.product.prodname_oauth_apps %}{% else %} {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}{% endif %}.' intro: 'As an organization owner, you can control access to your organization by {% data variables.product.pat_generic %}s, {% data variables.product.prodname_github_apps %}, and {% data variables.product.prodname_oauth_apps %}.'
permissions: Organization owners can control programmatic access in their organization. permissions: Organization owners can control programmatic access in their organization.
topics: topics:
- Organizations - Organizations
@@ -38,14 +38,10 @@ Organization managers can restrict {% data variables.product.prodname_oauth_apps
## {% data variables.product.pat_generic_caps %}s ## {% data variables.product.pat_generic_caps %}s
{% ifversion pat-v2%}
Organization owners can prevent {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} from accessing resources owned by the organization. Organization owners can also require approval for each {% data variables.product.pat_v2 %} that can access the organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)." Organization owners can prevent {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} from accessing resources owned by the organization. Organization owners can also require approval for each {% data variables.product.pat_v2 %} that can access the organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization)."
Organization owners can view all {% data variables.product.pat_v2 %}s that can access resources owned by the organization. Organization owners can also revoke access by {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization)." Organization owners can view all {% data variables.product.pat_v2 %}s that can access resources owned by the organization. Organization owners can also revoke access by {% data variables.product.pat_v2 %}s. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization)."
{% endif %}
{% ifversion ghec %} {% ifversion ghec %}
If their organization uses SAML, organization owners can see each {% data variables.product.pat_generic %} that a member of their organization authorized. For more information, see "[AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-authorized-credentials)." If their organization uses SAML, organization owners can see each {% data variables.product.pat_generic %} that a member of their organization authorized. For more information, see "[AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-authorized-credentials)."

4
content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md
View File

@@ -2,7 +2,9 @@
title: Managing requests for personal access tokens in your organization title: Managing requests for personal access tokens in your organization
intro: 'Organization owners can approve or deny {% data variables.product.pat_v2 %}s that request access to their organization.' intro: 'Organization owners can approve or deny {% data variables.product.pat_v2 %}s that request access to their organization.'
versions: versions:
feature: pat-v2 fpt: '*'
ghes: '*'
ghec: '*'
shortTitle: Manage token requests shortTitle: Manage token requests
--- ---

4
content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md
View File

@@ -2,7 +2,9 @@
title: Reviewing and revoking personal access tokens in your organization title: Reviewing and revoking personal access tokens in your organization
intro: 'Organization owners can review the {% data variables.product.pat_v2 %}s that can access their organization. They can also revoke access of specific {% data variables.product.pat_v2 %}s.' intro: 'Organization owners can review the {% data variables.product.pat_v2 %}s that can access their organization. They can also revoke access of specific {% data variables.product.pat_v2 %}s.'
versions: versions:
feature: pat-v2 fpt: '*'
ghes: '*'
ghec: '*'
shortTitle: Review token access shortTitle: Review token access
--- ---

4
content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md
View File

@@ -2,7 +2,9 @@
title: Setting a personal access token policy for your organization title: Setting a personal access token policy for your organization
intro: 'Organization owners can control whether to allow {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}, and can require approval for {% data variables.product.pat_v2 %}s.' intro: 'Organization owners can control whether to allow {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}, and can require approval for {% data variables.product.pat_v2 %}s.'
versions: versions:
feature: pat-v2 fpt: '*'
ghes: '*'
ghec: '*'
shortTitle: Set a token policy shortTitle: Set a token policy
--- ---

8
content/rest/authentication/authenticating-to-the-rest-api.md
View File

@@ -43,15 +43,15 @@ After detecting several requests with invalid credentials within a short period,
## Authenticating with a {% data variables.product.pat_generic %} ## Authenticating with a {% data variables.product.pat_generic %}
If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}.{% ifversion pat-v2 %} If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}.{% endif %} For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
{% ifversion pat-v2 %}If you are using a {% data variables.product.pat_v2 %}, your {% data variables.product.pat_v2 %} requires specific permissions in order to access each REST API endpoint. The REST API reference document for each endpoint states whether the endpoint works with {% data variables.product.pat_v2 %}s and states what permissions are required in order for the token to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.pat_v2 %} can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)."{% endif %} If you are using a {% data variables.product.pat_v2 %}, your {% data variables.product.pat_v2 %} requires specific permissions in order to access each REST API endpoint. The REST API reference document for each endpoint states whether the endpoint works with {% data variables.product.pat_v2 %}s and states what permissions are required in order for the token to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.pat_v2 %} can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)."
{% ifversion pat-v2 %}If you are using a {% data variables.product.pat_v1 %}, your {% else %}Your {% endif %}{% data variables.product.pat_v1 %} requires specific scopes in order to access each REST API endpoint. For general guidance about what scopes to choose, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)." If you are using a {% data variables.product.pat_v1 %}, it requires specific scopes in order to access each REST API endpoint. For general guidance about what scopes to choose, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)."
### {% data variables.product.pat_generic_caps_plural %} and SAML SSO ### {% data variables.product.pat_generic_caps_plural %} and SAML SSO
{% ifversion fpt or ghec %}If you use a {% data variables.product.pat_v1 %} to access an organization that enforces SAML single sign-on (SSO) for authentication, you will need to authorize your token after creation.{% ifversion pat-v2 %} {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted.{% endif %} For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)." {% ifversion fpt or ghec %}If you use a {% data variables.product.pat_v1 %} to access an organization that enforces SAML single sign-on (SSO) for authentication, you will need to authorize your token after creation. {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted. For more information, see "[AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)."
If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access a single organization that enforces SAML SSO, you may receive a `404 Not Found` or a `403 Forbidden` error. If you receive a `403 Forbidden` error, the `X-GitHub-SSO` header will include a URL that you can follow to authorize your token. The URL expires after one hour. If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access a single organization that enforces SAML SSO, you may receive a `404 Not Found` or a `403 Forbidden` error. If you receive a `403 Forbidden` error, the `X-GitHub-SSO` header will include a URL that you can follow to authorize your token. The URL expires after one hour.

4
content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md
View File

@@ -2,7 +2,9 @@
title: Endpoints available for fine-grained personal access tokens title: Endpoints available for fine-grained personal access tokens
intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.' intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.'
versions: versions:
feature: pat-v2 fpt: '*'
ghes: '*'
ghec: '*'
shortTitle: Endpoints for fine-grained PATs shortTitle: Endpoints for fine-grained PATs
autogenerated: github-apps autogenerated: github-apps
redirect_from: redirect_from:

8
content/rest/authentication/keeping-your-api-credentials-secure.md
View File

@@ -24,16 +24,8 @@ For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-
## Limit the permissions of your credentials ## 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)." 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 %}
{% data reusables.user-settings.token_access_capabilities %} {% data reusables.user-settings.token_access_capabilities %}
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 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)."

4
content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md
View File

@@ -2,7 +2,9 @@
title: Permissions required for fine-grained personal access tokens title: Permissions required for fine-grained personal access tokens
intro: 'For each permission granted to a {% data variables.product.pat_v2 %}, these are the REST API endpoints that the app can use.' intro: 'For each permission granted to a {% data variables.product.pat_v2 %}, these are the REST API endpoints that the app can use.'
versions: versions:
feature: pat-v2 fpt: '*'
ghes: '*'
ghec: '*'
shortTitle: Permissions for fine-grained PATs shortTitle: Permissions for fine-grained PATs
autogenerated: github-apps autogenerated: github-apps
redirect_from: redirect_from:

8
content/rest/using-the-rest-api/getting-started-with-the-rest-api.md
View File

@@ -349,16 +349,12 @@ curl --request GET \
The following example uses the "[Create an issue](/rest/issues/issues#create-an-issue)" endpoint to create a new issue in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} Replace `YOUR-TOKEN` with the authentication token you created in a previous step. The following example uses the "[Create an issue](/rest/issues/issues#create-an-issue)" endpoint to create a new issue in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} Replace `YOUR-TOKEN` with the authentication token you created in a previous step.
{% ifversion pat-v2 %}
{% note %} {% note %}
**Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." **Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
{% endnote %} {% endnote %}
{% endif %}
```shell copy ```shell copy
curl \ curl \
--request POST \ --request POST \
@@ -418,16 +414,12 @@ Create an access token to authenticate your request. You can save your token and
In the following example request, the HTTP method is `POST`, the path is `/repos/{owner}/{repo}/issues`, the path parameters are `owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}"` and `repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}"`, and the body parameters are `title: "Created with the REST API"` and `body: "This is a test issue created by the REST API"`.{% ifversion ghes %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %} In the following example request, the HTTP method is `POST`, the path is `/repos/{owner}/{repo}/issues`, the path parameters are `owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}"` and `repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}"`, and the body parameters are `title: "Created with the REST API"` and `body: "This is a test issue created by the REST API"`.{% ifversion ghes %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %}
{% ifversion pat-v2 %}
{% note %} {% note %}
**Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." **Note**: If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
{% endnote %} {% endnote %}
{% endif %}
```javascript copy ```javascript copy
await octokit.request("POST /repos/{owner}/{repo}/issues", { await octokit.request("POST /repos/{owner}/{repo}/issues", {
owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}", owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}",

12
content/rest/using-the-rest-api/troubleshooting-the-rest-api.md
View File

@@ -39,13 +39,13 @@ If you get a `404 Not Found` response when you know that the resource that you a
* If you are using a {% data variables.product.pat_v1 %}, you should ensure that: * If you are using a {% data variables.product.pat_v1 %}, you should ensure that:
* The token has the scopes that are required to use the endpoint. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)" and "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)." * The token has the scopes that are required to use the endpoint. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes)" and "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)."
* The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. * The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint.
* The token has not been expired or revoked. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)."{% ifversion pat-v2 %} * The token has not been expired or revoked. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)."
* If you are using a {% data variables.product.pat_v2 %}, you should ensure that: * If you are using a {% data variables.product.pat_v2 %}, you should ensure that:
* The token has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint. * The token has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint.
* The resource owner that was specified for the token matches the owner of the resource that the endpoint will affect. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)." * The resource owner that was specified for the token matches the owner of the resource that the endpoint will affect. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)."
* The token has access to any private repositories that the endpoint will affect. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)." * The token has access to any private repositories that the endpoint will affect. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)."
* The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. * The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint.
* The token has not been expired or revoked. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)."{% endif %} * The token has not been expired or revoked. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)."
* If you are using a {% data variables.product.prodname_github_app %} installation access token, you should ensure that: * If you are using a {% data variables.product.prodname_github_app %} installation access token, you should ensure that:
* The {% data variables.product.prodname_github_app %} has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint. * The {% data variables.product.prodname_github_app %} has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint.
* The endpoint is only affecting resources owned by the account where the {% data variables.product.prodname_github_app %} is installed. * The endpoint is only affecting resources owned by the account where the {% data variables.product.prodname_github_app %} is installed.
@@ -95,7 +95,7 @@ You can check the status of the REST API at [githubstatus.com](https://www.githu
## Resource not accessible ## Resource not accessible
If you are using a {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} and you receive a "Resource not accessible by integration"{% ifversion pat-v2 %} or "Resource not accessible by {% data variables.product.pat_generic %}"{% endif %} error, then your token has insufficient permissions. For more information about the required permissions, see the documentation for the endpoint. If you are using a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} and you receive a "Resource not accessible by integration" or "Resource not accessible by {% data variables.product.pat_generic %}" error, then your token has insufficient permissions. For more information about the required permissions, see the documentation for the endpoint.
{% ifversion rest-permissions-header %} {% ifversion rest-permissions-header %}
@@ -105,9 +105,9 @@ The value of the `X-Accepted-GitHub-Permissions` header is a comma separated lis
For example: For example:
* `X-Accepted-GitHub-Permissions: contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs read access to the contents permission. * `X-Accepted-GitHub-Permissions: contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs read access to the contents permission.
* `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs write access to the pull request permission and read access to the contents permission. * `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs write access to the pull request permission and read access to the contents permission.
* `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` means that your {% data variables.product.prodname_github_app %}{% ifversion pat-v2 %} or {% data variables.product.pat_v2 %}{% endif %} needs either read access to the pull request permission and read access to the contents permission, or read access to the issues permission and read access to the contents permission. * `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs either read access to the pull request permission and read access to the contents permission, or read access to the issues permission and read access to the contents permission.
{% endif %} {% endif %}

4
content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-github-app-webhook.md
View File

@@ -35,15 +35,11 @@ The endpoints to fetch and update the value of environment variables require a {
1. Store the app ID from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information about storing secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." 1. Store the app ID from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information about storing secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
1. Generate a private key for your app. For more information about generating a private key, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." 1. Generate a private key for your app. For more information about generating a private key, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)."
1. Store the private key, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`, from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. 1. Store the private key, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`, from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run.
{% ifversion pat-v2 %}
1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)." 1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
* For a {% data variables.product.pat_v2 %}, grant the token: * For a {% data variables.product.pat_v2 %}, grant the token:
* Write access to the repository variables permission * Write access to the repository variables permission
* Access to the repository where this workflow will run * Access to the repository where this workflow will run
* For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope. * For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope.
{% else %}
1. Create a {% data variables.product.pat_v1 %} with the `repo` scope. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
{% endif %}
1. Store your {% data variables.product.pat_generic %} from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. 1. Store your {% data variables.product.pat_generic %} from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run.
## Adding a workflow that will run the script ## Adding a workflow that will run the script

4
content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-webhook.md
View File

@@ -29,7 +29,6 @@ This example uses {% data variables.product.prodname_actions %}, but you can als
The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)." The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)."
{% ifversion pat-v2 %}
1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)." 1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
* For a {% data variables.product.pat_v2 %}, grant the token: * For a {% data variables.product.pat_v2 %}, grant the token:
* Access to the repository where your webhook was created * Access to the repository where your webhook was created
@@ -37,9 +36,6 @@ The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver we
* Write access to the repository webhooks permission * Write access to the repository webhooks permission
* Write access to the repository variables permission * Write access to the repository variables permission
* For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope. * For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope.
{% else %}
1. Create a {% data variables.product.pat_v1 %} with the `repo` scope. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
{% endif %}
1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." 1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
## Adding a workflow that will run the script ## Adding a workflow that will run the script

4
content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-an-organization-webhook.md
View File

@@ -29,7 +29,6 @@ This example uses {% data variables.product.prodname_actions %}, but you can als
The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)." The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow)."
{% ifversion pat-v2 %}
1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)." 1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
* For a {% data variables.product.pat_v2 %}: * For a {% data variables.product.pat_v2 %}:
* Set resource owner to be the organization where your webhook was created * Set resource owner to be the organization where your webhook was created
@@ -37,9 +36,6 @@ The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver we
* Grant the token write access to the organization webhooks permission * Grant the token write access to the organization webhooks permission
* Grant the token write access to the repository variables permission * Grant the token write access to the repository variables permission
* For a {% data variables.product.pat_v1 %}, grant the token the `admin:org_hook` and `repo` scope. * For a {% data variables.product.pat_v1 %}, grant the token the `admin:org_hook` and `repo` scope.
{% else %}
1. Create a {% data variables.product.pat_v1 %} with the `admin:org_hook` and `repo` scope. For more information, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)."
{% endif %}
1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." 1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
## Adding a workflow that will run the script ## Adding a workflow that will run the script