diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 71bef6dd..29741ab6 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 14fda6a8..dce90426 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 6fe00b41..3f9bcb4d 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 a7884488..49956f79 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 518a2f2f..20179158 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 3357f251..e3fe2e0a 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 00000000..bf599325 --- /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.