Model Versioning and Registries

By Khimananda Oli | Last reviewed: August 2026

Shipping machine learning to production without structured model versioning and registries is a reliability risk that compounds with every retrain. Unlike application code managed in Git, ML systems comprise three distinct moving parts: code, data, and parameters, all of which must be pinned together to guarantee reproducibility. A dedicated registry acts as the single source of truth for this triad, enabling safe rollbacks, audit trails, and consistent deployments across environments. This guide covers the engineering patterns required to implement a registry that survives real-world production constraints.

What Are Model Versioning and Registries in Production MLOps?

In traditional software engineering, version control is solved. In MLOps, it is merely the starting point. When we discuss model versioning and registries, we are distinguishing between two related but distinct concepts. Versioning is the act of assigning a unique identifier to a specific state of a model artifact. The registry is the infrastructure that stores that artifact, enforces immutability, and manages its lifecycle transitions (e.g., Staging → Production).

A common mistake I see in teams transitioning from research to production is treating object storage like S3 or MinIO as a registry. While these tools store files, they lack semantic understanding of ML artifacts. A true registry understands that model-v2.1.bin was trained on dataset-v4.parquet using scikit-learn==1.5.0. Without this lineage, debugging a regression in production becomes a forensic archaeology project. For teams building RAG systems or fine-tuning LLMs, this distinction is even more critical; see my guide on building RAG chatbots for product documentation where embedding model versions directly impact retrieval quality.

The registry serves as the interface between data scientists who produce models and platform engineers who deploy them. It abstracts away physical storage paths. Instead of deploying s3://bucket/models/2026/08/final_v3.pt, your CI/CD pipeline deploys [email protected]. This abstraction layer is what makes MLOps distinct from standard DevOps; the artifact has internal structure and external dependencies that must be validated before promotion.

How Do You Implement Semantic Versioning for ML Artifacts?

Adopting Semantic Versioning (SemVer) for ML requires adapting the Major.Minor.Patch convention to statistical reality. Code changes are deterministic; model changes are probabilistic. Here is the schema I recommend for production systems in 2026:

• Major: Breaking API changes in input/output schema, or a fundamental architecture change (e.g., switching from XGBoost to Transformer). Requires downstream service updates.
• Minor: Retraining on new data with the same architecture and schema. Performance metrics may shift, but the contract remains identical.
• Patch: Metadata corrections, quantization optimizations, or hotfixes to preprocessing logic that do not alter predictions significantly.

Crucially, versioning must be automated. Never allow manual renaming of model files. Use your CI pipeline or training orchestrator to stamp versions based on git tags or pipeline run IDs. When working with large language models, the version string should also encode the base model hash and adapter LoRA rank. If you are self-hosting LLMs, pinning the exact GGUF or SafeTensor checksum is mandatory to prevent silent supply chain attacks or performance drift during hardware migrations.

Enforcing Immutability

A registry entry must be immutable. Once v1.2.0 is published, it cannot be overwritten. If a bug is found in the artifact, you publish v1.2.1. Overwriting destroys your ability to reproduce past results and violates SOC 2 audit requirements for change management. Configure your underlying object storage with WORM (Write Once, Read Many) policies or versioning enabled at the bucket level to enforce this technically, not just procedurally.

Which Model Registry Tools Fit Your Infrastructure Stack?

Choosing a registry depends heavily on your existing cloud commitment, compliance needs, and team size. There is no universal best option, only trade-offs. Below is a comparison of the dominant options in 2026 based on real implementation experience.

For teams in Nepal or regions with strict data residency requirements, self-hosted MLflow or ZenML on local infrastructure or sovereign cloud providers is often the only viable path. Cloud-managed registries simplify operations but lock you into vendor APIs. If you anticipate multi-cloud deployment or need to pass ISO 27001 audits with evidence stored locally, prioritize tools that treat the registry as a portable metadata layer over standard object storage.

How Do You Automate Model Registration in CI/CD Pipelines?

Manual registration is a failure point. Your CI pipeline should register the model immediately after successful evaluation. Below is a practical pattern using Python and MLflow within a GitHub Actions or GitLab CI job. This assumes you have already configured remote tracking.

<!-- Example: Registering a model after validation -->
import mlflow
from mlflow.tracking import MlflowClient

client = MlflowClient()
run_id = os.environ["MLFLOW_RUN_ID"]
model_uri = f"runs:/{run_id}/model"

# Validate metrics against threshold before registering
metrics = client.get_run(run_id).data.metrics
if metrics["val_f1_score"] < 0.85:
    raise ValueError("F1 score below production threshold")

# Register with explicit version alias
result = mlflow.register_model(model_uri, "fraud-detection-xgb")

# Tag with commit SHA for traceability
client.set_model_version_tag(
    name="fraud-detection-xgb",
    version=result.version,
    key="git_sha",
    value=os.environ["GITHUB_SHA"]
)

print(f"Registered version {result.version}")

This script enforces a quality gate before registration. Never register failed experiments. In regulated environments, add a step to generate and attach a model card or SBOM (Software Bill of Materials) to the registry entry. This aligns with the practices discussed in adding AI code review to CI pipelines, extending the same rigor from code to artifacts.

Handling Large Artifacts

For LLMs or diffusion models exceeding 10GB, avoid storing weights directly in the registry database. Store weights in object storage with content-addressable naming (SHA-256 hash), and store only the pointer and metadata in the registry. This deduplicates identical checkpoints across fine-tunes and keeps registry queries fast. Ensure your download scripts verify checksums before loading to prevent corruption-induced hallucinations.

How Does Model Versioning Enable Safe Rollbacks and Compliance?

The primary operational value of a registry is instant, deterministic rollback. When monitoring detects drift or a business KPI drops, you should be able to revert to the previous stable version in seconds, not hours. This requires your serving infrastructure to resolve versions dynamically.

Configure your inference servers (Triton, TorchServe, or custom FastAPI) to pull models by alias (champion) rather than version number. When rolling back, you simply reassign the champion alias to the previous version in the registry. The serving layer picks up the change via webhook or polling. This decouples deployment actions from infrastructure changes.

From a compliance perspective, the registry provides the audit trail that SOC 2 and ISO 27001 auditors demand. They will ask: "Show me exactly which model served predictions on July 15th and what data trained it." With proper versioning, this is a database query. Without it, you are reconstructing history from Slack messages and bash history. Automated evidence collection for compliance should hook directly into registry events, logging every promotion and deprecation to your SIEM or compliance platform.

Implementing Model Versioning and Registries Today

Start simple. Do not build a custom registry from scratch unless you have unique constraints that existing tools cannot meet. Pick MLflow for portability or your cloud provider's native tool for integration depth. Define your versioning schema before training your next model. Integrate registration into your CI pipeline as a blocking step. Most importantly, test your rollback procedure quarterly; a registry you have never used to recover from an incident is just expensive shelfware. Effective model versioning and registries transform ML from experimental art into reliable engineering. If your team needs help designing an audit-ready MLOps platform or integrating registries with existing infrastructure, reach out to discuss your architecture.