Skip to content

releasing.md

Latest commit

 

History

History
257 lines (193 loc) · 12 KB

releasing.md

File metadata and controls

257 lines (193 loc) · 12 KB
Raw

Release Process

This document describes how to create a new release of the agentic-workflow-firewall (awf).

Prerequisites

  • Ability to trigger workflows (Actions tab or gh CLI)

Release Steps

1. Run the Release Workflow

From the CLI:

# Patch release (0.1.0 -> 0.1.1)
gh workflow run release.yml -f bump=patch

# Minor release (0.1.1 -> 0.2.0)
gh workflow run release.yml -f bump=minor

# Major release (0.2.0 -> 1.0.0)
gh workflow run release.yml -f bump=major

Or from the GitHub UI: go to Actions > Release > Run workflow, select the bump type, and click Run workflow.

The workflow will:

  • Bump the version in package.json
  • Commit the version change and create a git tag
  • Build and push Docker images to GHCR
  • Create Linux x64 and arm64 binaries
  • Create NPM tarball and checksums
  • Generate versioned JSON Schema files with the release tag embedded in their $id URLs
  • Publish the GitHub Release with auto-generated changelog

Release source identity and enclave acceptance

Git tags, not main's package.json, are the authoritative published versions. The workflow synchronizes the package and lockfile to the latest version tag, bumps them, and creates a tag-only version commit on the selected source. It does not push that commit to protected main. All release build jobs check out the new tag. Thus main remaining at 0.23.1 while v0.28.31 contains package version 0.28.31 is intentional, not an artifact publication bug.

Cloud Hypervisor production preflight requires both artifact sets to match the running package version; an arbitrary source checkout must not consume a newer release's artifacts. Enclave live acceptance must therefore build AWF from the exact published release tag, with that tag containing the reviewed acceptance implementation. The acceptance workflow additionally requires a full acceptance_commit SHA and verifies its ancestry and harness presence before the Copilot credential is introduced. Both downloaded manifests must identify the checked-out tag commit; signature and digest verification still run through production preflight.

A maintainer must merge the acceptance implementation and separately authorize the normal release workflow to publish its package-matched signed Cloud Hypervisor archive/manifest/bundle and both enclave role rootfs, SBOM and provenance sets. No package bump on main, retagging, or local artifact substitution is needed. See the explicit acceptance dispatch procedure for the separate, credential-bearing acceptance authorization.

Successful Cloud Hypervisor preflight fixtures must derive their manifest tag, rootfs/supervisor versions, and configured release tag from CLOUD_HYPERVISOR_ARTIFACT_RELEASE_TAG, rather than the version currently on main. Validate deterministic acceptance and foundation preflight tests with the package and lockfile coherently set to another release version as well as the source version, then restore both files before committing. Negative tests must still reject mismatched release identities and reach their intended gate.

A source fixture fix does not change an immutable published tag. In particular, the deterministic fixture failures on v0.28.33 require a future release containing the fix before live acceptance can proceed; rerunning that old tag cannot consume the corrected tests.

2. Verify Release

Once the workflow completes:

  1. Go to Releases page
  2. Verify the new release is published with:
    • Linux x64 binary (awf-linux-x64)
    • Linux arm64 binary (awf-linux-arm64)
    • NPM tarball (awf.tgz)
    • Checksums file (checksums.txt)
    • Container digest manifest (containers.txt)
    • JSON Schema files (awf-config.schema.json, audit.schema.json, token-usage.schema.json)
    • Installation instructions with GHCR image references
  3. Go to Packages page (in repository)
  4. Verify Docker images are published:
    • squid:<version> and squid:latest
    • agent:<version> and agent:latest
    • api-proxy:<version> and api-proxy:latest
    • cli-proxy:<version> and cli-proxy:latest
    • agent-act:<version> and agent-act:latest (GitHub Actions parity image)
    • enclave-script:<version> and enclave-script:latest
    • enclave-agent:<version> and enclave-agent:latest
    • enclave-mcp-server:<version> and enclave-mcp-server:latest

Release Artifacts

Each release includes:

GitHub Release Assets

  • awf-linux-x64 - Linux x64 standalone executable
  • awf-linux-arm64 - Linux arm64 standalone executable
  • awf.tgz - NPM package tarball (alternative installation method)
  • checksums.txt - SHA256 checksums for all files
  • containers.txt - Digest-pinned container manifest for published runtime images
  • awf-config.schema.json - AWF config JSON Schema
  • awf-config.v1.schema.json - Deprecated alias of awf-config.schema.json (kept for backward compatibility)
  • audit.schema.json - AWF audit JSONL record JSON Schema
  • token-usage.schema.json - AWF token-usage JSONL record JSON Schema

JSON Schema versioning

Each release generates all three schemas with a $id URL that includes the release tag, creating stable, pinnable references:

https://github.com/github/gh-aw-firewall/releases/download/v0.26.0/awf-config.schema.json
https://github.com/github/gh-aw-firewall/releases/download/v0.26.0/audit.schema.json
https://github.com/github/gh-aw-firewall/releases/download/v0.26.0/token-usage.schema.json

External consumers (e.g. the gh-aw compiler) should pin to the release URL or the stable raw URL:

Schema Pinned to release tag Always-latest from main
Config https://github.com/github/gh-aw-firewall/releases/download/<tag>/awf-config.schema.json https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json
Audit https://github.com/github/gh-aw-firewall/releases/download/<tag>/audit.schema.json https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/audit.schema.json
Token usage https://github.com/github/gh-aw-firewall/releases/download/<tag>/token-usage.schema.json https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/token-usage.schema.json

Migration note: The previously documented URL …/releases/download/<tag>/awf-config.v1.schema.json and the raw URL …/main/docs/awf-config.v1.schema.json are now deprecated. awf-config.v1.schema.json continues to be published as a compatibility alias (identical content to awf-config.schema.json) so existing consumers are not broken, but new consumers should use awf-config.schema.json instead. The docs/awf-config.v1.schema.json file in the repository has been removed; use docs/awf-config.schema.json for the always-latest copy.

JSONL _schema field: Each JSONL record embeds the AWF version in its _schema field, e.g. "_schema": "audit/v0.26.0". For audit logs, the version reflects the AWF CLI version that configured the Squid proxy. For token-usage logs, the version is baked into the api-proxy container image at release build time (via --build-arg AWF_VERSION=…), so it correctly reflects the api-proxy image version even when --image-tag pins the proxy to a different release. Dev/local builds use audit/v<package.json-version> and token-usage/v0.0.0-dev respectively. Consumers should use a prefix match (_schema.startsWith("audit/")) rather than an exact match to handle any version gracefully.

Schema evolution: Breaking changes (field removal, rename, type change, new required field) should be documented in the changelog. Since the repo version is used as the schema version, consumers can pin to a specific release tag to ensure compatibility.

GitHub Container Registry (GHCR)

Docker images are published to ghcr.io/github/gh-aw-firewall:

  • squid:<version> and squid:latest - Squid proxy container
  • agent:<version> and agent:latest - Agent execution environment (minimal, ~200MB)
  • api-proxy:<version> and api-proxy:latest - API proxy sidecar for credential isolation
  • cli-proxy:<version> and cli-proxy:latest - CLI proxy sidecar for gh CLI access via mcpg DIFC proxy
  • agent-act:<version> and agent-act:latest - Agent with GitHub Actions parity (~2GB)
  • enclave-script:<version> and enclave-script:latest - No-network script executor, built from containers/enclave/Dockerfile target enclave-script
  • enclave-agent:<version> and enclave-agent:latest - Single-use agent executor, built from containers/enclave/Dockerfile target enclave-agent
  • enclave-mcp-server:<version> and enclave-mcp-server:latest - Shared enclave MCP server, built from containers/enclave/Dockerfile target enclave-mcp-server

These images are automatically pulled by the CLI when running commands.

The agent-act image is used when running with --agent-image act for workflows that need closer parity with GitHub Actions runner environments.

Testing a Release Locally

Before releasing, you can test the build process locally:

Test Binary Creation

# Install pkg globally
npm install -g pkg

# Build TypeScript
npm run build

# Create Linux binary
mkdir -p release
pkg . --targets node18-linux-x64 --output release/awf

# Test the binary (requires Docker images - see below)
./release/awf-linux --help

Test Docker Images Locally

# Build images locally
docker build -t awf-test/squid:local ./containers/squid
docker build -t awf-test/agent:local ./containers/agent
docker build -t awf-test/api-proxy:local ./containers/api-proxy
docker build -t awf-test/cli-proxy:local ./containers/cli-proxy

# Test with local images
sudo ./dist/cli.js \
  --build-local \
  --allow-domains github.com \
  'curl https://github.com'

# Or test with existing GHCR images
sudo ./dist/cli.js \
  --allow-domains github.com \
  'curl https://github.com'

Troubleshooting

Release workflow fails

  1. Check the Actions tab for error logs
  2. Common issues:
    • Build errors: Check TypeScript compilation locally with npm run build
    • Docker build errors: Test image builds locally in containers/ directories
    • GHCR push errors: Ensure packages: write permission is granted
    • Permission errors: Ensure repository has contents: write permission

Binary doesn't work

  1. Test locally before release
  2. Ensure all dependencies are bundled (check pkg.assets in package.json)
  3. For dynamic requires, you may need to mark files/directories in pkg.assets

Docker images not available

If users report that Docker images can't be pulled:

  1. Check Packages page to verify images were published
  2. Verify image visibility is set to Public (not Private)
  3. Check image tags match what the CLI expects (version + latest)
  4. Users can use --build-local as a workaround while troubleshooting

To make packages public:

  1. Go to repository Packages page
  2. Click on the package (squid, agent, api-proxy, cli-proxy, or agent-act)
  3. Go to Package settings
  4. Change visibility to Public

Version mismatch

If you accidentally released the wrong version:

  1. Delete the tag remotely: git push origin :refs/tags/v0.1.0
  2. Delete the release from GitHub UI
  3. Delete or retag the GHCR images if needed
  4. Re-run the workflow with the correct bump type

Pre-release Versions

Pre-release versions are not currently supported via the workflow dispatch input. To create a pre-release, manually bump the version locally and push:

npm version prerelease --preid=alpha  # 0.1.0 -> 0.1.1-alpha.0
git push origin main --tags

The release workflow can then be triggered manually (it will read the pre-release version from package.json and skip the bump step since the tag already exists).

Maintenance Releases

For backporting fixes to older major versions:

  1. Create a maintenance branch: git checkout -b v0.x
  2. Cherry-pick or apply fixes
  3. Push branch: git push origin v0.x
  4. Run the release workflow on the maintenance branch (select the v0.x branch in the UI)