Versioning Across Multiple Projects

Overview

The Agent Platform consists of 60+ projects that need coordinated versioning. This guide covers strategies for managing versions across multiple repositories while maintaining independence where needed.

Agent Platform Architecture

Project Types

The Agent Platform has three types of projects:

1. Core Projects - Shared infrastructure

   • agent-core - Core agent runtime
   • agent-sdk - SDK for building agents
   • agent-cli - Command-line interface

2. Agent Projects - Individual agents (60+ projects)

   • openstandardagents - Open Standard Agents
   • gitlab-agent - GitLab integration agent
   • kubernetes-agent - Kubernetes operator agent
   • ... (60+ more)

3. Infrastructure Projects - Supporting services

   • agent-registry - Agent discovery service
   • agent-gateway - API gateway
   • agent-dashboard - Web dashboard

Versioning Strategy

Platform Version: v0.3.x
 Core Projects: v0.3.x (synchronized)
 Agent Projects: Independent versions
 Infrastructure: v0.3.x (synchronized)

Versioning Models

Model 1: Independent Versioning

Each project has its own version number.

Pros:

• Projects version at their own pace
• Clear what changed in each project
• No unnecessary version bumps

Cons:

• Harder to coordinate releases
• Compatibility matrix needed
• Version skew between projects

Best for: Agent projects (60+ individual agents)

Example:

openstandardagents: v0.5.2
gitlab-agent:       v0.3.1
kubernetes-agent:   v0.7.0

Model 2: Fixed/Synchronized Versioning

All projects share the same version number.

Pros:

• Simple to understand
• Easy to coordinate releases
• Clear platform version

Cons:

• Many projects bump version unnecessarily
• Loses per-project semantic meaning
• Can't version independently

Best for: Core and infrastructure projects

Example:

agent-core:     v0.3.5
agent-sdk:      v0.3.5
agent-cli:      v0.3.5
agent-registry: v0.3.5

Model 3: Hybrid (Agent Platform)

Core projects synchronized, agents independent.

Pros:

• Best of both worlds
• Core stability with agent flexibility
• Clear platform compatibility

Cons:

• More complex to manage
• Need compatibility tracking
• Documentation overhead

Agent Platform Strategy:

Platform Version: v0.3.x
 Core Projects: v0.3.5 (all synchronized)
 Agent Projects: Independent (v0.5.2, v0.3.1, v0.7.0...)
 Infrastructure: v0.3.5 (synchronized with core)

Group Milestones for Coordination

Group Milestone Structure

Group: blueflyio/agent-platform

Milestones:
 v0.1.x - Initial release
 v0.2.x - Core features
 v0.3.x - Integrations (current)
 v1.0.x - Production ready
 v1.1.x - Enhancements

Cross-Project Coordination

Example: v0.3.x Milestone

Milestone: v0.3.x (Group)

Core Projects (synchronized):
 agent-core (v0.3.0 † v0.3.5)
 agent-sdk (v0.3.0 † v0.3.5)
 agent-cli (v0.3.0 † v0.3.5)

Agent Projects (independent):
 openstandardagents (v0.5.0 † v0.5.2)
 gitlab-agent (v0.3.0 † v0.3.1)
 kubernetes-agent (v0.7.0 † v0.7.1)

Infrastructure (synchronized):
 agent-registry (v0.3.0 † v0.3.5)
 agent-gateway (v0.3.0 † v0.3.5)

Creating Group Milestones

# Create group milestone for v0.3.x
glab api graphql -f query='
mutation {
  createMilestone(
    input: {
      groupPath: "blueflyio/agent-platform"
      title: "v0.3.x"
      description: "Platform release series v0.3.x"
    }
  ) {
    milestone {
      id
      title
    }
  }
}'

# Or using glab milestone (if available for groups)
glab milestone create v0.3.x \
  --group blueflyio/agent-platform \
  --title "v0.3.x Platform Release" \
  --description "Coordinated release for platform v0.3.x"

Assigning Issues to Group Milestones

# Create issue with group milestone
glab issue create \
  --title "Add OAuth2 support to core" \
  --milestone v0.3.x \
  --repo blueflyio/agent-platform/agent-core

# Update existing issue
glab issue update 106 \
  --milestone v0.3.x \
  --repo blueflyio/openstandardagents

Dependency Management

Version Constraints

Core Project Dependencies

Core projects depend on each other with exact versions:

// agent-cli/package.json
{
  "name": "@agent-platform/cli",
  "version": "0.4.9",
  "dependencies": {
    "@agent-platform/core": "0.3.5",
    "@agent-platform/sdk": "0.3.5"
  }
}

Agent Dependencies

Agents depend on core with minor version range:

// openstandardagents/package.json
{
  "name": "@agent-platform/openstandardagents",
  "version": "0.4.9",
  "dependencies": {
    "@agent-platform/core": "^0.3.0",
    "@agent-platform/sdk": "^0.3.0"
  }
}

Rationale: Agents work with any v0.3.x core version.

Compatibility Matrix

Track compatibility between core and agent versions:

# Compatibility Matrix

| Core Version | Compatible Agent Versions |
|--------------|---------------------------|
| v0.1.x       | v0.1.x - v0.4.x          |
| v0.2.x       | v0.3.x - v0.6.x          |
| v0.3.x       | v0.5.x - v0.8.x          |
| v1.0.x       | v1.0.x+                  |

Automated Compatibility Checks

# .gitlab-ci.yml
check-compatibility:
  stage: validate
  image: node:20-alpine
  script:
    - |
      # Get core version from dependencies
      CORE_VERSION=$(jq -r '.dependencies["@agent-platform/core"]' package.json)

      # Query compatibility matrix
      COMPATIBLE=$(curl -s "https://api.agent-platform.io/compatibility?core=$CORE_VERSION&agent=$CI_COMMIT_TAG")

      if [ "$COMPATIBLE" != "true" ]; then
        echo "ERROR: Agent $CI_COMMIT_TAG not compatible with core $CORE_VERSION"
        echo "See compatibility matrix: https://docs.agent-platform.io/compatibility"
        exit 1
      fi

      echo "Compatibility check passed"
  only:
    - tags

Synchronized Release Process

Core Project Release

When releasing synchronized core projects:

# .gitlab-ci.yml (agent-core, agent-sdk, agent-cli, agent-registry, agent-gateway)
trigger-coordinated-release:
  stage: release
  script:
    - |
      # This project version
      NEXT_VERSION=$NEXT_VERSION

      # Trigger releases in dependent projects
      glab api -X POST "/projects/blueflyio%2Fagent-platform%2Fagent-sdk/trigger/pipeline" \
        -f "token=$CI_JOB_TOKEN" \
        -f "ref=release/v0.3.x" \
        -f "variables[CORE_VERSION]=$NEXT_VERSION"

      glab api -X POST "/projects/blueflyio%2Fagent-platform%2Fagent-cli/trigger/pipeline" \
        -f "token=$CI_JOB_TOKEN" \
        -f "ref=release/v0.3.x" \
        -f "variables[CORE_VERSION]=$NEXT_VERSION"
  only:
    - /^release\/v[0-9]+\.[0-9]+\.x$/
  when: manual

Coordinated Release Steps

1. Release Core (agent-core)

   v0.3.4 † v0.3.5
   

2. Update Dependencies in SDK, CLI, Registry, Gateway

   "@agent-platform/core": "0.3.5"

3. Release Dependents

   agent-sdk: v0.3.4 † v0.3.5
   agent-cli: v0.3.4 † v0.3.5
   agent-registry: v0.3.4 † v0.3.5
   agent-gateway: v0.3.4 † v0.3.5
   

4. Verify All Releases

   # Check all core projects released
   glab release list --repo blueflyio/agent-platform/agent-core | grep v0.3.5
   glab release list --repo blueflyio/agent-platform/agent-sdk | grep v0.3.5
   glab release list --repo blueflyio/agent-platform/agent-cli | grep v0.3.5

5. Update Platform Version

   # Tag platform with combined release
   git tag v0.3.5 -m "Platform release v0.3.5"
   git push origin v0.3.5

Independent Agent Releases

Agents release independently from core platform:

# .gitlab-ci.yml (agent projects)
release-agent:
  stage: release
  script:
    - |
      # Calculate next version for this agent
      BRANCH_VERSION=$(echo $CI_COMMIT_REF_NAME | sed 's/release\/v\([0-9]*\.[0-9]*\)\.x/\1/')
      LATEST_TAG=$(git tag -l "v${BRANCH_VERSION}.*" --sort=-v:refname | head -n 1)

      if [ -z "$LATEST_TAG" ]; then
        NEXT_VERSION="v${BRANCH_VERSION}.0"
      else
        PATCH=$(echo $LATEST_TAG | awk -F. '{print $NF}')
        NEXT_VERSION="v${BRANCH_VERSION}.$((PATCH + 1))"
      fi

      # Release this agent
      git tag $NEXT_VERSION
      git push origin $NEXT_VERSION

      glab release create $NEXT_VERSION \
        --name "Release $NEXT_VERSION" \
        --notes "$(./scripts/generate-release-notes.sh $NEXT_VERSION)"
  only:
    - /^release\/v[0-9]+\.[0-9]+\.x$/

Agent versions are NOT synchronized:

openstandardagents: v0.5.2
gitlab-agent:       v0.3.1
kubernetes-agent:   v0.7.0

Monorepo vs Polyrepo

Polyrepo (Agent Platform)

The Agent Platform uses polyrepo strategy:

Structure:

blueflyio/agent-platform/
 agent-core/           (separate repo)
 agent-sdk/            (separate repo)
 agent-cli/            (separate repo)
 openstandardagents/   (separate repo)
 gitlab-agent/         (separate repo)
 ... (60+ separate repos)

Pros:

• Clear ownership boundaries
• Independent release cycles
• Smaller repos, faster CI
• Different access controls

Cons:

• Coordinating changes harder
• Dependency management complex
• Version matrix needed

Monorepo Alternative

Some platforms use monorepo:

Structure:

agent-platform/          (single repo)
 packages/
‚   core/
‚   sdk/
‚   cli/
‚   agents/
‚      openstandardagents/
‚      gitlab-agent/
‚      kubernetes-agent/
 package.json

Pros:

• Atomic cross-project changes
• Simplified dependency management
• Single source of truth

Cons:

• Large repo, slower operations
• All-or-nothing releases
• Harder to isolate permissions

Not used by Agent Platform due to scale (60+ projects).

Version Tagging Strategy

Tag Format by Project Type

Core Projects (synchronized)

v0.3.5

Plain semantic version, synchronized across core projects.

Agent Projects (independent)

openstandardagents-v0.5.2
gitlab-agent-v0.3.1
kubernetes-agent-v0.7.0

Prefixed with project name to avoid collisions in aggregated views.

Platform Releases

platform-v0.3.5

Aggregated release representing core + compatible agents.

Example Tag Structure

# Core releases
v0.3.0, v0.3.1, v0.3.2, v0.3.3, v0.3.4, v0.3.5

# Agent releases (independent)
openstandardagents-v0.5.0, openstandardagents-v0.5.1, openstandardagents-v0.5.2
gitlab-agent-v0.3.0, gitlab-agent-v0.3.1
kubernetes-agent-v0.7.0, kubernetes-agent-v0.7.1

# Platform releases (aggregate)
platform-v0.3.0, platform-v0.3.5

Changelog Aggregation

Platform Changelog

Aggregate changes from all projects:

# Platform Changelog

## [0.3.5] - 2026-01-08

### Core (@agent-platform/core v0.3.5)

#### Features
- OAuth2 authentication support
- Distributed tracing integration

#### Bug Fixes
- Memory leak in agent runtime
- Token validation edge case

### SDK (@agent-platform/sdk v0.3.5)

#### Features
- New authentication API
- Async operation support

### CLI (@agent-platform/cli v0.3.5)

#### Features
- `auth` command for OAuth2 setup
- Configuration management

### Agents

#### openstandardagents (v0.5.2)
- GitLab Duo integration
- Enhanced observability

#### gitlab-agent (v0.3.1)
- CI/CD pipeline agent
- MR automation

#### kubernetes-agent (v0.7.1)
- Kubernetes operator
- Custom resource definitions

Automated Aggregation

#!/bin/bash
# aggregate-changelog.sh

PLATFORM_VERSION=$1
RELEASE_DATE=$(date +%Y-%m-%d)

echo "# Platform Changelog"
echo ""
echo "## [$PLATFORM_VERSION] - $RELEASE_DATE"
echo ""

# Core projects
for project in agent-core agent-sdk agent-cli agent-registry agent-gateway; do
  echo "### $project ($PLATFORM_VERSION)"
  echo ""

  # Extract changelog from project
  PROJECT_CHANGELOG=$(glab api "/projects/blueflyio%2Fagent-platform%2F$project/repository/files/CHANGELOG.md/raw?ref=v$PLATFORM_VERSION")

  # Parse and extract current version section
  echo "$PROJECT_CHANGELOG" | sed -n "/## \[$PLATFORM_VERSION\]/,/## \[/p" | sed '1d;$d'
  echo ""
done

# Agent projects (get latest versions)
echo "### Agent Projects"
echo ""

for agent in openstandardagents gitlab-agent kubernetes-agent; do
  AGENT_VERSION=$(glab api "/projects/blueflyio%2F$agent/repository/tags" | jq -r '.[0].name')
  echo "#### $agent ($AGENT_VERSION)"

  # Extract changelog
  AGENT_CHANGELOG=$(glab api "/projects/blueflyio%2F$agent/repository/files/CHANGELOG.md/raw?ref=$AGENT_VERSION")
  echo "$AGENT_CHANGELOG" | sed -n "/## \[$AGENT_VERSION\]/,/## \[/p" | sed '1d;$d' | head -5
  echo ""
done

Release Coordination

Platform Release Process

1. Plan Release

   # Create group milestone
   glab milestone create v0.3.x --group blueflyio/agent-platform

2. Develop Features

   # Assign issues to milestone across projects
   glab issue create --milestone v0.3.x --repo blueflyio/agent-platform/agent-core
   glab issue create --milestone v0.3.x --repo blueflyio/openstandardagents

3. Track Progress

   # View milestone progress
   glab api "/groups/blueflyio%2Fagent-platform/milestones?title=v0.3.x"

4. Release Core Projects (synchronized)

   # Release core, SDK, CLI together
   # CI handles dependency updates and coordinated releases

5. Release Agents (independent)

   # Each agent releases when ready
   # Compatible with core v0.3.x

6. Create Platform Release

   # Aggregate release
   ./scripts/create-platform-release.sh v0.3.5

7. Update Documentation

   # Update compatibility matrix
   # Update platform changelog
   # Publish release notes

Best Practices

DO

1. Use group milestones for coordination

   • Track work across projects
   • Coordinate releases
   • Monitor progress

2. Synchronize core projects

   • Keep core, SDK, CLI in sync
   • Update dependencies together
   • Release as a unit

3. Allow agents independence

   • Version at their own pace
   • Compatible with core minor versions
   • Clear compatibility matrix

4. Document compatibility

   • Which agent versions work with which core
   • Update matrix with each release
   • Automate compatibility checks

5. Aggregate changelogs

   • Platform-level changelog
   • Per-project changelogs
   • Clear what changed where

6. Automate coordination

   • CI triggers dependent releases
   • Dependency updates automated
   • Version compatibility validated

DON'T

1. Don't version everything together

   • 60+ projects at same version = noise
   • Lost semantic meaning
   • Unnecessary version bumps

2. Don't allow core version skew

   • Core, SDK, CLI must stay in sync
   • Breaking changes need coordination
   • Test together

3. Don't forget compatibility

   • Agents must work with core
   • Document requirements
   • Validate in CI

4. Don't manually coordinate

   • Automate releases
   • Use CI/CD pipelines
   • Reduce human error

5. Don't skip documentation

   • Update compatibility matrix
   • Maintain changelogs
   • Publish release notes

Troubleshooting

Issue: Version Skew

Problem: Core projects out of sync

agent-core: v0.3.5
agent-sdk:  v0.3.4  † Out of sync
agent-cli:  v0.3.5

Solution: Trigger synchronized release:

# Trigger SDK release to catch up
glab api -X POST "/projects/blueflyio%2Fagent-platform%2Fagent-sdk/trigger/pipeline" \
  -f "token=$CI_JOB_TOKEN" \
  -f "ref=release/v0.3.x"

Issue: Agent Incompatibility

Problem: Agent doesn't work with new core version

Solution: Update agent dependencies and test:

# Update package.json
npm install @agent-platform/core@^0.3.0

# Run compatibility tests
npm test

# Release new agent version
git commit -m "chore(deps): update core to v0.3.x"
git push

Issue: Milestone Chaos

Problem: Issues across multiple milestones

Solution: Use group milestones consistently:

# Audit issues without group milestone
glab api "/groups/blueflyio%2Fagent-platform/issues?milestone=None"

# Update to group milestone
glab issue update <ID> --milestone v0.3.x

Tools and Scripts

Check Synchronization

#!/bin/bash
# check-core-sync.sh

EXPECTED_VERSION=$1

for project in agent-core agent-sdk agent-cli agent-registry agent-gateway; do
  ACTUAL_VERSION=$(glab api "/projects/blueflyio%2Fagent-platform%2F$project/repository/tags" | jq -r '.[0].name')

  if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
    echo " $project: $ACTUAL_VERSION (expected $EXPECTED_VERSION)"
  else
    echo " $project: $ACTUAL_VERSION"
  fi
done

Update Dependency Versions

#!/bin/bash
# update-core-deps.sh

CORE_VERSION=$1

# Update package.json dependencies
jq ".dependencies[\"@agent-platform/core\"] = \"$CORE_VERSION\"" package.json > package.json.tmp
mv package.json.tmp package.json

# Install new version
npm install

# Commit
git add package.json package-lock.json
git commit -m "chore(deps): update core to $CORE_VERSION"

Resources

• Monorepo Versioning Strategies
• Polyrepo Versioning
• Changesets Documentation
• Lerna Documentation

See Also

• Semantic Versioning
• Automated Version Bumping
• Release Branches
• GitLab Releases
• Conventional Commits