ci: Fix release artifact publication

.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

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
 

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

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

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

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

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.