From 75a2acdb9b350c615df0dddf1d6f8fe07d075030 Mon Sep 17 00:00:00 2001 From: timflannagan Date: Fri, 31 Jul 2026 16:50:44 -0400 Subject: [PATCH] ci: Fix release artifact publication The release workflow now targets GHCR consistently, keeps container and Helm application versions aligned, and documents the complete tag-based maintainer process. Previously, image builds used the local build registry even after the workflow logged into GHCR, and the chart defaulted to an image tag without the release tag's leading v. The existing contributor notes also omitted artifact and recovery details. Now releases run only from validated stable SemVer tags, publish both images to GHCR, and configure the chart to use the matching application version. The documented procedure tags the freshly fetched main revision and covers published artifacts, verification, and retries. Signed-off-by: timflannagan --- .github/workflows/release.yaml | 24 +++--- CONTRIBUTING.md | 15 +--- DEVELOPMENT.md | 4 + charts/agentregistry/Chart-template.yaml | 4 +- .../agentregistry/tests/deployment_test.yaml | 2 +- docs/governance/cncf/technical-review.md | 3 + docs/releasing.md | 79 +++++++++++++++++++ 7 files changed, 107 insertions(+), 24 deletions(-) create mode 100644 docs/releasing.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 71bef6ddd..29741ab60 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -4,17 +4,27 @@ on: push: tags: - "v*.*.*" - workflow_dispatch: - inputs: - version: - description: 'Version number' env: - VERSION: ${{ github.event.inputs.version || github.ref_name }} + VERSION: ${{ github.ref_name }} DOCKER_REGISTRY: ghcr.io + DOCKER_BUILD_REGISTRY: ghcr.io jobs: + validate: + name: Validate release version + runs-on: ubuntu-latest + steps: + - name: Validate version + shell: bash + run: | + if [[ ! "${VERSION}" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then + echo "::error::version must match vX.Y.Z; got ${VERSION}" + exit 1 + fi + docker: + needs: validate strategy: matrix: image: @@ -121,7 +131,3 @@ jobs: bin/arctl-* build/charts/*.tgz build/charts/checksums.txt - - - name: Log out of Helm registry - if: always() - run: $HELM registry logout "${HELM_REGISTRY}" || true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14fda6a83..dce904264 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -273,18 +273,9 @@ refactor(db): simplify query methods ## Building for Release -```bash -# Full clean build -make all - -# Test the binary -./bin/arctl version -./bin/arctl ui - -# Create release -git tag -a v1.0.0 -m "Release v1.0.0" -git push origin v1.0.0 -``` +Maintainers should follow the complete [release process](docs/releasing.md). +Releases are built and published by GitHub Actions from an annotated SemVer +tag on `main`. ## Common Issues diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6fe00b41c..3f9bcb4d2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -84,6 +84,10 @@ Because `charts/agentregistry/Chart.yaml` is gitignored, some editors may flag i ### Helm release pipeline +For the complete project release procedure, including container images, CLI +binaries, the Helm chart, and verification, see +[Releasing AgentRegistry](docs/releasing.md). + The full release pipeline is encapsulated in a single target: ```bash diff --git a/charts/agentregistry/Chart-template.yaml b/charts/agentregistry/Chart-template.yaml index a7884488b..49956f79d 100644 --- a/charts/agentregistry/Chart-template.yaml +++ b/charts/agentregistry/Chart-template.yaml @@ -3,7 +3,7 @@ name: agentregistry description: Production-grade Helm chart for Agent Registry -- deploy, secure, and scale the open-source platform for curating and managing AI agents, MCP servers, and skills on Kubernetes with bundled PostgreSQL type: application version: ${CHART_VERSION} -appVersion: "${CHART_VERSION}" +appVersion: "v${CHART_VERSION}" kubeVersion: ">=1.19.0-0" keywords: - agentregistry @@ -25,6 +25,6 @@ annotations: url: https://github.com/agentregistry-dev/agentregistry artifacthub.io/images: | - name: agentregistry - image: ghcr.io/agentregistry-dev/agentregistry/server:${CHART_VERSION} + image: ghcr.io/agentregistry-dev/agentregistry/server:v${CHART_VERSION} - name: postgresql image: docker.io/library/postgres:18 diff --git a/charts/agentregistry/tests/deployment_test.yaml b/charts/agentregistry/tests/deployment_test.yaml index 518a2f2fc..201791583 100644 --- a/charts/agentregistry/tests/deployment_test.yaml +++ b/charts/agentregistry/tests/deployment_test.yaml @@ -25,7 +25,7 @@ tests: asserts: - matchRegex: path: spec.template.spec.containers[0].image - pattern: '^ghcr.io/agentregistry-dev/agentregistry/server:[^@\s]+$' + pattern: '^ghcr.io/agentregistry-dev/agentregistry/server:v[^@\s]+$' - it: uses digest when image.digest is set template: deployment.yaml diff --git a/docs/governance/cncf/technical-review.md b/docs/governance/cncf/technical-review.md index 3357f251b..e3fe2e0a6 100644 --- a/docs/governance/cncf/technical-review.md +++ b/docs/governance/cncf/technical-review.md @@ -160,6 +160,9 @@ agentregistry follows semantic versioning (https://semver.org/): - Minor Releases (0.x.0): New features, non-breaking changes. - Patch Releases (0.0.x): Bug fixes, security patches +The tagging, publication, artifact, verification, and recovery procedures are +documented in [Releasing AgentRegistry](../../releasing.md). + --- ## Installation diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 000000000..bf5993258 --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,79 @@ +# Releasing AgentRegistry + +AgentRegistry releases are published by the GitHub Actions release workflow. +The supported release path is to tag a commit on `main`; release artifacts +should not be published manually from a developer workstation. + +AgentRegistry follows Semantic Versioning: + +- Major (`X.0.0`): breaking API or behavior changes. +- Minor (`X.Y.0`): backward-compatible features. +- Patch (`X.Y.Z`): backward-compatible fixes, including security fixes. + +Release Git tags and container image tags include a leading `v`, such as +`v0.4.0`. Helm chart versions omit the prefix, such as `0.4.0`. + +## Published artifacts + +For a `vX.Y.Z` release, `.github/workflows/release.yaml` publishes: + +- Multi-architecture Linux container images for `amd64` and `arm64`: + - `ghcr.io/agentregistry-dev/agentregistry/server:vX.Y.Z` + - `ghcr.io/agentregistry-dev/agentregistry/arctl-agentgateway:vX.Y.Z` +- CLI binaries and individual SHA-256 files for: + - Linux `amd64` and `arm64` + - macOS `amd64` and `arm64` + - Windows `amd64` +- The Helm chart at + `oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry` + with chart version `X.Y.Z` and application version `vX.Y.Z`. +- A GitHub Release with generated release notes, the CLI files, the packaged + Helm chart, and the chart checksum file. + +## Cut a release + +1. Choose the next version according to Semantic Versioning. +2. Confirm the release commit is on `main` and all required checks pass. +3. Review merged changes since the previous release for the generated release + notes. +4. Create and push an annotated tag from the release commit: + + ```bash + git fetch origin + git tag -a vX.Y.Z origin/main -m "Release vX.Y.Z" + git push origin vX.Y.Z + ``` + +5. Monitor the `Release` workflow. The GitHub Release is created only after + both container images and the Helm chart have been published successfully. + +Do not move or reuse a published release tag. If released content needs to +change, publish a new patch version. + +## Verify a release + +Confirm all jobs in the `Release` workflow succeeded, then verify each public +artifact: + +```bash +gh release view vX.Y.Z +docker pull ghcr.io/agentregistry-dev/agentregistry/server:vX.Y.Z +docker pull ghcr.io/agentregistry-dev/agentregistry/arctl-agentgateway:vX.Y.Z +helm show chart \ + oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --version X.Y.Z +``` + +The GitHub Release should contain each CLI binary next to its `.sha256` file, +plus `agentregistry-X.Y.Z.tgz` and `checksums.txt`. Compare downloaded files +against their published SHA-256 values before distributing them. + +The Helm output should report `version: X.Y.Z` and `appVersion: vX.Y.Z`. The +default rendered server image must therefore use the same `vX.Y.Z` tag that +the container job published. + +## Retry and recovery + +First use GitHub Actions to rerun only failed jobs. Artifact publishing can be +partially complete, so inspect the GitHub Release, GHCR packages, and Helm OCI +chart before retrying.