Support Fine-grained Personal Access Tokens (PATs) in GEI to enable least-privilege CLI migrations

Start with the referenced GithubApi.cs, ArchiveUploader.cs, and the linked issues about token support to map which migration APIs reject GitHub App installation tokens and fine-grained PATs. The request spans GraphQL mutations, the REST export API, and archive storage, and proposes alternative migration workflows; completion would require agreeing on scope and delivering compatible support or documented fallback paths.

Description

1. Background & Scope (Distinction from #1420)

Currently, GitHub Enterprise Importer (GEI) strictly requires Personal Access Tokens (classic) with broad scopes (repo, admin:org, workflow) and does not support Fine-grained PATs (Official Documentation).

While #1420 requests support for GitHub App installation tokens for long-lived automated pipelines, this issue specifically focuses on why Fine-grained PAT support is essential for GEI.

---

2. Concrete Scenarios Where Classic PATs Are Problematic

A structural flaw of Classic PATs is that they cannot be scoped to a specific resource owner (organization) or repository—they grant repo and admin:org permissions across every organization and private repository the user can access (Official Documentation).

This creates severe security blockers in the following scenarios:

1. Migrating only a specific organization or a subset of repositories
   If an engineer belongs to multiple organizations (e.g., Production Org A, Department Org B, and Migration Target Org C), issuing a Classic PAT just to migrate a single repository in Org C produces a token that can read, write, and modify settings across all repositories in unrelated Orgs A and B (maximizing the blast radius if leaked).
2. Delegating migration work via the Migrator role
   GEI provides a Migrator role to delegate migrations to non-owner engineers or external migration partners. However, requiring the migrator to generate a Classic PAT means their token inevitably includes access to unrelated private repositories and organizations they happen to belong to.
3. Conflict with the "Restrict personal access tokens (classic)" policy
   As explicitly stated in the GEI documentation, "You cannot use GitHub Enterprise Importer if your organization uses the 'Restrict personal access tokens (classic) from accessing your organizations' policy." Organizations enforcing this policy are forced to either weaken their security posture by allowing over-privileged Classic PATs or abandon using GEI altogether.

---

3. Why Fine-grained PATs Are Needed Instead of GitHub Apps (#1420)

1. GEI is used for short-lived migration scripts, where GitHub's own guidelines recommend Fine-grained PATs over GitHub Apps

   • According to GitHub's official documentation (Choosing between a GitHub App or a personal access token), GitHub Apps are intended for long-lived integrations, whereas Personal Access Tokens (specifically Fine-grained PATs whenever possible) are recommended for short-lived scripts.
   • For GEI's standard CLI workflow—generating a one-off migrate.ps1 script via generate-script and running it—registering a new GitHub App, managing private keys (PEM), and implementing JWT signing is excessive overhead. Fine-grained PATs preserve the existing CLI experience (GH_PAT / GH_SOURCE_PAT environment variables) with zero additional setup.

2. Combining GEI's Migrator role with GitHub's default Fine-grained PAT approval flow

   • GEI provides the Migrator role so organization owners can delegate migrations to individual users or teams. However, installing a GitHub App requires Organization Owner privileges, and the grantMigratorRole API only accepts USER or TEAM as the actorType. Therefore, a delegated migrator cannot self-provision or use a GitHub App.
   • By contrast, since Fine-grained PATs became GA in March 2025, both Fine-grained PATs and the Organization Owner approval flow are enabled by default for all organizations. This allows a user with the Migrator role to request a Fine-grained PAT scoped strictly to the target organization/repositories with least-privilege permissions (such as the repository_creation:write permission added on October 13, 2026), and run the CLI migration safely once approved by an Organization Owner.

---

4. Related Issues & Community Feedback

The limitation of only accepting Classic PATs and legacy OAuth scopes has been raised repeatedly by users:

• #1283 (Open): Only classic PATs are accepted as authentication
• GitHub Community Discussion #162365: Fine-grained personal access token doesn't work
• #708 (Closed) / #1229 (Closed) / Discussion #1120: createMigrationSource failing with FORBIDDEN due to strict Classic PAT scope requirements (['read:org', 'repo'] / admin:org)
• #20 (Open) / #1001 (Open): Discussions on validating PATs via legacy X-OAuth-Scopes headers
• (Reference: Related requests/reports regarding GitHub App tokens: #1420 (Open), #1260 (Closed), #867 comment)

---

5. Technical Bottlenecks (①–③) and Proposed Solutions / Fallback Options

An inspection of the gh-gei codebase (GithubClient.cs, GithubApi.cs, ArchiveUploader.cs) and GitHub's API compatibility tables shows that the CLI itself merely passes the token as Authorization: Bearer <token>. Fine-grained PATs are blocked by three specific backend API bottlenecks:

Bottleneck API	Why Fine-grained PATs Are Currently Blocked	Affected Migration Sources	Proposed Fix & Security-First Workaround / Compromise
① Source Export API REST POST /orgs/{org}/migrations	/orgs/{org}/migrations is not included in the Endpoints available for fine-grained personal access tokens.	GHES / GHE.com only (Note: GitLab gl2gh, Bitbucket bbs2gh, and ADO ado2gh use their own native export APIs and do not call ①)	[Fundamental Fix] Add Fine-grained PAT support (GH_SOURCE_PAT) to /orgs/{org}/migrations. [Workaround] Instead of the Migration API, read repository settings/metadata temporarily via standard REST/GraphQL APIs (already Fine-grained PAT compatible, similar to migrate-code-scanning-alerts).
② Target Import API GraphQL createMigrationSource startRepositoryMigration startOrganizationMigration	[Primary Blocker] The backend enforces legacy OAuth scope string checks (['read:org', 'repo']) and passes githubPat / accessToken directly to async backend workers.	All Migration Sources (GitHub, GitLab, ADO, Bitbucket are all blocked here)	[Fundamental Fix] Update the GraphQL mutations and async backend workers to accept Fine-grained PATs and fine-grained permissions (e.g., repository_creation:write). [Compromise / Fallback Mode] See details below.
③ Archive Upload API uploads.github.com/organizations/{id}/gei/archive	Internal GEI endpoint with no Fine-grained PAT permission mapping.	When using --use-github-storage (GHES, GitLab, Bitbucket)	[Fundamental Fix] Allow Fine-grained PATs (GH_PAT) on this endpoint. [Workaround Available Today] Bypass GitHub Owned Storage (③) by using --aws-bucket-name (S3) or --azure-storage-connection-string (Azure Blob) to pass pre-signed URLs.

Details on Compromise / Fallback Mode for ② (Prioritizing Security Over Metadata Fidelity)

If updating the ② backend GraphQL mutations takes time, organizations that ban Classic PATs would benefit from a fallback mode (or official guidance) that trades mannequin attribution and original issue/PR timestamps for 100% Fine-grained PAT compatibility using standard APIs:

1. Repository Creation & Git Push: Create the repository via POST /orgs/{org}/repos (supported by Fine-grained PATs with the new repository_creation:write permission) and run git push --mirror + git lfs push --all (preserving 100% of commit history and authors).
2. Settings Backup & Restore: Read and recreate branch protections, rulesets, team permissions, autolinks, and code/secret scanning alerts via standard REST APIs (all compatible with Fine-grained PATs).
3. Issue & PR Recreation: Recreate issues, labels, milestones, and PRs via standard REST APIs (POST /repos/{owner}/{repo}/issues, /pulls) using the Fine-grained PAT, embedding the original author and timestamp metadata into the body text.

---

6. Request

1. Primary Request (Backend Fine-grained PAT Support):
   Please update the authorization checks on ② GraphQL (createMigrationSource, startRepositoryMigration), ① REST (/orgs/{org}/migrations), and ③ GitHub Owned Storage (uploads.github.com) to accept Fine-grained PATs (GH_SOURCE_PAT and GH_PAT) and fine-grained permissions such as repository_creation:write.
2. Roadmap Sharing:
   As stated in the March 2025 Fine-grained PAT GA announcement, GitHub's goal is "enabling organizations to eventually disable the use of PATs (Classic) for their resources." Could the team share whether Fine-grained PAT support for GEI is on the roadmap?