CLI/SDK/CFN CreateApp with classic PAT yields SSH/legacy OAuth; fine-grained PAT yields GitHub App (TOKEN) — docs should state this

### Before opening, please confirm:

- [x] I have checked to see if my question is addressed in the [FAQ](https://github.com/aws-amplify/amplify-hosting/blob/master/FAQ.md).
- [x] I have [searched for duplicate or closed issues](https://github.com/aws-amplify/amplify-hosting/issues?q=is%3Aissue+).
- [x] I have removed any sensitive information from my code snippets and submission.

### Amplify Hosting feature

Git providers, Documentation, CI/CD (CreateApp / AccessToken)

### Is your feature request related to a problem? Please describe:

When creating an Amplify Hosting app **programmatically** (`aws amplify create-app`, Terraform `aws_amplify_app`, CloudFormation `AWS::Amplify::App`, SDKs) with `--access-token` / `AccessToken`, the resulting Git connection depends on the **GitHub token type**, but the Amplify User Guide does not document this.

Empirically (region `eu-west-3`, org-installed Amplify GitHub App `aws-amplify-eu-west-3`, private GitHub repo, Aug 2026):

| Token used with `CreateApp.AccessToken` | Resulting `repositoryCloneMethod` | Console |
| --- | --- | --- |
| Classic PAT (`ghp_…`), including `repo` + `admin:repo_hook` (and even broader classic scopes) | **`SSH`** (legacy deploy-key / OAuth-style) | Shows **“Migrate to our GitHub App”** |
| GitHub CLI OAuth token (`gho_…` from `gh auth token`) | **`SSH`** | Same migrate banner |
| **Fine-grained PAT** (`github_pat_…`) with repo-scoped Contents:Read, Metadata:Read, Webhooks:Read/write, Administration:Read | **`TOKEN`** (modern Amplify GitHub App) | No migrate banner; branch create + `start-job` BUILD/DEPLOY/VERIFY succeeded |

Same API call shape (`CreateApp` + `accessToken` + `repository`); only the token kind changed.

This matches long-standing community reports that Terraform/CLI create leaves apps on deprecated OAuth until console migrate, e.g. [hashicorp/terraform-provider-aws#25122](https://github.com/hashicorp/terraform-provider-aws/issues/25122) (still open). Comments there already note CLI/CDK/CFN share the same surface and that token scopes affect whether migration is required.

### Current documentation gap

[Setting up the Amplify GitHub App for CloudFormation, CLI, and SDK deployments](https://docs.aws.amazon.com/amplify/latest/userguide/setting-up-GitHub-access.html#setting-up-github-app-cloudformation) currently:

1. Says to generate a **classic** personal access token and select **`admin:repo_hook`** only.
2. States that using `accessToken` deploys an app that uses the **GitHub App** for repo access.
3. Also says existing OAuth-style apps need **console migrate**.

In practice, following that classic-PAT recipe for CLI/Terraform often still produces **`repositoryCloneMethod=SSH`** and the migrate banner — i.e. not the modern GitHub App clone path — while a **fine-grained** PAT produces **`TOKEN`** without console migrate.

AWS docs / API help for `CreateApp` also describe `accessToken` as authorizing via the Amplify GitHub App, which is misleading if classic PATs still land on SSH.

Related: there is **no** CreateApp input for `repositoryCloneMethod` (output-only: `TOKEN` | `SSH` | `SIGV4`). Operators can only verify after create:

```bash
aws amplify get-app --app-id --query 'app.repositoryCloneMethod' --output text
```

### Expected behavior / docs proposal

Please update the Amplify User Guide (and ideally CreateApp API docs) to **explicitly** document:

1. **Token type matters for programmatic creates**
- Prefer / require a **fine-grained** GitHub PAT (`github_pat_…`) for CLI / SDK / CloudFormation / Terraform when targeting the modern GitHub App connection (`repositoryCloneMethod=TOKEN`).
- Classic PATs (`ghp_…`) and GitHub CLI OAuth tokens (`gho_…`) commonly produce the **legacy SSH / deploy-key** path (`repositoryCloneMethod=SSH`) and the console **“Migrate to our GitHub App”** flow — even when `accessToken` (not `oauthToken`) is used.

2. **Recommended fine-grained permissions** (repo-scoped to the Amplify target repo; org resource owner as needed):
- Contents: **Read-only**
- Metadata: **Read-only**
- Webhooks: **Read and write**
- Administration: **Read-only**
- Install regional Amplify GitHub App first (`aws-amplify-`).

3. **Verification step (mandatory in docs)**
After any programmatic create, check:
```bash
aws amplify get-app --app-id --query 'app.repositoryCloneMethod'
```
Expect `TOKEN`. If `SSH`, the app is still on the legacy path (migrate in console, or recreate with a fine-grained PAT).

4. **Clarify classic `admin:repo_hook` guidance**
Either remove “classic PAT + admin:repo_hook only” as the CLI/CFN recipe, or mark it as **insufficient for private repos / legacy SSH risk**, and point to fine-grained PATs for TOKEN.

5. **Optional product ask** (if docs-only is not enough): expose a supported way to request GitHub App / `TOKEN` at create time (or document a supported migrate API), so automation does not depend on undocumented token-type heuristics.

### Steps to Reproduce

1. Install `aws-amplify-` GitHub App on the org; grant the target private repo.
2. Create with classic PAT (`repo` + `admin:repo_hook`):
```bash
aws amplify create-app --name test-classic --repository https://github.com/ORG/REPO \
--access-token "$CLASSIC_PAT" --platform WEB
aws amplify get-app --app-id --query app.repositoryCloneMethod
# observed: SSH
```
3. Delete that app (and any `{appId}:amplify@aws` deploy key).
4. Create with fine-grained PAT (permissions above):
```bash
aws amplify create-app --name test-fg --repository https://github.com/ORG/REPO \
--access-token "$FINE_GRAINED_PAT" --platform WEB
aws amplify get-app --app-id --query app.repositoryCloneMethod
# observed: TOKEN
```
5. Optional: `create-branch` + `start-job --job-type RELEASE` succeeds on the TOKEN app.

### Additional information

- Confirmed with AWS CLI 2.36.x; CreateApp model still only accepts `accessToken` / `oauthToken` (no clone-method input). Changelog-only Amplify change recently was longer `oauthToken` max length — not a new TOKEN create path.
- Terraform registry docs for `aws_amplify_app` still describe PAT → webhook + deploy key; community tracks this as [terraform-provider-aws#25122](https://github.com/hashicorp/terraform-provider-aws/issues/25122).
- The public `awsdocs/aws-amplify-console-user-guide` repo appears archived, so filing the User Guide correction here under Documentation.
- Happy to adjust wording if Amplify’s intended contract differs; the ask is that **docs match observed CreateApp behavior** so teams can automate without surprise console migrates.

### App Id

N/A (repro apps deleted after verification)

### Region

eu-west-3

Start with the linked Amplify User Guide section on GitHub access for CloudFormation, CLI, and SDK deployments, then compare its classic-PAT guidance with the CreateApp API help. Reproduce the two token paths with the provided AWS CLI commands and verify repositoryCloneMethod; done means the documentation explains token types, permissions, verification, and the SSH-versus-TOKEN outcome.

Written by the indexing model from the issue text.