From b9238964f24b94f03be36bdebc5ac90ce79d954f Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Tue, 11 Mar 2025 14:23:14 +0100 Subject: [PATCH 1/7] feat: update docs for fine-grained-access tokens --- .../batch-changes/configuring-credentials.mdx | 66 +++++++++++++++++-- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index 2fa691269..478939616 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -101,13 +101,71 @@ Let's learn how you can do it for different code hosts. ### GitHub -On GitHub.com, [create a personal access token (classic) with the correct scopes](https://github.com/settings/tokens/new?scopes=repo,read:org,user:email,read:discussion,workflow). +On GitHub.com, create a personal access token or fine-grained access token with the correct scopes. The `workflow` scope is technically only required if your batch changes modify files in the `.github` directory of a repository. Still, it's recommended to enable it regardless to avoid confusing errors at a later time. When working with organizations that have SAML SSO (Single Sign On) enabled, configuring credentials requires an additional step that [involves white-listing the token for use in that organization](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). -At present, only classic personal access tokens (PATs) are supported. Alternative token types like OAuth access tokens (e.g., OAuth apps), and fine-grained personal access tokens (PATv2) are not supported. +At present, only classic and fine-grained access tokens are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps) are not supported. + +#### Personal Access Token + +Personal access tokens will have access to all repositories that you have access to. + +[Click here to prefill the form](https://github.com/settings/tokens/new?scopes=repo,read:org,user:email,read:discussion,workflow). + +Required Scopes: +- `repo` +- `read:org` +- `user:email` +- `read:discussion` +- `workflow` + +#### Fine-Grained Access Token + +Fine-grained access tokens allow more granular control of what actions can be performed for a given set of repositories. Most notably, fine-grained access tokens don't grant access by default to all repositories that you have access to. + +In contrast to personal access tokens, fine-grained access tokens for organization resources may be restricted, may have an expiration, and may require approval. + +**Restriction**: If an administrator of your GitHub organization has restricted access via fine-grained access tokens, you may not be able to use them for Batch Changes. + +**Expiration**: If your organization has configured fine-grained access tokens to have maximum lifetimes, you may need to recreate the token when it has expired. + +**Approval**: If your organization has configured fine-grained access tokens to require approval, you may need to wait for an administrator to approve the token before you can use it with Batch Changes. + +Start by navigating to the form for creating a [new fine-grained access token](https://github.com/settings/personal-access-tokens/new). + +Pick the resource owner that owns the repositories you want to use with Batch Changes. This will most likely be your company's GitHub organization. + +PICTURE + +Scroll down and select "All repositories" so that your token can access all current and future repositories that you have access to. You may restrict it to "Only select repositories", but may have to generate a new token when you want to handle a new repository with Batch Changes. + +PICTURE + +Under "Permissions" click on the arrows on the right-hand side to expand the list for repository and organization permissions. + +PICTURE + +Under "Repository permissions", select the following permissions: +- Commit statuses: Read-only +- Contents: Read and write +- Discussions: Read-only +- Metadata: Read-only +- Pull requests: Read and write +- Workflows: Read and write + +Under "Organization permissions", select the following permissions: +- Custom properties: Read-only + +Once you created the token, copy it and add it to your Batch Changes credentials. + +If your organization requires approval for fine-grained access tokens, you need to wait for an administrator to approve the token. + +PICTURE + +TODO: Rest of text ### GitHub Enterprise @@ -129,7 +187,7 @@ When working with organizations that have SAML SSO (Single Sign On) enabled, con Currently, for customers on an instance of GitHub Enterprise Cloud that uses [SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) and requires SSH certificates to authenticate, we are unable to provide a means of authenticating Batch Changes to your code host. -At present, only classic personal access tokens (PATs) are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps), and fine-grained personal access tokens (PATv2) are not supported. +At present, only classic personal and fine-grained access tokens are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps) are not supported. ### GitLab @@ -239,4 +297,4 @@ To remove a GitHub app from your Sourcegraph instance, navigate back to the same -If you want to delete the GitHub app entirely you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/), and delete it from there. \ No newline at end of file +If you want to delete the GitHub app entirely you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/), and delete it from there. From 80b6720db17fc7de1c905ef89fd011d9c71a5b71 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 12 Mar 2025 15:08:11 +0100 Subject: [PATCH 2/7] remove surplus permissions --- docs/batch-changes/configuring-credentials.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index 478939616..a9053db06 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -149,9 +149,7 @@ Under "Permissions" click on the arrows on the right-hand side to expand the lis PICTURE Under "Repository permissions", select the following permissions: -- Commit statuses: Read-only - Contents: Read and write -- Discussions: Read-only - Metadata: Read-only - Pull requests: Read and write - Workflows: Read and write From b98b56b260db9bf20e4b36d554e2a67e87d3cff7 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Thu, 13 Mar 2025 12:27:18 +0100 Subject: [PATCH 3/7] add pictures --- docs/batch-changes/configuring-credentials.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index a9053db06..9c0594e38 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -138,15 +138,15 @@ Start by navigating to the form for creating a [new fine-grained access token](h Pick the resource owner that owns the repositories you want to use with Batch Changes. This will most likely be your company's GitHub organization. -PICTURE +![Select resource owner for fine-grained access token](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_owner.png) Scroll down and select "All repositories" so that your token can access all current and future repositories that you have access to. You may restrict it to "Only select repositories", but may have to generate a new token when you want to handle a new repository with Batch Changes. -PICTURE +![Select all repositories for repository access](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_repos.png) Under "Permissions" click on the arrows on the right-hand side to expand the list for repository and organization permissions. -PICTURE +![Expand the repository permissions by clicking on the arrows](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_expand_permissions.png) Under "Repository permissions", select the following permissions: - Contents: Read and write @@ -159,11 +159,11 @@ Under "Organization permissions", select the following permissions: Once you created the token, copy it and add it to your Batch Changes credentials. -If your organization requires approval for fine-grained access tokens, you need to wait for an administrator to approve the token. +![Add credential modal with fine-grained token selected](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/setup_fine_grained_access_token.png) -PICTURE +If your organization requires approval for fine-grained access tokens, you need to wait for an administrator to approve the token until you can publish changesets with it. -TODO: Rest of text +The fine-grained access token is now ready to use. Create a new batch change to start using it. ### GitHub Enterprise From eb0087dd83a4451afff0012f7d0e9192dd384407 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 25 Mar 2025 12:46:07 -0700 Subject: [PATCH 4/7] Update docs/batch-changes/configuring-credentials.mdx --- docs/batch-changes/configuring-credentials.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index 9c0594e38..b0c0bef37 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -107,7 +107,7 @@ The `workflow` scope is technically only required if your batch changes modify f When working with organizations that have SAML SSO (Single Sign On) enabled, configuring credentials requires an additional step that [involves white-listing the token for use in that organization](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). -At present, only classic and fine-grained access tokens are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps) are not supported. +Currently, classic and fine-grained access tokens are supported only. Alternative token types like OAuth access tokens (for example, OAuth apps) are not supported. #### Personal Access Token From 3bfa3300f7ace4e75e68b5449210057464b0eef5 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 25 Mar 2025 12:46:16 -0700 Subject: [PATCH 5/7] Update docs/batch-changes/configuring-credentials.mdx --- docs/batch-changes/configuring-credentials.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index b0c0bef37..5cde40c0a 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -295,4 +295,4 @@ To remove a GitHub app from your Sourcegraph instance, navigate back to the same -If you want to delete the GitHub app entirely you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/), and delete it from there. +If you want to delete the GitHub app entirely, you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/) and delete it from there. From 97af1249f50259db0902ba72d67d8dc894398a0f Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 25 Mar 2025 12:46:21 -0700 Subject: [PATCH 6/7] Update docs/batch-changes/configuring-credentials.mdx --- docs/batch-changes/configuring-credentials.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index 5cde40c0a..d5a496f52 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -185,7 +185,7 @@ When working with organizations that have SAML SSO (Single Sign On) enabled, con Currently, for customers on an instance of GitHub Enterprise Cloud that uses [SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) and requires SSH certificates to authenticate, we are unable to provide a means of authenticating Batch Changes to your code host. -At present, only classic personal and fine-grained access tokens are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps) are not supported. +Currently, classic personal and fine-grained access tokens are supported only. Alternative token types like OAuth access tokens (for example, OAuth apps) are not supported. ### GitLab From 7e6a42cb10925f91328ea21bc21348c8e7ab73ed Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 25 Mar 2025 12:50:54 -0700 Subject: [PATCH 7/7] Add feedback --- .../batch-changes/configuring-credentials.mdx | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index d5a496f52..52ec0cd95 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -111,11 +111,12 @@ When working with organizations that have SAML SSO (Single Sign On) enabled, con #### Personal Access Token -Personal access tokens will have access to all repositories that you have access to. +Personal access tokens will have access to all repositories you have access to. [Click here to prefill the form](https://github.com/settings/tokens/new?scopes=repo,read:org,user:email,read:discussion,workflow). Required Scopes: + - `repo` - `read:org` - `user:email` @@ -124,44 +125,44 @@ Required Scopes: #### Fine-Grained Access Token -Fine-grained access tokens allow more granular control of what actions can be performed for a given set of repositories. Most notably, fine-grained access tokens don't grant access by default to all repositories that you have access to. +Fine-grained access tokens allow more granular control of what actions can be performed for a given set of repositories. Most notably, fine-grained access tokens don't grant access by default to all repositories you have access to. In contrast to personal access tokens, fine-grained access tokens for organization resources may be restricted, may have an expiration, and may require approval. -**Restriction**: If an administrator of your GitHub organization has restricted access via fine-grained access tokens, you may not be able to use them for Batch Changes. - -**Expiration**: If your organization has configured fine-grained access tokens to have maximum lifetimes, you may need to recreate the token when it has expired. - -**Approval**: If your organization has configured fine-grained access tokens to require approval, you may need to wait for an administrator to approve the token before you can use it with Batch Changes. +- **Restriction**: If an administrator of your GitHub organization has restricted access via fine-grained access tokens, you may not be able to use them for Batch Changes +- **Expiration**: If your organization has configured fine-grained access tokens to have maximum lifetimes, you may need to recreate the token when it has expired +- **Approval**: If your organization has configured fine-grained access tokens to require approval, you may need to wait for an administrator to approve the token before you can use it with Batch Changes -Start by navigating to the form for creating a [new fine-grained access token](https://github.com/settings/personal-access-tokens/new). +Start by navigating to create a [new fine-grained access token](https://github.com/settings/personal-access-tokens/new). -Pick the resource owner that owns the repositories you want to use with Batch Changes. This will most likely be your company's GitHub organization. +Pick the resource owner that owns the repositories you want to use with Batch Changes. This will likely be your company's GitHub organization. ![Select resource owner for fine-grained access token](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_owner.png) -Scroll down and select "All repositories" so that your token can access all current and future repositories that you have access to. You may restrict it to "Only select repositories", but may have to generate a new token when you want to handle a new repository with Batch Changes. +Scroll down and select "All repositories" so that your token can access all current and future repositories that you have access to. You may restrict it to "Only select repositories", but you may have to generate a new token when you want to handle a new repository with Batch Changes. ![Select all repositories for repository access](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_repos.png) -Under "Permissions" click on the arrows on the right-hand side to expand the list for repository and organization permissions. +Under "Permissions," click on the arrows on the right-hand side to expand the list of repository and organization permissions. ![Expand the repository permissions by clicking on the arrows](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_expand_permissions.png) Under "Repository permissions", select the following permissions: + - Contents: Read and write - Metadata: Read-only - Pull requests: Read and write - Workflows: Read and write Under "Organization permissions", select the following permissions: + - Custom properties: Read-only Once you created the token, copy it and add it to your Batch Changes credentials. ![Add credential modal with fine-grained token selected](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/setup_fine_grained_access_token.png) -If your organization requires approval for fine-grained access tokens, you need to wait for an administrator to approve the token until you can publish changesets with it. +If your organization requires approval for fine-grained access tokens, you must wait for an administrator to approve the token before you can publish changesets with it. The fine-grained access token is now ready to use. Create a new batch change to start using it.