Skip to content

docs(#9448): explain fine-grained PAT via GH_TOKEN in prerequisites - #9450

Open
fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/9448-repo-mgmt-pat-gh-token
Open

fullsend-ai-coder[bot] wants to merge 2 commits into
mainfrom
agent/9448-repo-mgmt-pat-gh-token

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Updates the GitHub prerequisites in docs/guides/getting-started/repo-management.md and docs/guides/getting-started/operations.md to explain how to use a fine-grained PAT. Users who created a PAT and then ran gh auth login in the browser got gh's own OAuth token, and fullsend repos install never used the PAT.

Changes

  • Replaced the gh CLI bullet with a GitHub token bullet in both guides:
    • States the CLI's token resolution order: GH_TOKEN → GITHUB_TOKEN → gh auth token. I checked this against resolveToken / envGitHubToken in internal/cli/github_client.go.
    • Offers both paths: authenticate gh with the OAuth scopes, or create a fine-grained PAT scoped to the target repo(s) and export GH_TOKEN=....
    • Links to Configuring GitHub § Prerequisites, which lists the fine-grained PAT permissions.
    • Recommends export GH_TOKEN over gh auth login --with-token, which would replace the user's stored gh login.
  • operations.md had the same bullet, so I updated it too, as the triage suggested. Its wording uses the singular "target repository" to match that guide's per-repo scope.

Testing

  • pre-commit run could not fetch remote hook repos in the sandbox (TLS verification failed), so I ran the relevant hooks directly. All passed: lint-docs-links, lint-broken-symlinks, lint-md-links (lychee --offline --include-fragments, which also checks the new #prerequisites anchor), whitespace and end-of-file checks, and gitleaks. The other hooks don't apply to Markdown.
  • Tests added/updated: not applicable, docs only.

Checklist

  • PR title follows Conventional Commits (docs, not breaking)
  • Autonomous agent commit, so no DCO sign-off

🤖 Generated with Claude Code


Closes #9448

Post-script verification

  • Branch is not main/master (agent/9448-repo-mgmt-pat-gh-token)
  • Secret scan passed (gitleaks — bc4f5fe240efa31276b22ccc901ee5dabe052c8c..HEAD)
  • PR body secret scan passed (gitleaks — no-git)
  • Final PR description secret scan passed (gitleaks — no-git)

The GitHub prerequisites in repo-management.md and operations.md only
said to authenticate the gh CLI. Users who created a fine-grained PAT
and then ran `gh auth login` in the browser ended up with gh's own
OAuth token, so the CLI never used the PAT they made.

Replace the gh bullet in both guides with a "GitHub token" bullet that
states the CLI's resolution order (GH_TOKEN, then GITHUB_TOKEN, then
`gh auth token`, verified against internal/cli/github_client.go),
offers both the gh OAuth and the fine-grained PAT paths, links to the
PAT permissions in configuring-github.md, and recommends
`export GH_TOKEN` over `gh auth login --with-token`, which would
replace the user's stored gh login.

Note: `pre-commit run` could not fetch remote hook repositories (TLS
verification failed in the sandbox). Ran lint-docs-links,
lint-broken-symlinks, lint-md-links (lychee, with fragments),
whitespace/EOF checks, and gitleaks directly; all passed. Other
remote hooks do not apply to Markdown files.

Closes #9448

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:12 PM UTC · Completed 8:20 PM UTC

Commit: 2ccc45b · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.72

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://99158c6a-site.fullsend-ai.workers.dev

Commit: 2990fab92e3e827f98074b8d2c864e38ba0dd761

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 13, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Documentation-only PR by a bot with minimal diff size and full issue alignment, but elevated to moderate risk due to high churn, multi-author contention, and change coupling in the modified getting-started guide files.

Previous run

Risk Assessment: moderate (2/5)

Details

Documentation-only PR by a bot with minimal diff size and full issue alignment, but elevated to moderate risk due to high churn, multi-author contention, and change coupling in the modified getting-started guide files.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Looks good to me

Earlier findings

  • docs/guides/getting-started/operations.md:14, doc-style, resolved — the bullet is now wrapped with a 2-space hanging indent in the latest push.
  • docs/guides/getting-started/repo-management.md:31, doc-style, resolved — the bullet is now wrapped with a 2-space hanging indent in the latest push.
Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOlt7InNldmVyaXR5IjoibG93IiwiY2F0ZWdvcnkiOiJkb2Mtc3R5bGUiLCJmaWxlIjoiZG9jcy9ndWlkZXMvZ2V0dGluZy1zdGFydGVkL29wZXJhdGlvbnMubWQiLCJpZCI6ImZfOWZkMDEyZGI1MWU0MmRhYyIsImxpbmUiOjE0LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJzdHlsZS1jb252ZW50aW9ucyJ9LHsic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImRvYy1zdHlsZSIsImZpbGUiOiJkb2NzL2d1aWRlcy9nZXR0aW5nLXN0YXJ0ZWQvcmVwby1tYW5hZ2VtZW50Lm1kIiwiaWQiOiJmXzM0YzYwYjg3NmVkYjczMzciLCJsaW5lIjozMSwiYWN0aW9uYWJsZSI6dHJ1ZSwiZGltZW5zaW9uIjoic3R5bGUtY29udmVudGlvbnMifV0sImRpc3Bvc2l0aW9ucyI6W3siaWQiOiJmXzlmZDAxMmRiNTFlNDJkYWMiLCJzdGF0dXMiOiJyZXNvbHZlZF9ieV9jaGFuZ2UifSx7ImlkIjoiZl8zNGM2MGI4NzZlZGI3MzM3Iiwic3RhdHVzIjoicmVzb2x2ZWRfYnlfY2hhbmdlIn1dfQ== -->

Looks good to me

Earlier findings

  • docs/guides/getting-started/operations.md:14, doc-style, resolved — the bullet is now wrapped with a 2-space hanging indent in the latest push.
  • docs/guides/getting-started/repo-management.md:31, doc-style, resolved — the bullet is now wrapped with a 2-space hanging indent in the latest push.
Previous run (2)

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJsb3ciLCJjYXRlZ29yeSI6ImRvYy1zdHlsZSIsImZpbGUiOiJkb2NzL2d1aWRlcy9nZXR0aW5nLXN0YXJ0ZWQvb3BlcmF0aW9ucy5tZCIsImlkIjoiZl85ZmQwMTJkYjUxZTQyZGFjIiwibGluZSI6MTQsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6InN0eWxlLWNvbnZlbnRpb25zIn0seyJzZXZlcml0eSI6ImxvdyIsImNhdGVnb3J5IjoiZG9jLXN0eWxlIiwiZmlsZSI6ImRvY3MvZ3VpZGVzL2dldHRpbmctc3RhcnRlZC9yZXBvLW1hbmFnZW1lbnQubWQiLCJpZCI6ImZfMzRjNjBiODc2ZWRiNzMzNyIsImxpbmUiOjMxLCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJzdHlsZS1jb252ZW50aW9ucyJ9XX0= -->

Review

Findings

Low

  • [doc-style] docs/guides/getting-started/operations.md:14 — The replaced GitHub token bullet is a single ~451-column line. docs/contributing/documentation.md (Line wrapping) requires new or edited Markdown prose to be wrapped at about 80 columns, with list-item continuation lines indented to align with the item text.

    Remediation: Wrap the bullet at ~80 columns with a 2-space hanging indent (link targets that do not fit may stay on their own line).

  • [doc-style] docs/guides/getting-started/repo-management.md:31 — Same issue: the replaced GitHub token bullet is a single ~452-column line, so the wrapping rule applies to this new content too. The neighbouring untouched long bullets do not exempt it. Remediation: Wrap the bullet at ~80 columns with a 2-space hanging indent.


Labels: Docs-only change to getting-started guides.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added documentation component/docs User-facing documentation labels Nov 13, 2026
@fullsend-ai-coder

fullsend-ai-coder Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 8:22 PM UTC · Completed 8:26 PM UTC

Commit: 2ccc45b · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.20

Address review feedback on PR #9450: wrap the replaced GitHub
token bullets in operations.md and repo-management.md per the line
wrapping rule in docs/contributing/documentation.md, using a 2-space
hanging indent. Wording is unchanged.

Note: pre-commit could not fetch hook repositories (TLS failure), so
the applicable hooks (trailing whitespace, EOF, line endings) were
checked manually. make lint-md-links could not run (lychee unavailable
in the sandbox); links are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 Fix agent — iteration 1 (bot-triggered)

Wrapped both replaced GitHub token bullets at about 80 columns per docs/contributing/documentation.md. Pre-commit could not fetch hook repos and lychee link check could not run in the sandbox; whitespace/EOF/line-ending checks were done manually, and link targets are unchanged.

Fixed (2):

  1. GitHub token bullet in operations.md is a single very long line, violating the 80-column wrapping rule (docs/guides/getting-started/operations.md): Wrapped the bullet at about 80 columns with a 2-space hanging indent; wording unchanged, long link targets kept on their own lines.
  2. GitHub token bullet in repo-management.md is a single very long line, violating the 80-column wrapping rule (docs/guides/getting-started/repo-management.md): Wrapped the bullet at about 80 columns with a 2-space hanging indent; wording unchanged, long link targets kept on their own lines.

Tests: passed

CI inspections (6):

  1. CI / test (pending, in_progress): Still running at inspection time; docs-only change is unlikely to affect it.
  2. CI / semgrep (passing, success)
  3. CI / commit-lint (passing, success)
  4. Build Site / build (passing, success)
  5. PR Title Lint (passing, success)
  6. DCO (passing, success)

Conflict update: skipped; strategy none; forge MERGEABLE; target main

Next steps:

  • /fs-review — request a re-review of the changes
  • /fs-fix <your instruction> — run another fix pass with specific guidance
  • Push commits directly — review re-runs automatically on push

Updated by fullsend fix agent

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 8:28 PM UTC · Completed 8:35 PM UTC

Commit: 2990fab · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $0.85

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 13, 2026
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — 2990fab9 Deployed Nov 13, 2026 by github-actions[bot]
dev — 2990fab9 Deployed Nov 13, 2026 by fullsend-ai-coder[bot] via playback #20190
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/docs User-facing documentation documentation ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: repo-management prerequisites should explain using a fine-grained PAT via GH_TOKEN

1 participant