Skip to main content

Versioning & Updates

How Versioning Works​

AuthProxy and other ItBuild modules follow a snapshot-based versioning model that gives you maximum control over stability.

Key Concepts​

Build = Current Version Snapshot

When you request a module build, you receive whatever version is currently in the platform's master branch:

You request: "Please build AuthProxy for my project"
You receive: AuthProxy 2.6.0 (current version in master)

You CANNOT request: "Build AuthProxy 2.5.0"
Platform does NOT build old versions

You Accumulate Versions Over Time

As you request builds at different times, you accumulate version snapshots:

January: Request build → Receive AuthProxy 2.4.0 (master was at 2.4.0)
February: Request build → Receive AuthProxy 2.5.0 (master was at 2.5.0)
March: Request build → Receive AuthProxy 2.6.0 (master was at 2.6.0)

Your project directory:
/projects/your-project/AuthProxy/
├── 2.4.0/  # Snapshot from January
├── 2.5.0/  # Snapshot from February
└── 2.6.0/  # Snapshot from March

You can USE any of these versions

Version Independence​

Your Development is Decoupled from Platform Releases​

Critical Advantage: Platform can release new versions, but your project isn't affected until YOU decide to request a new build.

Platform Timeline:
Week 1: Releases AuthProxy 2.5.0
Week 2: Releases AuthProxy 2.6.0
Week 3: Releases AuthProxy 2.7.0
Week 4: Releases AuthProxy 3.0.0 (breaking changes!)

Your Project:
Week 1-4: Still using AuthProxy 2.4.0 ✅
         Your development continues normally
         Nothing breaks
         Complete stability

You decide WHEN to upgrade:

  • ✅ Upgrade when YOU need new features
  • ✅ Test new versions on YOUR schedule
  • ✅ Deploy when YOUR team is ready
  • ❌ NO forced upgrades
  • ❌ NO surprise breaking changes

Version Selection Strategies​

Conservative (Maximum Stability)​

Approach:

  • Request builds: Every 2-3 months
  • Testing period: 2-4 weeks
  • Versions behind: 1-2 versions

Best for:

  • Production-critical systems
  • Regulated industries (finance, healthcare)
  • Small teams with limited testing capacity

Example:

Production:
  AuthProxy: 2.4.0    # Proven stable for 3 months
  TrexWallet: 1.2.0   # No issues reported
  Core: 1.0.5         # Your latest

Strategy: "If it works, don't touch it"

Approach:

  • Request builds: Monthly
  • Testing period: 1-2 weeks
  • Versions behind: 0-1 versions

Best for:

  • Most production systems
  • Teams with staging environment
  • Active development projects

Example:

Production:
  AuthProxy: 2.5.0    # Previous month's version, well tested
  TrexWallet: 1.2.0   # Stable
  Core: 1.0.5         # Your latest

Staging:
  AuthProxy: 2.6.0    # Testing this month's version
  TrexWallet: 1.2.0   # Same as production
  Core: 1.0.6         # Your development

Aggressive (Cutting Edge)​

Approach:

  • Request builds: Weekly/bi-weekly
  • Testing period: Few days
  • Versions behind: 0 (always latest)

Best for:

  • Development environments
  • New projects (not in production yet)
  • Teams with strong QA

Example:

Development:
  AuthProxy: 2.6.0    # Latest from platform
  TrexWallet: 1.3.0   # Latest from platform
  Core: 1.0.6-dev     # Your development

Version Mixing (Контуры)​

You Can Mix Different Module Versions​

Each module version is independent. You can combine them freely:

# Scenario: Testing new AuthProxy, keeping TrexWallet stable

Production:
  AuthProxy: 2.5.0      # Stable, proven
  TrexWallet: 1.2.0     # No need to change
  Core: 1.0.5           # Your version

Staging:
  AuthProxy: 2.6.0      # Testing new OAuth feature
  TrexWallet: 1.2.0     # Same as production (isolated testing)
  Core: 1.0.5           # Same as production

Result: Test AuthProxy upgrade without affecting other modules

Benefits​

Gradual Migration:

Week 1: Upgrade AuthProxy 2.5.0 → 2.6.0
Week 2: Test, monitor
Week 3: Upgrade TrexWallet 1.2.0 → 1.3.0
Week 4: Test, monitor

Low risk, controlled upgrades

Fast Rollback:

Production: AuthProxy 2.6.0 has issue
Rollback: Switch to AuthProxy 2.5.0
Time: < 5 minutes
Other modules: Unaffected (TrexWallet, Core stay same)

Bug Isolation:

Problem occurs after upgrade
Test with different version combinations:
- AuthProxy 2.6.0 + TrexWallet 1.2.0 → Issue found
- AuthProxy 2.5.0 + TrexWallet 1.2.0 → No issue
Conclusion: Bug is in AuthProxy 2.6.0
Action: Rollback just AuthProxy

Requesting New Builds​

When to Request​

Good reasons:

  • ✅ Need specific new feature
  • ✅ Security patch released
  • ✅ Bug fix you need
  • ✅ Scheduled upgrade cycle
  • ✅ Performance improvements

Bad reasons:

  • ❌ "Just because" (no specific need)
  • ❌ FOMO (platform released new version)
  • ❌ Without testing plan

Request Process​

1. Review Changelog

Check what's changed since your current version:

Current version: AuthProxy 2.5.0
Available: AuthProxy 2.6.0

Changelog:
- Added OAuth 2.0 device flow ✅ You need this
- Performance improvements ✅ Nice to have
- Bug fixes ✅ Good
- BREAKING CHANGES ⚠️ None

Decision: Request build

2. Contact Platform Team

Request: "Please build latest AuthProxy for project customer123"
Platform: Builds current master (2.6.0)
Result: /projects/customer123/AuthProxy/2.6.0/

3. Test in Staging

# Deploy to staging
# Test OAuth feature
# Run integration tests
# Monitor for issues
# Duration: 1-2 weeks

If successful → Deploy to production
If issues → Stay on 2.5.0, report bugs

Version Pinning for Teams​

Problem: Inconsistent Versions​

Developer A: AuthProxy 2.5.0
Developer B: AuthProxy 2.6.0
CI/CD: AuthProxy 2.4.0
Staging: AuthProxy 2.5.0

Result: "Works on my machine" ❌

Solution: Pin Versions​

Create version configuration:

// config/module-versions.json
{
  "versions": {
    "AuthProxy": "2.5.0",
    "TrexWallet": "1.2.0",
    "Core": "1.0.5"
  },
  "environment": "production",
  "pinned": true,
  "updated": "2026-02-01"
}

Setup script uses pinned versions:

./scripts/setup-environment.sh

# Reads config/module-versions.json
# Creates docker-compose with correct versions
# Everyone uses same versions ✅

Update pins together:

# Team lead tests new versions
# Updates config/module-versions.json
git commit -m "pin: upgrade AuthProxy to 2.6.0"

# Team pulls changes
# Everyone upgrades together ✅

Handling Breaking Changes​

You Control When to Handle Them​

Platform releases breaking change:

Platform: "AuthProxy 3.0.0 released - API header renamed"

Your project: Using AuthProxy 2.5.0
Impact: NONE ✅

Your timeline:
Week 1: Review migration guide
Week 2: Plan code updates
Week 3-4: Update your Core module code
Week 5: Request AuthProxy 3.0.0 build
Week 6: Test in staging
Week 7: Deploy to production

You handled breaking change on YOUR schedule

Migration Guide Available​

Platform provides detailed migration guides for breaking changes. Concrete examples below use the real header set — AuthProxy injects identity through X-Crm (CRM id), X-AppId, X-Pkey-Crm, X-KeyType, X-Scopes, X-Country, X-Project. No X-User-Id / X-UserId header is forwarded; integrators must read identity from X-Crm.

# Migration Guide: v2.x → v3.0.0

## Breaking Changes

### Scope behaviour split
Changed: `X-Scopes` was a free string, now it is a comma-separated canonical list.

## Your Action Required

Update your Core module:
:::note[Implementation detail]
Source-level examples and database statements are maintained in the module repositories. This public page describes the operational contract and configuration intent.
:::

Test before production ✅

Version Documentation​

Track Your Versions​

Create versions.md in your project:

# Module Versions

## Production
Updated: 2026-02-01

| Module | Version | Notes |
|--------|---------|-------|
| AuthProxy | 2.5.0 | Stable, proven |
| TrexWallet | 1.2.0 | No issues |
| Core | 1.0.5 | Latest |

## Staging
Updated: 2026-02-15

| Module | Version | Notes |
|--------|---------|-------|
| AuthProxy | 2.6.0 | Testing OAuth |
| TrexWallet | 1.2.0 | Same as prod |
| Core | 1.0.6 | Testing |

## Version History

### 2026-02-15: Tested AuthProxy 2.6.0
- OAuth feature working
- Performance improved
- All tests passing
- Ready for production

### 2026-02-01: Production deploy
- Initial stable versions
- All modules tested together

Benefits​

  • ✅ Clear record of deployments
  • ✅ Audit trail
  • ✅ Troubleshooting reference
  • ✅ Team knowledge base

Compatibility Matrix​

Check Before Mixing​

Not all version combinations work together. Check compatibility:

AuthProxy 2.6.0:
  Compatible with TrexWallet: 1.2.0, 1.3.0 ✅
  Compatible with Core: Any (no breaking changes) ✅

AuthProxy 3.0.0:
  Requires TrexWallet: 1.3.0+ ⚠️
  Requires Core update: Yes (X-Scopes parsing change) ⚠️

Example - Compatible:

AuthProxy: 2.6.0
TrexWallet: 1.2.0
# Identity forwarded as X-Crm + X-Scopes ✅

Example - Incompatible:

AuthProxy: 3.0.0
TrexWallet: 1.2.0
# AuthProxy emits X-Scopes as comma-separated list
# TrexWallet 1.2.0 still parses it as a free string
# → Permission checks may fail ❌
# Need to upgrade TrexWallet to 1.3.0

Best Practices​

Do​

  • ✅ Request builds only when needed (not "just because")
  • ✅ Test in staging first (1-2 weeks minimum)
  • ✅ Pin versions for team (consistent environments)
  • ✅ Document what you use (versions.md)
  • ✅ Keep 2-3 recent versions (rollback capability)
  • ✅ Review changelogs (know what's changing)
  • ✅ Plan upgrades (schedule, testing, rollback)

Don't​

  • ❌ Auto-upgrade without testing (risky)
  • ❌ Mix incompatible versions (check compatibility)
  • ❌ Delete versions in use (check all environments first)
  • ❌ Upgrade during critical periods (wait for stable time)
  • ❌ Skip staging testing (find issues before production)
  • ❌ Forget to document (track what's deployed)

Summary​

Key Takeaways​

1. Builds = Current Master Snapshots

  • You get whatever version is in master NOW
  • You cannot request old versions
  • You accumulate versions over time

2. You Control Upgrade Timing

  • Platform releases don't affect you immediately
  • Upgrade on YOUR schedule
  • Test before production
  • NO forced upgrades

3. Mix Versions Freely

  • Each module is independent
  • Test one module at a time
  • Fast rollback of single module
  • Gradual migration

4. Development Stability

  • Your work doesn't break from platform releases
  • You control when to handle breaking changes
  • Pin versions for team consistency
  • Focus on your features, not fighting updates

Result​

Maximum stability + Control = Productive development

You're not at the mercy of platform release cycles. You upgrade when YOU'RE ready, test at YOUR pace, and deploy on YOUR schedule.

This is a critical advantage of the ItBuild Platform architecture.

See Also​