docs: cwd accuracy, pushTag pitfalls, consumer troubleshooting

[cursor]

Summary

Documentation follow-up after merged PR #13 (action runtime). Fixes outdated user-facing cwd wording and documents publish-time tag/release pitfalls that were easy to miss from code alone.

Does not redo PR #11 (maintainer release runbook) or Pages docs.

Docs added/updated

• docs/troubleshooting.md (new) — consumer pitfall index: empty changesets, publish detection, cwd wiring, tags/Releases, commitMode: github-api, Octokit throttling, permissions.
• README.md / action.yml — cwd no longer claims process.chdir; documents post-fix: use latest ghcommit and fix cwd for git-cli changesets/action#486 pass-through limits. createGithubReleases notes that false skips tag pushes too.
• docs/push-changes-internals.md — new §5 on pushTag (git-cli vs github-api github.context.sha, warning-on-failure, tag name conventions).
• docs/action-runtime.md / docs/auth-and-publishing.md — publish createGithubReleases gating, throttling section, cross-links.

Codepaths covered

• src/index.ts — cwd resolve without chdir; dispatch outputs
• src/run.ts — runPublish tag/release gating and stdout New tag: detection
• src/git.ts — pushTag / setupUser mode differences
• src/octokit.ts — rate-limit retry policy (retryCount <= 2)
• action.yml / README.md — public input descriptions

Knowledge gaps addressed

• README/action.yml still described cwd as changing process.cwd() after fix: use latest ghcommit and fix cwd for git-cli changesets/action#486 removed chdir.
• createGithubReleases: false also skips action-driven pushTag, not only Releases.
• github-api tags always point at github.context.sha; createRef failures only warn.
• No single scan-friendly place for empty-changeset + custom hasChangesets publish gating pitfalls.

Verified against src/index.ts, src/run.ts, src/git.ts, and src/octokit.ts.

  

---

Summary by cubic

Updates docs to clarify cwd wiring (no process.chdir) and how publish-time tags and Releases are gated by createGithubReleases. Adds a troubleshooting guide and details on pushTag behavior (git-cli vs github-api) and @octokit/plugin-throttling.

• Migration
  • Keep .changeset/ at the job working directory; cwd only scopes git and the publish script.
  • If you set createGithubReleases: false, your publish script must create and push tags; github-api tags point at github.context.sha.

^{Written for commit f5f4365. Summary will update on new commits.}

---

Note

Low Risk
Markdown and action input descriptions only; no runtime or workflow behavior changes.

Overview
Documentation-only follow-up: corrects cwd and createGithubReleases in the README and action.yml, and adds engineering docs so behavior matches post-changesets#486 code (no process.chdir).

README.md / action.yml — cwd is described as scoping git and the publish script via path.resolve, not changing process.cwd(); initial changeset read and the version path still use the job working directory. createGithubReleases: false is documented as skipping both action tag pushes and GitHub Releases, not only Releases.

docs/troubleshooting.md (new) — Scan-friendly pitfall index: empty changesets vs hasChangesets, stdout New tag: publish detection, cwd wiring, tags/Releases, commitMode: github-api, Octokit throttling, and permissions.

docs/push-changes-internals.md — New §5 on pushTag: git-cli vs github-api (github.context.sha), tag naming, and createRef failures as warnings.

docs/action-runtime.md / docs/auth-and-publishing.md — Publish gating when createGithubReleases is false, Octokit throttling section, and cross-links to troubleshooting.

^{Reviewed by Cursor Bugbot for commit f5f4365. Configure here.}

[greptile-apps]

PR author is not in the allowed authors list.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_0fa2db6f-ed3e-4c41-8690-499952819261)

[cursor]

Risk: low. Left a non-blocking comment because Cursor Bugbot did not complete successfully (status: skipping / usage limit reached), so this run did not approve. Assigned garlobrian52 for human review; the PR was already merged before this assessment finished.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[Copilot]

Pull request overview

Documentation-only follow-up to align consumer-facing docs with current action runtime behavior, especially around cwd (no process.chdir) and publish-time tag/Release behavior gated by createGithubReleases.

Changes:

• Clarifies cwd behavior in README and action.yml, including the remaining entrypoint paths that still use the job’s process.cwd().
• Adds a new troubleshooting guide consolidating common consumer pitfalls (empty changesets, publish detection, tags/Releases, permissions, throttling).
• Expands internal docs for publish-time tagging (pushTag) and cross-links related docs for easier navigation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Updates user-facing input documentation for cwd and createGithubReleases pitfalls.
action.yml	Updates cwd input description to match runtime behavior (no process.chdir).
docs/troubleshooting.md	New scan-friendly troubleshooting/pitfall index for consumers.
docs/push-changes-internals.md	Adds a dedicated section documenting pushTag behavior and pitfalls.
docs/auth-and-publishing.md	Adds Octokit throttling notes and improves cross-linking to troubleshooting.
docs/action-runtime.md	Adds clarifications/cross-links around publish detection and createGithubReleases gating.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.