> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyleeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server Versions

> Understanding server versions and how to manage them in Pylee

# Server Versions

Server versions allow you to track and manage different releases of your MCP servers over time. This enables you to maintain multiple versions of a server for different environments, rollback to previous versions, and coordinate deployments across your organization.

## What are Server Versions?

Server versions are numbered releases of your MCP servers that provide:

* **Version Control**: Track changes and evolution of your servers
* **Environment Management**: Deploy different versions to different environments
* **Rollback Capability**: Quickly revert to previous working versions
* **Team Coordination**: Share specific versions across your organization
* **Release Management**: Organize and document server releases

## Version Numbering

Pylee uses semantic versioning (semver) for server versions:

### Semantic Versioning Format

```
MAJOR.MINOR.PATCH
```

* **MAJOR**: Incompatible API changes
* **MINOR**: Backwards-compatible functionality additions
* **PATCH**: Backwards-compatible bug fixes

### Examples

* `1.0.0` - Initial release
* `1.0.1` - Bug fix release
* `1.1.0` - New feature release
* `2.0.0` - Breaking changes release

### Version Suggestions

When creating a new server version, Pylee automatically suggests the next logical version number based on your existing versions:

* If no versions exist: `1.0.0`
* For patch updates: increment the patch number (e.g., `1.0.0` → `1.0.1`)
* For minor updates: increment the minor number (e.g., `1.0.5` → `1.1.0`)
* For major updates: increment the major number (e.g., `1.5.3` → `2.0.0`)

## Creating Server Versions

### Prerequisites

Before creating a server version, ensure you have:

* A server registered in your organization
* Appropriate permissions to create versions
* Your server code ready for release

### Version Creation Process

1. **Navigate to Server**: Go to your server's page in the Pylee dashboard
2. **Create New Version**: Click "Create New Version" or navigate to the versions section
3. **Select Organization**: Choose which organization will own this version
4. **Enter Version Number**: Provide a semantic version number
5. **Review and Create**: Confirm the version details and create

### Version Validation

Pylee validates version numbers to ensure:

* **Unique Versions**: No duplicate versions within the same organization
* **Valid Format**: Follows semantic versioning conventions
* **Logical Progression**: Versions make sense in sequence

## Managing Server Versions

### Version Listing

View all versions of a server with details including:

* Version number
* Release date
* Organization ownership
* Current deployment status

### Version Comparison

Compare different versions to understand:

* Changes between versions
* Feature additions or removals
* Configuration differences
* Performance improvements

### Version Metadata

Each version stores important metadata:

* **Creation Date**: When the version was created
* **Creator**: Who created the version
* **Organization**: Which organization owns it
* **Release Notes**: Documentation of changes
* **Deployment Status**: Where it's currently deployed

## Version Deployment

### Environment-Specific Deployment

Deploy different versions to different environments:

```json theme={null}
{
  "environments": {
    "development": {
      "server": "my-server",
      "version": "1.2.0-beta.1"
    },
    "staging": {
      "server": "my-server",
      "version": "1.1.5"
    },
    "production": {
      "server": "my-server",
      "version": "1.1.4"
    }
  }
}
```

### Gradual Rollout

Implement gradual rollouts:

1. **Development**: Deploy and test new version
2. **Staging**: Validate in staging environment
3. **Canary**: Deploy to small subset of production
4. **Production**: Full production deployment

### Rollback Strategy

Quickly rollback to previous versions:

* **Immediate Rollback**: Revert to last known good version
* **Selective Rollback**: Rollback specific environments
* **Staged Rollback**: Gradually rollback across environments

## Version Organization

### Multi-Organization Support

Server versions can be owned by different organizations:

* **Shared Servers**: Multiple organizations using the same server
* **Organization-Specific Versions**: Custom versions for specific organizations
* **Version Inheritance**: Base versions with organization-specific modifications

### Organization Context

When creating versions, consider:

* **Target Organization**: Which organization will own the version
* **Access Permissions**: Who can deploy and manage the version
* **Resource Allocation**: Organization-specific resource limits

## Best Practices

### Version Naming

Follow consistent naming conventions:

* Use semantic versioning
* Include pre-release identifiers when appropriate
* Consider branch-based versioning for development

### Release Planning

Plan your releases effectively:

* **Feature Branches**: Develop features in separate branches
* **Version Branches**: Maintain stable version branches
* **Hotfix Branches**: Quick fixes for production issues

### Documentation

Document your versions thoroughly:

* **Release Notes**: What changed in each version
* **Migration Guides**: How to upgrade between versions
* **Breaking Changes**: Incompatible changes and workarounds

### Testing Strategy

Test versions comprehensively:

* **Unit Tests**: Test individual components
* **Integration Tests**: Test server integration
* **Performance Tests**: Validate performance characteristics
* **Compatibility Tests**: Ensure backwards compatibility

## Version Lifecycle

### Development Phase

* Create development versions
* Test new features and fixes
* Iterate based on feedback

### Release Phase

* Create release candidate versions
* Perform final testing
* Create stable release version

### Maintenance Phase

* Monitor version performance
* Apply security patches
* Plan deprecation timeline

### Deprecation Phase

* Announce deprecation timeline
* Provide migration path
* Remove deprecated versions

## Advanced Features

### Version Tagging

Use tags to mark special versions:

* `latest` - Most recent stable version
* `lts` - Long-term support version
* `beta` - Beta release version
* `alpha` - Alpha release version

### Version Branching

Maintain multiple version branches:

* **Master Branch**: Latest development
* **Release Branches**: Stable releases
* **Hotfix Branches**: Critical fixes

### Version Automation

Automate version management:

* **CI/CD Integration**: Automatic version creation
* **Deployment Automation**: Automated deployment pipelines
* **Version Monitoring**: Monitor version health

## Troubleshooting

### Version Creation Issues

Common problems and solutions:

* **Duplicate Version**: Choose a different version number
* **Invalid Format**: Use semantic versioning format
* **Permission Denied**: Ensure you have version creation permissions

### Deployment Issues

Resolve deployment problems:

* **Version Not Found**: Verify version exists and is accessible
* **Compatibility Issues**: Check version compatibility
* **Resource Conflicts**: Resolve resource allocation conflicts

### Performance Issues

Optimize version performance:

* **Version Size**: Keep versions lightweight
* **Startup Time**: Optimize server startup
* **Memory Usage**: Monitor memory consumption

## Integration with CI/CD

### Automated Version Creation

Integrate with your CI/CD pipeline:

```yaml theme={null}
name: Create Version
on:
  push:
    tags:
      - 'v*'

jobs:
  create-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Create Pylee Version
        run: |
          pylee server version create \
            --server=${{ env.SERVER_NAME }} \
            --version=${{ github.ref_name }} \
            --organization=${{ env.ORG_ID }}
```

### Deployment Automation

Automate version deployment:

```yaml theme={null}
name: Deploy Version
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy'
        required: true
      environment:
        description: 'Target environment'
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy Version
        run: |
          pylee server deploy \
            --server=${{ env.SERVER_NAME }} \
            --version=${{ inputs.version }} \
            --environment=${{ inputs.environment }}
```

## Security Considerations

### Version Access Control

Control access to versions:

* **Read Permissions**: Who can view versions
* **Write Permissions**: Who can create versions
* **Deploy Permissions**: Who can deploy versions

### Version Signing

Sign versions for integrity:

* **Digital Signatures**: Verify version authenticity
* **Checksum Validation**: Ensure version integrity
* **Audit Trail**: Track version changes

### Sensitive Data

Protect sensitive information:

* **Environment Variables**: Secure configuration
* **API Keys**: Protect authentication credentials
* **Database Connections**: Secure database access

## Migration and Upgrades

### Version Migration

Migrate between versions safely:

1. **Backup Current State**: Save current configuration
2. **Test Migration**: Test in non-production environment
3. **Execute Migration**: Apply version changes
4. **Verify Results**: Confirm migration success

### Upgrade Strategies

Choose appropriate upgrade strategies:

* **Blue-Green Deployment**: Zero-downtime upgrades
* **Rolling Updates**: Gradual version rollout
* **Canary Deployment**: Test with subset of traffic

## Monitoring and Observability

### Version Metrics

Monitor version performance:

* **Deployment Success Rate**: Track deployment success
* **Error Rates**: Monitor version-specific errors
* **Performance Metrics**: Track response times and throughput

### Health Checks

Implement version health checks:

* **Startup Checks**: Verify version starts correctly
* **Runtime Checks**: Monitor ongoing health
* **Dependency Checks**: Verify external dependencies

## Next Steps

* Learn about [Organizations](/understanding-pylee/organizations) to understand version ownership
* Explore [Servers](/understanding-pylee/servers) for server management basics
* Check [Variables](/understanding-pylee/variables) for version-specific configuration
* Review [Troubleshooting](/support/troubleshooting) for common issues