get-gh-aw-release-binary

# Getting the latest `github/gh-aw` release binary Use this skill whenever you need the `gh-aw` compiler binary — for example to recompile agentic workflow `.lock.yml` files (see the [`update-workflow-versions`](../update-workflow-versions/SKILL.md) skill), to reproduce a compiled workflow locally, or to run `gh aw` in CI. `github/gh-aw` publishes two kinds of consumable artifacts on each GitHub Release: - **The `gh` CLI extension** — installed with `gh extension install github/gh-aw` and invoked as `gh aw ...`. This is the normal way to *use* the tool. - **Raw platform binaries** — bare release assets named by GOOS/GOARCH (`linux-amd64`, `darwin-arm64`, …) plus a `checksums.txt`. Use these when you need the executable directly (no `gh`, or a pinned standalone binary). No authentication is required to download from a **public** repository's releases. In this environment TLS is already trusted (system CA bundle), so `curl`, `gh`, and `go` work without extra flags. ## 1. Decide what "latest" means `gh-aw` ships both **stable** releases and **prereleases**. Pick deliberately: - **Latest stable** — the release GitHub marks as *Latest* (never a prerelease). - **Latest overall** — the newest release *or* prerelease by publish date. Resolve the tag (`vX.Y.Z`). Any method works; ignore drafts and rolling refs and only accept tags matching `^v[0-9]`. ```bash # Latest STABLE tag (the GitHub "Latest" release, excludes prereleases): gh release view --repo github/gh-aw --json tagName --jq .tagName # ...or without gh: curl -fsSL https://api.github.com/repos/github/gh-aw/releases/latest \ | grep -m1 '"tag_name"' | cut -d'"' -f4 # Latest OVERALL tag (newest release OR prerelease): gh api repos/github/gh-aw/releases --paginate \ --jq '.[] | select(.draft == false) | select(.tag_name | test("^v[0-9]")) | [.published_at, .tag_name] | @tsv' \ | sort | tail -n1 | cut -f2 ``` Refer to the chosen value below as `<TAG>` (e.g. `v0.83.4`). > [!NOTE] > `/releases/latest` and `gh release view` (no tag) return only the release > flagged **Latest** — i.e. the newest **stable** one. To include prereleases you > must list all releases and sort, as shown above. ## 2a. Install as the `gh` CLI extension (to run `gh aw`) This is the right choice when you want to *run* the compiler. ```bash # Latest available (stable) extension: gh extension install github/gh-aw # Pin to a specific tag (repeat with --force to switch versions): gh extension install github/gh-aw --pin <TAG> --force # Verify: gh aw version # -> "gh aw version <TAG>" # Later, upgrade to the newest published extension: gh extension upgrade gh-aw ``` The compiler baked-in version is what stamps `compiler_version` into generated `.lock.yml` files, so pin the extension to the exact `<TAG>` you intend the locks to track. ## 2b. Download the raw platform binary Use this when you need the executable directly. Release assets are **bare** GOOS/GOARCH names (no `gh-aw-` prefix): | Platform | Asset name | |---------------------|----------------------| | Linux x86_64 | `linux-amd64` | | Linux arm64 | `linux-arm64` | | macOS Intel | `darwin-amd64` | | macOS Apple Silicon | `darwin-arm64` | | Windows x86_64 | `windows-amd64.exe` | | Windows arm64 | `windows-arm64.exe` | Also published: `checksums.txt`, a WASM tarball (`gh-aw-wasm-<TAG>.tar.gz`), and assorted `freebsd-*` / `android-*` builds. Pick the asset for the current machine: ```bash case "$(uname -s)-$(uname -m)" in Linux-x86_64) ASSET=linux-amd64 ;; Linux-aarch64) ASSET=linux-arm64 ;; Darwin-x86_64) ASSET=darwin-amd64 ;; Darwin-arm64) ASSET=darwin-arm64 ;; *) echo "unsupported platform: $(uname -s)-$(uname -m)" >&2; exit 1 ;; esac ``` Download with `gh` (resolves the tag for you) … ```bash gh release download <TAG> --repo github/gh-aw \ --pattern "$ASSET" --pattern checksums.txt --dir /tmp/gh-aw-dl --clobber ``` … or with plain `curl` against the predictable asset URL: ```bash BASE="https://github.com/github/gh-aw/releases/download/<TAG>" mkdir -p /tmp/gh-aw-dl curl -fsSL "$BASE/$ASSET" -o /tmp/gh-aw-dl/"$ASSET" curl -fsSL "$BASE/checksums.txt" -o /tmp/gh-aw-dl/checksums.txt ``` ## 3. Verify the checksum `checksums.txt` has one `sha256␠␠asset-name` line per asset. ```bash cd /tmp/gh-aw-dl # Verify just the asset you downloaded: grep " $ASSET\$" checksums.txt | sha256sum -c - # -> "<asset>: OK" ``` ## 4. Make it executable and use it ```bash install -m 0755 /tmp/gh-aw-dl/"$ASSET" /tmp/gh-aw /tmp/gh-aw version # confirm it matches <TAG> # Example: compile workflows with the pinned binary /tmp/gh-aw compile --action-mode action --action-tag <TAG> --no-check-update \ .github/workflows/<file>.md ``` ## Notes - **Extension vs raw binary** produce the same compiler; use the extension to run `gh aw`, the raw binary when you need a standalone, pinnable executable. - **Don't confuse repos.** This skill is about the **`github/gh-aw`** compiler. The **`threat-detect`** binary this repository ships is released separately from **`github/gh-aw-threat-detection`** (assets `threat-detect-linux-amd64` / `threat-detect-linux-arm64`); the same tag-resolution and checksum steps apply, only the repo and asset names differ. - **Compiler version matters.** Whatever binary you compile with stamps its version into `.lock.yml` (`compiler_version`), which the **gh-aw Version Check** workflow validates — so match `<TAG>` to the version the locks should track.