update-workflow-versions

# Updating Agentic Workflow Versions Use this skill when the **gh-aw Version Check** workflow (`.github/workflows/gh-aw-version-check.yml`) opens a *"Workflow version drift"* issue, or whenever you need to bump the versions the compiled workflow `.lock.yml` files are pinned to. There is no automation for the regeneration itself — it is a deliberate, human-reviewed step. Pushing changes under `.github/workflows/` requires a token with the `workflows` permission, which the built-in `GITHUB_TOKEN` lacks, so a maintainer (or an agent with suitably-permissioned credentials) performs the recompile locally and opens a PR. ## Background Each agentic workflow source (`.github/workflows/*.md`) is compiled by the `gh-aw` compiler into a committed `*.lock.yml`. The version baked into a lock is whatever compiler produced it, and **every** workflow tracks the same gh-aw version: the newest `github/gh-aw` release **or prerelease**, whichever was published most recently. There are no per-workflow categories — a bump recompiles all the locks together. **The detector version is baked into the locks.** `gh-aw`'s `buildInstallThreatDetectStep` unconditionally emits `constants.DefaultThreatDetectVersion` (a hardcoded tag, e.g. `v0.4.12`) as the argument to `install_threat_detect_binary.sh`. There is no CLI flag, env var, or frontmatter field that consults an alternate version at compile time. The detector pin therefore only moves when either: 1. `github/gh-aw` bumps the constant upstream (typically after a detector promotion) and a normal drift-recompile picks up the new tag, or 2. a maintainer does a targeted post-compile edit of the lock (see [Testing an unpromoted detector prerelease in the smokes](#testing-an-unpromoted-detector-prerelease-in-the-smokes) below). Promoting a detector release is **not** by itself enough to put it into the smokes — it takes effect only once the upstream constant is bumped and this repo's locks are recompiled against that gh-aw tag. ## 1. Determine the target gh-aw version The drift issue lists it. To confirm or resolve it yourself (any method works — `gh`, `curl`, or the GitHub Releases UI): newest `github/gh-aw` release **or** prerelease, i.e. the most recent by publish date whose tag looks like `v<digit>...`; ignore drafts. For example, with `gh` available: ```bash 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 ``` In the steps below, refer to this as `<TARGET_GH_AW>`. ## 2. Recompile the locks Recompile every workflow with the same tag. The released `gh aw` extension is the simplest route: ```bash gh extension install github/gh-aw --pin <TARGET_GH_AW> --force gh aw compile --action-mode action --action-tag <TARGET_GH_AW> --no-check-update \ .github/workflows/*.md ``` ### Building the compiler from source instead If `gh extension install` is unavailable (no `gh` auth, offline, etc.), build gh-aw from source — but you **must** set both version ldflags: ```bash git clone --depth 1 --branch <TAG> https://github.com/github/gh-aw /tmp/gh-aw-src ( cd /tmp/gh-aw-src && go build -ldflags "-X main.version=<TAG> -X main.isRelease=true" -o /tmp/gh-aw ./cmd/gh-aw ) ``` > [!IMPORTANT] > `-X main.isRelease=true` is not optional. `cmd/gh-aw/main.go` defaults > `isRelease` to `"false"` and passes it to `workflow.SetIsRelease()`, which > normalizes the emitted `compiler_version` / `GH_AW_VERSION` to `dev` and skips > release-only generation. Locks compiled without it look superficially fine but > carry `dev` at runtime. Verify before compiling: ```bash /tmp/gh-aw version # must print the target tag, not "dev" ``` ## 3. Verify and open a PR 1. Sanity-check that only the intended version bumps changed: ```bash git status --short -- .github/workflows git diff -- .github/workflows ``` Confirm each regenerated lock carries the target version in **both** places — they must not say `dev`: ```bash grep -o '"compiler_version":"[^"]*"' .github/workflows/*.lock.yml grep -n 'GH_AW_VERSION:' .github/workflows/*.lock.yml ``` Re-running the **gh-aw Version Check** workflow after the PR merges should report no drift. 2. Commit only the regenerated `*.lock.yml` files (and any intended `.md` changes). The compiler also refreshes `.github/aw/actions-lock.json` and may touch `.gitattributes` — that churn is expected. Open a PR describing the version bumps. 3. **Pushing workflow-file changes requires a token with the `workflows` permission.** The built-in `GITHUB_TOKEN` (github-actions[bot]) is rejected for changes under `.github/workflows/`, so this regeneration is done by a maintainer / agent whose credentials carry that permission — not by an automated push in the version-check workflow. 4. After merging, dispatch the top-level **Smoke** workflow to confirm the new versions run green. ## Testing an unpromoted detector prerelease There are two sanctioned paths, depending on what you want to exercise. ### Replay path (preferred for most prerelease iteration) Dispatch `.github/workflows/replay-detection.yml` with `detector_source=release`, `detector_ref=<prerelease tag>`, and `use_awf=true`. It downloads that exact release asset and runs it under AWF against a prior gh-aw run's artifacts. No lock edit needed. ### Smoke path (when you specifically need fresh AWF + fresh artifacts) The smokes only ever see whatever tag gh-aw's constant currently points at (promoted, stable). To point them at an unpromoted prerelease, do a targeted post-compile edit of the smoke locks: ```bash sed -i 's|install_threat_detect_binary.sh" v0\.[0-9.]*|install_threat_detect_binary.sh" <PRERELEASE_TAG>|' \ .github/workflows/smoke-copilot-standalone.lock.yml \ .github/workflows/smoke-claude-standalone.lock.yml \ .github/workflows/smoke-codex-standalone.lock.yml ``` Commit those three files and open a PR. Do **not** patch `constants.DefaultThreatDetectVersion` in a `gh-aw` fork to accomplish this: that route corrupts the compiler-version story (locks would carry a fork tag or lie about upstream), and it inverts the invariant that the constant tracks the promoted detector. Only touch the smoke locks. Leave `detection-stats-daily`, `detection-failure-monitor`, `gh-aw-issue-digest`, and `gh-aw-parity-monitor` on the compiler-emitted tag — they are not the test bed for detector prereleases. The edit is deliberately ephemeral: the next `gh aw compile` run will regenerate the locks from `constants.DefaultThreatDetectVersion` and revert the pin. That is intentional — prerelease pins should not survive a routine recompile. Once the detector is promoted and gh-aw bumps its constant, a normal drift-recompile picks it up on the standard path.