From 499931df33b9c69a96d764e5ed70e64850b0d8d9 Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 14:06:03 +0200 Subject: [PATCH 1/6] docs: prepare v0.4.0-beta.1 release --- README.md | 2 +- docs/getting-started.md | 10 ++-- docs/releases/v0.4.0-beta.1.md | 84 ++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 6 deletions(-) create mode 100644 docs/releases/v0.4.0-beta.1.md diff --git a/README.md b/README.md index 5fd62b1..7ce540a 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ Follow the [setup guide](docs/getting-started.md#install-a-release) to choose your download, verify its checksum, and put `gha` on your PATH. The guide also covers [building from source](docs/getting-started.md#build-from-source). -GHA currently publishes alpha releases. This README describes the current +GHA is in prerelease development. This README describes the current source; an older release may have fewer commands. Run `gha --help` to check your installation, or `gha capabilities --format json` if your build supports it. diff --git a/docs/getting-started.md b/docs/getting-started.md index 55eb135..c27f2c5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -16,7 +16,7 @@ Release binaries do not require Go. Building from source requires Go 1.26.5 or later; Make is optional. Published archives currently cover Linux and macOS, not Windows. -GHA publishes alpha releases. These docs describe the current source, which +GHA publishes prereleases. These docs describe the current source, which may have commands an older binary lacks. Check `gha --help` and, when available, `gha capabilities --format json` for what your installation supports. Build from source if you need features that have not reached a release. @@ -43,7 +43,7 @@ Choose the archive suffix for your machine: Run `uname -m` if you are unsure of the CPU architecture. `x86_64` means `amd64`; `aarch64` or `arm64` means `arm64`. -The commands below use the published `0.3.0-alpha` Linux x86-64 archive as an +The commands below use the published `0.4.0-beta.1` Linux x86-64 archive as an example. Substitute the exact filename you downloaded throughout. Release archives contain a `gha` executable, README, and license; they do not install coding-agent guidance automatically. @@ -62,11 +62,11 @@ Stop if its checksum fails. On macOS, select the line for your exact archive and check it: ```sh -grep ' gha_0.3.0-alpha_darwin_arm64.tar.gz$' checksums.txt > selected-checksum.txt +grep ' gha_0.4.0-beta.1_darwin_arm64.tar.gz$' checksums.txt > selected-checksum.txt shasum -a 256 --check selected-checksum.txt ``` -Expect `gha_0.3.0-alpha_darwin_arm64.tar.gz: OK`. Use the `darwin_amd64` filename +Expect `gha_0.4.0-beta.1_darwin_arm64.tar.gz: OK`. Use the `darwin_amd64` filename for an Intel Mac. An empty selection is not a successful check. This verifies the download against the release's checksum file. @@ -76,7 +76,7 @@ Extract the verified archive and copy the executable into `~/.local/bin`. On Linux x86-64, for example: ```sh -tar -xzf gha_0.3.0-alpha_linux_amd64.tar.gz +tar -xzf gha_0.4.0-beta.1_linux_amd64.tar.gz mkdir -p "$HOME/.local/bin" install -m 755 gha "$HOME/.local/bin/gha" ``` diff --git a/docs/releases/v0.4.0-beta.1.md b/docs/releases/v0.4.0-beta.1.md new file mode 100644 index 0000000..07b7df7 --- /dev/null +++ b/docs/releases/v0.4.0-beta.1.md @@ -0,0 +1,84 @@ +# v0.4.0-beta.1 + +GHA's first beta brings isolated PR worktrees, clearer outcomes when a mutation +partly fails, broader coding-agent setup, and package-manager installation. +The core workflows are ready for wider testing. This remains a prerelease: +please report unexpected behavior with the output of `gha version --format json`. + +## Installation and upgrades + +- On macOS, install with `brew install --cask raithlin/tap/gha`, or run + `brew update` followed by `brew upgrade --cask gha` for an existing install. + The release workflow now maintains the [Homebrew tap](https://github.com/Raithlin/homebrew-tap). +- Debian/Ubuntu, Fedora, and Arch packages join the macOS/Linux archives for + amd64 and arm64. Verify the downloaded package against this release's + `checksums.txt` before installation. Native package managers own executable + upgrades; these are downloadable packages, not hosted apt/dnf/pacman repositories. +- See the [setup guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/getting-started.md) + and [distribution guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/package-distribution.md) + for installation, authentication, checksum verification, and upgrade instructions. + macOS binaries are not Developer ID signed or notarized. + +## Changes + +- **Isolated PR work:** inspect, add, and safely remove Git worktrees. Use + `gha pr checkout --worktree ` to check out or resume an existing + PR with an explicit fork-aware push destination. `gha pr retire` explains + whether a closed PR's checkout can be removed and preserves dirty, unpublished, + locked, or uncertain work. [#23](https://github.com/Raithlin/gha/pull/23), + [#26](https://github.com/Raithlin/gha/pull/26). +- **Safer mutations and useful failure results:** branch operations check the + actual origin write target and local operation state. Partial failures retain + completed effects in structured output, and origin branch renames use atomic + pushes. [#21](https://github.com/Raithlin/gha/pull/21), + [#24](https://github.com/Raithlin/gha/pull/24), + [#25](https://github.com/Raithlin/gha/pull/25). +- **More coding-agent harnesses:** guidance setup supports Codex, Claude Code, + Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw. + Installation detects configured harnesses without requiring their executables; + use `--agent` for explicit selection. Compact default guidance keeps the + detailed skill available when needed. [#14](https://github.com/Raithlin/gha/pull/14), + [#19](https://github.com/Raithlin/gha/pull/19), + [#20](https://github.com/Raithlin/gha/pull/20), + [#22](https://github.com/Raithlin/gha/pull/22). +- **Compatible guidance updates:** `gha update` refreshes recorded agent + installations while checking skill requirements against the installed binary. + Incompatible or customized skills are preserved. The command does not upgrade + the executable. [#18](https://github.com/Raithlin/gha/pull/18), + [#19](https://github.com/Raithlin/gha/pull/19). +- **Authentication and PR preparation:** GHA can reuse `gh` authentication when + `GHA_GITHUB_TOKEN` is unset. `gha pr prepare` drafts descriptions from local + commits without fetching or creating a PR. [#15](https://github.com/Raithlin/gha/pull/15), + [#17](https://github.com/Raithlin/gha/pull/17). +- **Release readiness and diagnostics:** CI evaluation accounts for exact-commit + workflow attempts, required checks, and supported skipped/neutral outcomes. + Build identity, unpublished release branches, and pruned upstreams have clearer + results. Reviewed release notes and guarded tag publication are part of the + release workflow. [#12](https://github.com/Raithlin/gha/pull/12), + [#13](https://github.com/Raithlin/gha/pull/13), + [#26](https://github.com/Raithlin/gha/pull/26), + [#28](https://github.com/Raithlin/gha/pull/28). +- **Distribution and first use:** automated native install/upgrade tests now + cover Debian, Fedora, Arch, Intel Mac, and Apple Silicon, including checksum + rejection and guidance preservation. The README and setup guide explain a + complete first-use path. [#31](https://github.com/Raithlin/gha/pull/31), + [#32](https://github.com/Raithlin/gha/pull/32). + +## Migration from v0.3.0-alpha + +Mutating commands now **execute by default** after their safety checks. Use +`--dry-run` to preview changes; the old confirmation-flag workflow has been +removed. Review existing scripts before upgrading, particularly any that relied +on a default invocation being a preview. Explicit targets and preflight safety +checks remain. [#16](https://github.com/Raithlin/gha/pull/16). + +Upgrade the executable through its package manager or release archive first. +Then use `gha update --dry-run` to inspect guidance updates and `gha update` +to apply compatible updates. Agent setup is separate from package installation. +Use `gha capabilities --format json` to discover this binary's command contracts. + +Release-status/wait and downloaded-asset verification workflows remain planned; +this beta does not add those commands. Check the GitHub Actions run, published +release, and downloaded assets to verify a publication completed. + +Contributor: @Raithlin. From 27eea94035099e5f5760a74bb4ede69a3b7d9740 Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 21:48:10 +0200 Subject: [PATCH 2/6] docs: simplify beta release notes --- docs/releases/v0.4.0-beta.1.md | 134 ++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 62 deletions(-) diff --git a/docs/releases/v0.4.0-beta.1.md b/docs/releases/v0.4.0-beta.1.md index 07b7df7..8f8a7cf 100644 --- a/docs/releases/v0.4.0-beta.1.md +++ b/docs/releases/v0.4.0-beta.1.md @@ -1,84 +1,94 @@ # v0.4.0-beta.1 -GHA's first beta brings isolated PR worktrees, clearer outcomes when a mutation -partly fails, broader coding-agent setup, and package-manager installation. -The core workflows are ready for wider testing. This remains a prerelease: -please report unexpected behavior with the output of `gha version --format json`. +This first beta adds PR worktrees, supports more coding agents, and adds +Homebrew and native Linux packages. If you find a problem, include the output +of `gha version --format json` in your report. -## Installation and upgrades +## Before you upgrade -- On macOS, install with `brew install --cask raithlin/tap/gha`, or run - `brew update` followed by `brew upgrade --cask gha` for an existing install. - The release workflow now maintains the [Homebrew tap](https://github.com/Raithlin/homebrew-tap). -- Debian/Ubuntu, Fedora, and Arch packages join the macOS/Linux archives for - amd64 and arm64. Verify the downloaded package against this release's - `checksums.txt` before installation. Native package managers own executable - upgrades; these are downloadable packages, not hosted apt/dnf/pacman repositories. -- See the [setup guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/getting-started.md) - and [distribution guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/package-distribution.md) - for installation, authentication, checksum verification, and upgrade instructions. - macOS binaries are not Developer ID signed or notarized. +Commands that change local or GitHub state now **execute by default** after +their safety checks. Use `--dry-run` to preview changes. We removed the old +confirmation flag. Check scripts that rely on commands running as previews. +Explicit targets and safety checks still apply. +[#16](https://github.com/Raithlin/gha/pull/16). + +Upgrade the executable through its package manager or release archive first. +Then run `gha update --dry-run` to preview agent guidance changes and +`gha update` to apply compatible changes. This command updates guidance only. + +## Install or upgrade + +On macOS, run `brew install --cask raithlin/tap/gha`. To upgrade, run +`brew update`, then `brew upgrade --cask gha`. The release workflow updates +the [Homebrew tap](https://github.com/Raithlin/homebrew-tap) automatically. + +Linux users can download Debian/Ubuntu, Fedora, or Arch packages. Linux and +macOS archives remain available for amd64 and arm64. Verify downloads against +this release's `checksums.txt`. To upgrade a Linux package, download the new +version and install it with your package manager. GHA does not host apt, dnf, +or pacman repositories. + +After you install, run `gha version --format json`. Its `version` field should +read `0.4.0-beta.1`. Run `gha agent install` to set up agent guidance separately. + +See the [setup guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/getting-started.md) +and [distribution guide](https://github.com/Raithlin/gha/blob/v0.4.0-beta.1/docs/package-distribution.md) +for instructions. The macOS binaries are not signed with an Apple Developer ID +or notarized. [#31](https://github.com/Raithlin/gha/pull/31), +[#32](https://github.com/Raithlin/gha/pull/32). ## Changes -- **Isolated PR work:** inspect, add, and safely remove Git worktrees. Use - `gha pr checkout --worktree ` to check out or resume an existing - PR with an explicit fork-aware push destination. `gha pr retire` explains - whether a closed PR's checkout can be removed and preserves dirty, unpublished, - locked, or uncertain work. [#23](https://github.com/Raithlin/gha/pull/23), +- **Work on PRs in separate checkouts.** Use `gha pr checkout --worktree ` + to check out or resume a PR. GHA reports where to push changes, including + PRs from forks. `gha pr retire` removes eligible checkouts for closed or + merged PRs. It preserves local edits, unpublished commits, locked checkouts, + and work whose safety it cannot establish. You can also list, add, and remove + worktrees directly. [#23](https://github.com/Raithlin/gha/pull/23), [#26](https://github.com/Raithlin/gha/pull/26). -- **Safer mutations and useful failure results:** branch operations check the - actual origin write target and local operation state. Partial failures retain - completed effects in structured output, and origin branch renames use atomic - pushes. [#21](https://github.com/Raithlin/gha/pull/21), +- **See which branch changes completed.** Branch commands check where Git will + push and whether another Git operation is in progress. If a command partly + fails, its JSON output records the changes that completed. On origin, a + rename updates both branch names together or leaves both unchanged. + [#21](https://github.com/Raithlin/gha/pull/21), [#24](https://github.com/Raithlin/gha/pull/24), [#25](https://github.com/Raithlin/gha/pull/25). -- **More coding-agent harnesses:** guidance setup supports Codex, Claude Code, - Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw. - Installation detects configured harnesses without requiring their executables; - use `--agent` for explicit selection. Compact default guidance keeps the - detailed skill available when needed. [#14](https://github.com/Raithlin/gha/pull/14), +- **Set up more coding agents.** GHA supports Codex, Claude Code, Pi, OpenCode, + GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw. The installer + detects agents you have set up without requiring their executables. Use + `--agent` to select them explicitly. Shorter default guidance keeps the + detailed skill available when needed. + [#14](https://github.com/Raithlin/gha/pull/14), [#19](https://github.com/Raithlin/gha/pull/19), [#20](https://github.com/Raithlin/gha/pull/20), [#22](https://github.com/Raithlin/gha/pull/22). -- **Compatible guidance updates:** `gha update` refreshes recorded agent - installations while checking skill requirements against the installed binary. - Incompatible or customized skills are preserved. The command does not upgrade - the executable. [#18](https://github.com/Raithlin/gha/pull/18), +- **Keep guidance compatible with your binary.** `gha update` checks that your + binary supports the commands a skill requires. It preserves skills you + customized and rejects updates your binary cannot support. + [#18](https://github.com/Raithlin/gha/pull/18), [#19](https://github.com/Raithlin/gha/pull/19). -- **Authentication and PR preparation:** GHA can reuse `gh` authentication when - `GHA_GITHUB_TOKEN` is unset. `gha pr prepare` drafts descriptions from local - commits without fetching or creating a PR. [#15](https://github.com/Raithlin/gha/pull/15), +- **Reuse your GitHub login and draft PR descriptions.** GHA can reuse your `gh` + login when `GHA_GITHUB_TOKEN` is unset. `gha pr prepare` drafts a description + from local commits without fetching or creating a PR. + [#15](https://github.com/Raithlin/gha/pull/15), [#17](https://github.com/Raithlin/gha/pull/17). -- **Release readiness and diagnostics:** CI evaluation accounts for exact-commit - workflow attempts, required checks, and supported skipped/neutral outcomes. - Build identity, unpublished release branches, and pruned upstreams have clearer - results. Reviewed release notes and guarded tag publication are part of the - release workflow. [#12](https://github.com/Raithlin/gha/pull/12), +- **Check release readiness with better diagnostics.** Release checks use CI + results for the selected commit and account for workflow retries. They accept + skipped or neutral jobs alongside successful validation. GHA also reports + build details and explains problems with unpublished branches or deleted + upstream branches. Release publication checks the target and requires reviewed + notes when the workflow requests them. + [#12](https://github.com/Raithlin/gha/pull/12), [#13](https://github.com/Raithlin/gha/pull/13), [#26](https://github.com/Raithlin/gha/pull/26), [#28](https://github.com/Raithlin/gha/pull/28). -- **Distribution and first use:** automated native install/upgrade tests now - cover Debian, Fedora, Arch, Intel Mac, and Apple Silicon, including checksum - rejection and guidance preservation. The README and setup guide explain a - complete first-use path. [#31](https://github.com/Raithlin/gha/pull/31), - [#32](https://github.com/Raithlin/gha/pull/32). - -## Migration from v0.3.0-alpha -Mutating commands now **execute by default** after their safety checks. Use -`--dry-run` to preview changes; the old confirmation-flag workflow has been -removed. Review existing scripts before upgrading, particularly any that relied -on a default invocation being a preview. Explicit targets and preflight safety -checks remain. [#16](https://github.com/Raithlin/gha/pull/16). - -Upgrade the executable through its package manager or release archive first. -Then use `gha update --dry-run` to inspect guidance updates and `gha update` -to apply compatible updates. Agent setup is separate from package installation. -Use `gha capabilities --format json` to discover this binary's command contracts. +Install and upgrade tests cover Debian, Fedora, Arch, Intel Mac, and Apple +Silicon. They check that package operations preserve customized guidance and +that Homebrew rejects a download with the wrong checksum. -Release-status/wait and downloaded-asset verification workflows remain planned; -this beta does not add those commands. Check the GitHub Actions run, published -release, and downloaded assets to verify a publication completed. +Commands to wait for a release or verify downloaded assets remain planned. +To verify a release, check its GitHub Actions run, published release, and +downloads. Use `gha capabilities --format json` to list available commands. Contributor: @Raithlin. From ddad14d4476ae6b39beaf65f53954410a3c49b47 Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 21:54:45 +0200 Subject: [PATCH 3/6] docs: address the README to new GHA users --- README.md | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 7ce540a..f6af412 100644 --- a/README.md +++ b/README.md @@ -20,32 +20,26 @@ terminal or add `--format json` for scripts and agents. It works alongside ## Install -On macOS, install the released binary through Homebrew: +On macOS, install GHA through Homebrew: ```sh brew install --cask raithlin/tap/gha ``` -See [package installation and upgrades](docs/package-distribution.md) for -integrity checks, upgrades, native Linux packages, and the release-maintained -tap. Native Linux packages become available with the first release containing -the packaging configuration; earlier releases provide archives. +On Linux, download a Debian/Ubuntu, Fedora, or Arch package from +[GitHub Releases](https://github.com/Raithlin/gha/releases). Linux and macOS +archives are also available for amd64 and arm64. + +Follow the [package installation guide](docs/package-distribution.md) to verify +your download, install a package, or upgrade GHA. For manual archive installation +or building from source, follow the [setup guide](docs/getting-started.md). -You can also download a Linux or macOS archive from -[GitHub Releases](https://github.com/Raithlin/gha/releases). Install Git for local repository workflows and pushes. The [GitHub CLI (`gh`)](https://cli.github.com/) is optional; GHA can reuse its login -for GitHub access. - -You do not need Go to use a release binary. +for GitHub access. Release binaries do not require Go. -Follow the [setup guide](docs/getting-started.md#install-a-release) to choose -your download, verify its checksum, and put `gha` on your PATH. The guide also -covers [building from source](docs/getting-started.md#build-from-source). - -GHA is in prerelease development. This README describes the current -source; an older release may have fewer commands. Run `gha --help` to check -your installation, or `gha capabilities --format json` if your build supports it. +GHA is prerelease software. Review the +[release notes](https://github.com/Raithlin/gha/releases) before upgrading. ## First use @@ -55,11 +49,7 @@ If you use the GitHub CLI, sign in if you have not already: gh auth login ``` -GHA chooses GitHub credentials in this order: - -1. Use `GHA_GITHUB_TOKEN` if set, without invoking `gh`. -2. Otherwise, try `gh auth token` to reuse your GitHub CLI login. -3. If `gh` is missing or cannot supply a token, continue without authentication. +GHA reuses your `gh` login. To use a token instead, set `GHA_GITHUB_TOKEN`. Local inspection works without GitHub credentials. Public GitHub requests can also work without authentication, subject to lower API rate limits. Private @@ -86,8 +76,7 @@ signals appear as unavailable. ## Common workflows -These examples describe the current source build. Use your installed command's -`--help` to check its options. +Run `gha --help` for command options. | What you want to do | Command | | --- | --- | @@ -132,7 +121,7 @@ gha agent install GHA supports Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw. Use `--agent codex,claude` to select agents -explicitly. Existing releases may support fewer agents. +explicitly. See the [agent setup guide](docs/getting-started.md#set-up-a-coding-agent) for selection, installed-file checks, and removal. Agent setup is optional for From 3533136b85e41f4cccaf8dba45bbbb6b5c058347 Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 21:58:21 +0200 Subject: [PATCH 4/6] docs: show optional token export from GitHub CLI --- docs/getting-started.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index c27f2c5..8bc75a3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -139,6 +139,16 @@ The status should identify the GitHub account you intend to use. GHA uses public API requests remain unauthenticated and have lower rate limits. Local commands such as `gha analyze` work without GitHub credentials. +You can also set the variable explicitly from your active `gh` account: + +```sh +export GHA_GITHUB_TOKEN="$(gh auth token)" +``` + +This sets the token for the current shell and commands you run from it. The +command prints no token. This step is optional because GHA already tries +`gh auth token` when the variable is unset. + If you do not use `gh`, supply a fine-grained token through `GHA_GITHUB_TOKEN` using your shell or secret manager. Restrict it to the repositories GHA needs. Read-only inspection needs only the relevant read permissions; for the full From 15bc6bfe4c4ac7c78dbcd41694b76f371790fda6 Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 22:00:56 +0200 Subject: [PATCH 5/6] docs: explain how to persist the optional GitHub token export --- docs/getting-started.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 8bc75a3..602ff74 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -146,8 +146,22 @@ export GHA_GITHUB_TOKEN="$(gh auth token)" ``` This sets the token for the current shell and commands you run from it. The -command prints no token. This step is optional because GHA already tries -`gh auth token` when the variable is unset. +command prints no token. + +To set it in future terminals, add the same line to your shell's startup file: + +| Shell | File | +| --- | --- | +| Bash on Linux | `~/.bashrc` | +| Bash on macOS | `~/.bash_profile` | +| Zsh | `~/.zshrc` | + +Open the file in a text editor, add the line, and save it. Then open a new +terminal. Keep `$(gh auth token)` as written so each new shell retrieves the +token for your active `gh` account. + +This setup is optional because GHA already tries `gh auth token` when the +variable is unset. If you do not use `gh`, supply a fine-grained token through `GHA_GITHUB_TOKEN` using your shell or secret manager. Restrict it to the repositories GHA needs. From 89f6d3ec9ed1a8c367ae03bfb58df5acbf5fddbf Mon Sep 17 00:00:00 2001 From: Stephen Metcalfe Date: Wed, 28 Oct 2026 22:08:43 +0200 Subject: [PATCH 6/6] docs: show expected GHA output in the README --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 67 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f6af412..3663cbc 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,7 @@ If you use the GitHub CLI, sign in if you have not already: gh auth login ``` +Follow the prompts to sign in with the GitHub account you want to use. GHA reuses your `gh` login. To use a token instead, set `GHA_GITHUB_TOKEN`. Local inspection works without GitHub credentials. Public GitHub requests can @@ -63,16 +64,65 @@ Open a terminal in a GitHub checkout and start with: gha prs --limit 10 ``` -This lists up to ten open pull requests. Pick a number from the list and -inspect it, replacing `123` with that number: +This lists up to ten open pull requests. For example: + +```text +Pull Requests (1 returned): + +#42 Fix login redirect [open] by alex +``` + +The examples here use an illustrative PR. Your repository's numbers, titles, +and results will differ. Pick a number from the list and inspect it: ```sh -gha review 123 +gha review 42 ``` The review summary shows CI and merge readiness, outstanding reviews and -threads, risk signals, and recommended next actions. Missing or unsupported -signals appear as unavailable. +threads, risk signals, and recommended next actions. An excerpt might look like: + +```text +Review readiness: + Mergeable: true + CI: failure + Review threads: none + +Risk signals: + [high] ci_failure: one or more CI checks have failed + +Recommended next actions: + fix_ci: one or more CI checks have failed +``` + +Here, GitHub can combine the branches, but CI has failed. Check the failing +jobs before proceeding. Missing or unsupported signals appear as unavailable. + +For an agent or script, request the same review as JSON: + +```sh +gha review 42 --format json +``` + +JSON excerpt for the same PR: + +```json +{ + "schema_version": "v1", + "readiness": { + "mergeable": true, + "mergeable_state": "blocked", + "ci_status": "failure", + "review_threads_state": "none" + }, + "recommended_actions": [ + { + "action": "fix_ci", + "reason": "one or more CI checks have failed" + } + ] +} +``` ## Common workflows @@ -87,19 +137,27 @@ Run `gha --help` for command options. | List local worktrees | `gha worktrees` | | Analyze repository history, storage, and large files | `gha analyze` | | List recent published releases | `gha releases --limit 10` | -| Get a structured review for an agent or script | `gha review 123 --format json` | +| Get a structured review for an agent or script | `gha review 42 --format json` | Local branch information uses cached Git refs unless you explicitly request a refresh. Cleanup inspection lists candidates; it does not delete them. Commands that change state execute by default. Preview their effects with -`--dry-run` first. For example, for an existing local branch: +`--dry-run` first. To preview creating a local branch: ```sh -gha branch publish feature/reviews --dry-run +gha branch create feature/reviews --dry-run +``` + +```text +Branch mutation: create feature/reviews +Dry run: no changes were made. +Local: planned +Origin: not_requested ``` -The preview shows the publication target and safety checks without pushing. +`Local: planned` shows the intended change. `Origin: not_requested` means this +operation targets only the local repository. The dry run creates no branch. See the [command guide](docs/command-guide.md) for the full workflows, or the [PR worktree guide](docs/pr-worktree-lifecycle.md) to work on a PR in an isolated checkout and safely retire it afterward.