feat: update docs for fine-grained-access tokens (#1025)

Closes SRCH-1751

---------

Co-authored-by: Maedah Batool <[email protected]>

Author: bahrmichael

docs/batch-changes/configuring-credentials.mdx

@@ -101,13 +101,70 @@ 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).
 
-<Callout type="info">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.</Callout>
+<Callout type="info">Currently, classic and fine-grained access tokens are supported only. Alternative token types like OAuth access tokens (for example, OAuth apps) are not supported.</Callout>
+
+#### Personal Access Token
+
+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`
+- `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 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 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 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 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 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 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.
 
 ### GitHub Enterprise
 
@@ -129,7 +186,7 @@ When working with organizations that have SAML SSO (Single Sign On) enabled, con
 
 <Callout type="warning">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.</Callout>
 
-<Callout type="info">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.</Callout>
+<Callout type="info">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.</Callout>
 
 ### GitLab
 
@@ -239,4 +296,4 @@ To remove a GitHub app from your Sourcegraph instance, navigate back to the same
   <source src="https://sourcegraphstatic.com/docs/videos/batch_changes/2024/batches-github-app-delete.mp4" type="video/mp4" />
 </video>
 
-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.