diff --git a/README.md b/README.md index 5fd62b1..3663cbc 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. - -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). +for GitHub access. Release binaries do not require Go. -GHA currently publishes alpha releases. 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,8 @@ 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. +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 also work without authentication, subject to lower API rate limits. Private @@ -73,21 +64,69 @@ 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 -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 | | --- | --- | @@ -98,19 +137,27 @@ These examples describe the current source build. Use your installed command's | 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. @@ -132,7 +179,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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 55eb135..602ff74 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" ``` @@ -139,6 +139,30 @@ 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. + +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. Read-only inspection needs only the relevant read permissions; for the full 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..8f8a7cf --- /dev/null +++ b/docs/releases/v0.4.0-beta.1.md @@ -0,0 +1,94 @@ +# v0.4.0-beta.1 + +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. + +## Before you upgrade + +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 + +- **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). +- **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). +- **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). +- **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). +- **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). +- **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). + +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. + +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.