RELEASE notes

Signed-off-by: Jason Madigan <jason@jasonmadigan.com>

Author: jasonmadigan

.github/workflows/docker.yml

@@ -6,9 +6,13 @@ on:
       - main
     tags:
       - 'v*'
+      - '[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+'
   pull_request:
     branches:
       - main
+  release:
+    types: [created, published]
 
 env:
   REGISTRY: ghcr.io
@@ -29,6 +33,7 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Log in to the Container registry
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
@@ -41,18 +46,26 @@ jobs:
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
-            type=ref,event=branch
-            type=ref,event=pr
+            # :latest tag for main branch
+            type=raw,value=latest,enable={{is_default_branch}}
+            # version tags for releases (e.g., 0.1, 1.2.3, v1.0.0)
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
-            type=sha
+            type=semver,pattern={{major}}
+            # branch name for branches
+            type=ref,event=branch
+            # pr-123 for pull requests
+            type=ref,event=pr
+            # short sha for all builds
+            type=sha,prefix={{branch}}-
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
         with:
           context: .
-          push: true
+          push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64

README.md

@@ -10,7 +10,7 @@ A Model Context Protocol (MCP) server that generates Kuadrant policy manifests i
 
 ```bash
 # Add the MCP server using Docker (available in all projects)
-claude mcp add kuadrant docker run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest -s user
+claude mcp add -s user kuadrant "docker run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest"
 
 # Verify installation
 claude mcp list
@@ -47,6 +47,11 @@ docker pull ghcr.io/kuadrant/kuadrant-mcp-server:latest
 ```bash
 git clone https://github.com/kuadrant/kuadrant-mcp-server
 cd kuadrant-mcp-server
+
+# Build binary
+go build -o kuadrant-mcp-server
+
+# Or build Docker image
 docker build -t kuadrant-mcp-server:latest .
 ```
 
@@ -596,15 +601,6 @@ spec:
 - RateLimitPolicy: `kuadrant.io/v1`
 - AuthPolicy: `kuadrant.io/v1`
 
-## Building from Source
-
-```bash
-git clone https://github.com/kuadrant/kuadrant-mcp-server
-cd kuadrant-mcp-server
-go build -o kuadrant-mcp-server
-```
-
-
 ## Claude Code CLI Setup
 
 To use this server with Claude Code CLI:
@@ -613,7 +609,7 @@ To use this server with Claude Code CLI:
 
 ```bash
 # Add using Docker image
-claude mcp add kuadrant docker run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest -s user
+claude mcp add -s user kuadrant "docker run -i --rm ghcr.io/kuadrant/kuadrant-mcp-server:latest"
 
 # Verify installation
 claude mcp list
@@ -624,36 +620,16 @@ claude  # Start new session, type /mcp to see available servers
 
 ### Option 2: Using Local Binary
 
-1. **Build the server**
-   ```bash
-   go build -o kuadrant-mcp-server
-   ```
-
-2. **Add to Claude Code**
-   ```bash
-   claude mcp add kuadrant /path/to/kuadrant-mcp-server
-   ```
+```bash
+# Build the server
+go build -o kuadrant-mcp-server
 
-   For example:
-   ```bash
-   claude mcp add kuadrant /Users/yourusername/kuadrant-mcp-server/kuadrant-mcp-server
-   ```
+# Add to Claude Code
+claude mcp add -s user kuadrant ./kuadrant-mcp-server
 
-3. **Verify installation**
-   ```bash
-   claude mcp list
-   ```
-
-4. **Test in Claude**
-   Start a new Claude session and type:
-   ```
-   /mcp
-   ```
-   
-   You should see "kuadrant" listed. Then try:
-   ```
-   Create a Gateway manifest named 'test-gateway' in namespace 'default'
-   ```
+# Start using
+claude  # Start new session, type /mcp to see available servers
+```
 
 ### Troubleshooting
 
@@ -822,33 +798,25 @@ The update script:
 
 For more details, see [UPDATE_DOCS.md](UPDATE_DOCS.md).
 
-## MCP Configuration
+## Releases and Versioning
 
-To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:
+See [RELEASE.md](RELEASE.md) for detailed release procedures.
 
-Using the pre-built Docker image:
-```json
-{
-  "mcpServers": {
-    "kuadrant": {
-      "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/kuadrant/kuadrant-mcp-server:latest"]
-    }
-  }
-}
-```
+**Available versions:**
+- `:latest` - Tracks main branch (may be unstable)
+- `:1.2.3` - Specific version (recommended for production)
+- `:1.2` - Latest patch in minor version
+- `:1` - Latest release in major version
 
-Or if running the binary locally:
-```json
-{
-  "mcpServers": {
-    "kuadrant": {
-      "command": "/path/to/kuadrant-mcp-server"
-    }
-  }
-}
+**Creating releases:**
+```bash
+# Tag and push
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# GitHub automatically builds and publishes Docker images
 ```
 
-## License
+## Licence
 
 Apache 2.0

RELEASE.md

@@ -0,0 +1,134 @@
+# Release Process
+
+This document describes how to create and publish releases for the Kuadrant MCP Server.
+
+## Overview
+
+The project uses GitHub Actions to automatically build and publish Docker images:
+- Continuous deployment: Every merge to `main` updates the `:latest` tag
+- Release versions: Creating a GitHub release publishes versioned tags
+
+## Creating a Release
+
+### 1. Choose Version Number
+
+Follow semantic versioning (MAJOR.MINOR.PATCH):
+- MAJOR: Breaking changes to tools/resources API
+- MINOR: New features, backward compatible
+- PATCH: Bug fixes, documentation updates
+
+### 2. Create GitHub Release
+
+#### Option A: Via GitHub UI
+1. Go to [Releases](https://github.com/kuadrant/kuadrant-mcp-server/releases)
+2. Click "Draft a new release"
+3. Choose a tag (create new):
+   - Format: `v1.2.3` or `1.2.3` or `0.1`
+   - Both `v`-prefixed and plain versions work
+4. Set release title (e.g., "v1.2.3 - Feature Name")
+5. Add release notes:
+   - New features
+   - Bug fixes
+   - Breaking changes
+   - Credits
+6. Click "Publish release"
+
+#### Option B: Via GitHub CLI
+```bash
+# Create and push a tag
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# Create release with notes
+gh release create v1.2.3 \
+  --title "v1.2.3 - Feature Name" \
+  --notes "## What's Changed
+- Feature X added
+- Bug Y fixed
+- Breaking: Removed Z"
+```
+
+### 3. Automated Publishing
+
+Once the release is created, GitHub Actions will automatically:
+1. Build multi-platform Docker images (linux/amd64, linux/arm64)
+2. Push to GitHub Container Registry with tags:
+   - `ghcr.io/kuadrant/kuadrant-mcp-server:1.2.3` (exact version)
+   - `ghcr.io/kuadrant/kuadrant-mcp-server:1.2` (minor version)
+   - `ghcr.io/kuadrant/kuadrant-mcp-server:1` (major version)
+
+### 4. Verify Release
+
+Check that images are published:
+```bash
+# Pull specific version
+docker pull ghcr.io/kuadrant/kuadrant-mcp-server:1.2.3
+
+# Verify it works
+docker run --rm ghcr.io/kuadrant/kuadrant-mcp-server:1.2.3 --version
+```
+
+## Release Notes Template
+
+```markdown
+## What's Changed
+
+### New Features
+- Feature description (#PR)
+
+### Bug Fixes
+- Fix description (#PR)
+
+### Documentation
+- Docs update (#PR)
+
+### Breaking Changes
+- Change description and migration path
+
+### Credits
+- @contributor1 - Feature X
+- @contributor2 - Bug fix Y
+
+Full Changelog: https://github.com/kuadrant/kuadrant-mcp-server/compare/v1.2.2...v1.2.3
+```
+
+## Continuous Deployment
+
+The `main` branch is continuously deployed:
+- Every merge to `main` triggers a build
+- Updates the `:latest` Docker tag
+- Available immediately at `ghcr.io/kuadrant/kuadrant-mcp-server:latest`
+
+Note: `:latest` may be unstable. For production use, pin to a specific version.
+
+## Version Support
+
+- Latest: Always tracks `main` branch (may be unstable)
+- Major versions (e.g., `:1`): Latest release in that major version
+- Minor versions (e.g., `:1.2`): Latest patch in that minor version
+- Exact versions (e.g., `:1.2.3`): Immutable, specific release
+
+## Troubleshooting
+
+### Docker Build Failed
+Check the [Actions tab](https://github.com/kuadrant/kuadrant-mcp-server/actions) for build logs.
+
+### Wrong Version Published
+- Tags are immutable once pushed
+- To fix: Create a new patch version with the fix
+- Never force-push or delete published tags
+
+### Multi-platform Issues
+The workflow builds for both `linux/amd64` and `linux/arm64`. If one fails:
+1. Check architecture-specific dependencies
+2. Test locally with: `docker buildx build --platform linux/arm64 .`
+
+## Pre-release Checklist
+
+Before creating a release:
+- [ ] Update documentation if needed
+- [ ] Run tests: `go test ./...`
+- [ ] Build locally: `docker build -t test .`
+- [ ] Test the Docker image: `docker run --rm test`
+- [ ] Update CHANGELOG if maintained
+- [ ] Check for security vulnerabilities: `go mod audit`