> ## 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.

# Versions

> Understanding versions in Pylee and how they enable version control for your MCP servers

# Versions

Versions are fundamental to managing your MCP servers in Pylee. They provide a structured way to track, deploy, and manage different releases of your servers across environments.

## What are Versions?

Versions in Pylee represent specific releases or iterations of your MCP servers. They enable:

* **Change Tracking**: Monitor evolution of your servers over time
* **Environment Management**: Deploy different versions to different environments
* **Rollback Capability**: Quickly revert to previous working versions
* **Team Collaboration**: Share specific versions across your organization
* **Release Management**: Organize and document server releases

## Version Types

### Server Versions

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

* **Source Code**: The actual server implementation
* **Configuration**: Server-specific settings and parameters
* **Dependencies**: Required packages and remotes
* **Environment**: Variables and secrets needed for operation

[Learn more about Server Versions →](/understanding-pylee/server-versions)

### Registry Versions

Registry versions track different releases of packages and servers in your organization's registry:

* **Package Versions**: Different releases of reusable packages
* **Server Templates**: Versioned server configurations
* **Shared Resources**: Common utilities and libraries

## Version Lifecycle

### 1. Development Phase

* Create development versions for testing
* Iterate on features and fixes
* Validate changes in development environment

### 2. Release Phase

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

### 3. Deployment Phase

* Deploy to staging environment
* Validate in production-like conditions
* Roll out to production

### 4. Maintenance Phase

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

## Version Numbering

Pylee uses semantic versioning (semver) for consistent version management:

### Format

```
MAJOR.MINOR.PATCH
```

### Examples

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

### Pre-release Versions

* `1.0.0-alpha.1` - Alpha release
* `1.0.0-beta.1` - Beta release
* `1.0.0-rc.1` - Release candidate

## Creating Your First Version

### Prerequisites

Before creating a version, ensure you have:

1. **Server Registered**: Your server must be registered in Pylee
2. **Proper Permissions**: You need version creation permissions
3. **Code Ready**: Your server code is ready for release

### Step-by-Step Guide

1. **Navigate to Server**: Go to your server's page in Pylee
2. **Create Version**: Click "Create New Version"
3. **Enter Details**: Provide version number and release notes
4. **Configure**: Set up remotes, packages, and environment
5. **Deploy**: Create deployment to make version available

## Version Management Best Practices

### Naming Conventions

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

### Release Planning

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

### Documentation

* **Release Notes**: Document what changed in each version
* **Migration Guides**: Provide upgrade instructions
* **Breaking Changes**: Clearly identify incompatible changes

### Testing Strategy

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

## Version Deployment Strategies

### Environment-Specific Deployment

Deploy different versions to different environments:

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

### Gradual Rollout

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

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

## Version Configuration

### Server Configuration

Each version can have its own configuration:

* **Remotes**: HTTP endpoints for server communication
* **Packages**: Dependencies from npm, PyPI, Docker, Homebrew
* **Variables**: Environment-specific configuration
* **Secrets**: Secure storage of sensitive data

### Environment Variables

Configure environment-specific settings:

```json theme={null}
{
  "variables": {
    "API_BASE_URL": "https://api.example.com",
    "LOG_LEVEL": "info",
    "TIMEOUT": "30000"
  }
}
```

### Secrets Management

Securely store sensitive information:

```json theme={null}
{
  "secrets": {
    "API_KEY": "your-api-key",
    "DATABASE_URL": "your-database-connection-string",
    "JWT_SECRET": "your-jwt-secret"
  }
}
```

## Version Monitoring

### Performance Metrics

Monitor version performance:

* **Response Times**: Track API response times
* **Error Rates**: Monitor version-specific errors
* **Throughput**: Measure request handling capacity
* **Resource Usage**: Monitor CPU and memory usage

### Health Checks

Implement comprehensive health checks:

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

### Alerting

Set up alerts for version issues:

* **Error Rate Thresholds**: Alert on high error rates
* **Performance Degradation**: Alert on slow response times
* **Dependency Failures**: Alert on external service failures

## Version Security

### Access Control

Control who can manage versions:

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

### Vulnerability Management

Keep versions secure:

* **Dependency Scanning**: Scan for vulnerable dependencies
* **Security Patches**: Apply security updates promptly
* **Audit Trail**: Track all version changes

### Compliance

Ensure versions meet compliance requirements:

* **Data Protection**: Implement data protection measures
* **Access Logging**: Log all version access
* **Retention Policies**: Manage version retention

## 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 }}
```

### Deployment Automation

Automate version deployment:

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

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

## Troubleshooting

### Common Issues

**Version Creation Fails**

* Verify version number format
* Check permissions
* Ensure server exists

**Deployment Issues**

* Verify version exists
* Check environment configuration
* Validate dependencies

**Performance Problems**

* Monitor resource usage
* Check dependency health
* Optimize configuration

### Getting Help

* Check [Troubleshooting Guide](/support/troubleshooting)
* Review [Server Documentation](/understanding-pylee/servers)
* Contact support for assistance

## Next Steps

* Learn about [Server Versions](/understanding-pylee/server-versions) for detailed server versioning
* Explore [Deployments](/understanding-pylee/deployments) to deploy your versions
* Check [Variables](/understanding-pylee/variables) for environment configuration
* Review [Secrets](/understanding-pylee/secrets) for secure data management