Skip to content

docs(windows): companion app copy and GitHub auth notes#53788

Open
Tianworld wants to merge 4 commits intoopenclaw:mainfrom
Tianworld:docs/windows-github-connectivity
Open

docs(windows): companion app copy and GitHub auth notes#53788
Tianworld wants to merge 4 commits intoopenclaw:mainfrom
Tianworld:docs/windows-github-connectivity

Conversation

@Tianworld
Copy link
Copy Markdown

@Tianworld Tianworld commented Mar 24, 2026

Summary

  • Fix awkward, duplicated wording in the Windows companion app section.
  • Add a short "Git and GitHub connectivity (contributors)" section for Windows: unstable HTTPS to GitHub, failed gh auth login device flow, and authenticating via GH_TOKEN plus gh auth setup-git, with optional read:org refresh.

Why

New contributors on Windows often hit clone/auth timeouts; documenting PAT-based gh auth reduces friction.

Testing

  • pnpm exec oxfmt --write docs/platforms/windows.md

AI-assisted

  • AI-assisted (editing/drafting); I reviewed the diff and tested as noted above
  • Lightly tested (formatting only)
  • I understand what changed and why

@openclaw-barnacle openclaw-barnacle bot added docs Improvements or additions to documentation size: XS labels Mar 24, 2026
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps bot commented Mar 24, 2026

Greptile Summary

This PR makes two documentation updates to docs/platforms/windows.md: it fixes a minor wording duplication in the Windows companion app blurb ("contributions" appeared twice), and adds a new section guiding contributors through GitHub connectivity issues on restricted networks, including how to authenticate with a personal access token when gh auth login fails.

  • The companion app wording fix is clean and correct.
  • The new "Git and GitHub connectivity" section has a logic gap in step 3: gh auth refresh -h github.com -s read:org works only against credentials stored via gh auth login. Since the entire purpose of the section is to work around a failed gh auth login (due to network blocks), no stored OAuth session exists for gh auth refresh to act on. On the same blocked network it would simply attempt the browser/device flow again and time out. The right fix for missing read:org in the PAT flow is to create a new token with the required scope and reassign the environment variable.

Confidence Score: 3/5

  • Safe to merge after correcting the gh auth refresh step in the PAT-based auth flow
  • The companion app wording fix is straightforward. The new connectivity section is helpful, but step 3 gives instructions (gh auth refresh) that won't work in the scenario the section describes — using GH_TOKEN env var precisely because stored credentials don't exist. That's a concrete, fixable accuracy issue that would mislead contributors hitting this edge case.
  • docs/platforms/windows.md — specifically the step 3 gh auth refresh instruction in the new "Git and GitHub connectivity" section
Prompt To Fix All With AI
This is a comment left during a code review.
Path: docs/platforms/windows.md
Line: 262-265

Comment:
**`gh auth refresh` inapplicable in the env-var PAT flow**

Step 3 instructs the user to run `gh auth refresh -h github.com -s read:org`, but `gh auth refresh` operates on credentials stored via `gh auth login` — not on the `GH_TOKEN` environment variable set in step 2. Since the whole reason for using the env-var approach is that `gh auth login` failed due to network issues, there are no stored credentials to refresh, and this command will either fail or attempt to re-initiate the browser/device flow on the same blocked network.

The correct resolution in the PAT flow is to create a new token that already includes the `read:org` scope and reassign the variable — not to call `gh auth refresh`. (`gh auth refresh` is the right command only when the user has gone through `gh auth login` and needs to add scopes to a stored OAuth session, which is exactly the path this section works around.)

How can I resolve this? If you propose a fix, please make it concise.

Reviews (1): Last reviewed commit: "docs(windows): clarify companion app CTA..." | Re-trigger Greptile

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c444c6ec9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@Tianworld
Copy link
Copy Markdown
Author

This PR only changes docs/platforms/windows.md. The failing WhatsApp extension-fast tests appear unrelated to this change. If I don't have permission to re-run CI on this repo, a maintainer could re-run the failed jobs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to documentation size: XS

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant