Text of github.github.com › gh-aw › reference › releases as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Releases and Versioning | GitHub Agentic Workflows

Skip to main content Releases and Versioning GitHub Agentic Workflows uses a two-layer versioning model: the CLI extension ( gh aw ) that you run locally or in CI, and the compiled .lock.yml files that run in GitHub Actions. Each layer has independent version tracking. Release Cadence Section titled “Release Cadence” gh-aw follows a weekly or bi-weekly minor release cadence , similar to VS Code’s release practices .

Each release cycle: A new minor version is published as a prerelease and floated for a few days. On Monday , the last known-good prerelease is promoted to stable and latest is updated. Immediately after promotion, the next minor prerelease is kicked off. Patch releases are reserved for urgent fixes between cycles. Major releases are used only for significant breaking changes. Release Channels Section titled “Release Channels” Two options are available when installing gh-aw: Channel Alias Behavior Latest (default) latest Always resolves to the most recent GitHub release Pinned vMAJOR.MINOR.PATCH A fixed release tag — use when you need exact reproducibility Installing a channel Section titled “Installing a channel” Terminal window # Latest (default — no version flag needed) curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash # Specific version curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.64.5 Via the GitHub CLI extension manager: Terminal window gh extension install github/gh-aw # latest (default) gh extension install github/gh-aw@v0.64.5 # pinned version Checking and updating your version Section titled “Checking and updating your version” Terminal window gh aw version # Show currently installed version gh extension upgrade gh-aw # Upgrade to the latest release gh aw upgrade --pre-releases # Also consider newer pre-releases gh extension install github/gh-aw --force --pin v0.75.3-beta.1 # Install an exact pre-release tag Pinning in GitHub Actions Section titled “Pinning in GitHub Actions” Use the setup-cli action to install a specific version in CI: - name : Install gh-aw uses : github/gh-aw/actions/setup-cli@main with : version : v0.64.5 Version Enforcement in Compiled Workflows Section titled “Version Enforcement in Compiled Workflows” Every compiled .lock.yml embeds the gh-aw version used to produce it: GH_AW_INFO_AWF_VERSION : " v0.64.5 " At runtime, the activation job fetches .github/aw/compat.json and compares the embedded version against three policies: Policy Effect blockedVersions Workflow fails — the compiled version has been revoked minimumVersion Workflow fails — the compiled version is too old minRecommendedVersion Workflow warns — an upgrade is recommended but not enforced This means that if you compiled a workflow months ago with an older version of gh aw , you may see a warning (or failure) asking you to recompile with a newer version.

Run gh aw upgrade to bring all workflows up to date. Setup action dependency upgrades can also introduce runtime requirements that older generated workflows do not meet. If activation reports that a workflow is too old for safe-output publishing, update gh-aw , run gh aw compile , and commit the regenerated workflow files. Updating only the pinned setup action is not sufficient; older workflows must pass the publishing job’s check-run context for execution provenance.

This requirement is enforced by the newer setup runtime and does not retroactively block workflows that remain pinned to an older runtime. Common Compatibility Fixes After Upgrading Section titled “Common Compatibility Fixes After Upgrading” Older workflow sources can fail compilation after a CLI upgrade. For the two configuration patterns below, preview and apply the existing automatic fixes, then regenerate lock files: Terminal window gh aw fix gh aw fix --write gh aw compile Review and commit the changed workflow .md and generated .lock.yml files.

Fixing compilation does not restore removed tool capabilities; review the workflow’s tool requirements before running it. Copilot Web Tools in Offline BYOK Mode Section titled “Copilot Web Tools in Offline BYOK Mode” Copilot runs with COPILOT_OFFLINE=true in offline BYOK mode. Compilation rejects tools.web-search in both CLI and SDK modes, and tools.web-fetch in CLI mode. gh aw fix --write removes these unsupported declarations.

If the workflow still needs web access, configure an MCP server instead, or switch to an engine that supports the required tools, such as engine: codex . See web search configuration . For fetching only, enable Copilot SDK mode to retain tools.web-fetch : engine: id: copilot copilot-sdk: true tools: web-fetch: SDK mode provides a custom proxy-aware fetch tool that follows network.allowed ; it does not enable native web search.

Explicit Bash Configuration with min-integrity: none Section titled “Explicit Bash Configuration with min-integrity: none” Strict mode requires an explicit tools.bash setting when tools.github.min-integrity is none , so shell access is intentional when processing untrusted content. gh aw fix --write inserts tools.bash: false when the setting is absent. Keep this value if shell access is unnecessary. If the workflow needs shell commands, declare a limited allowlist instead: tools: bash: ["cat", "ls", "find", "grep", "head", "tail", "wc"] github: min-integrity: none Choose only the commands the workflow needs.

Setting min-integrity: none disables the automatic integrity protection for public repositories; use it only for workflows designed to handle untrusted input. See integrity filtering and Bash configuration . How Lock Files Are Pinned Section titled “How Lock Files Are Pinned” When gh aw compile generates a .lock.yml , it pins every GitHub Actions reference to a commit SHA: # Generated lock file (do not edit manually) uses : actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 SHA pins are immutable — unlike tags, they cannot be silently redirected to a different commit.

This protects workflows from supply-chain attacks. The resolved SHA mappings are cached in .github/aw/actions-lock.json . Commit this file to version control so that all contributors and automated tools (including GitHub Copilot Coding Agent) produce identical lock files without needing broad API access. To refresh action pins: Terminal window gh aw update-actions # Update actions-lock.json to latest SHAs gh aw compile # Recompile workflows using the refreshed pins upgrade vs update Section titled “upgrade vs update” These two commands address different concerns: gh aw upgrade — update the tooling Section titled “gh aw upgrade — update the tooling” upgrade brings the repository’s agentic workflow infrastructure up to date with the current version of gh aw .

It: Self-updates the gh aw extension to the latest version Regenerates the dispatcher agent file (like gh aw init ) Applies codemods to fix deprecated syntax across all workflow markdown files Updates GitHub Actions versions in actions-lock.json Recompiles all workflows to produce fresh .lock.yml files Run upgrade after installing a new version of gh aw , or periodically to keep your repository current. Terminal window gh aw upgrade # Upgrade everything gh aw upgrade --no-actions # Skip updating action pins gh aw upgrade --audit # Check dependency health without upgrading gh aw upgrade --create-pull-request # Open a PR with the changes gh aw update — update workflow content from source Section titled “gh aw update — update workflow content from source” update fetches the latest version of workflow markdown files from their upstream source repositories.

It only applies to workflows that declare a source field in their frontmatter. # Example workflow with a source field source : github/gh-aw/.github/workflows/shared/ci-doctor.md@v1 By default, update merges upstream changes with your local modifications (3-way merge). Use --no-merge to overwrit

The rest of this page is on the live site.