Understanding Cosign Key Trust in Harbor and How to Use revision_id for Model Versioning

In modern DevSecOps pipelines, Cosign is the go‑to tool for signing container images, while Harbor acts as a trusted registry that validates those signatures. Learners often wonder how Harbor can “trust” a key that you generate on your own laptop, and they also encounter the revision_id field when working with AI/ML models in labs. This article demystifies both concepts, explains the underlying mechanics, and shows you where to find the exact revision_id for a model hosted on Hugging Face.

Table of Contents

1. Why Does Harbor Trust a Self‑Signed Cosign Key?

2. How Cosign Signing Works – A Quick Walkthrough

3. What Is revision_id and Why It Matters

4. Locating the revision_id of a Hugging Face Model

5. Practical Example: Signing an Image and Pinning a Model Version

6. Common Questions & Tips

Why Does Harbor Trust a Self‑Signed Cosign Key?

Even though the key pair you generate with Cosign is technically self‑signed (there is no external certificate authority), Harbor can still verify signatures because trust is established by explicit key registration, not by a third‑party issuer.

Key Points

• Ownership Declaration: By uploading the public key to Harbor, you tell the registry, “I am the owner of the matching private key.”

• Private Key Confidentiality: The private key never leaves your workstation; it is used only to create signatures.

• Verification Only: Harbor uses the stored public key solely to verify that a signature was produced by the corresponding private key. It cannot generate new signatures.

• Policy Enforcement: Harbor can be configured with policies (e.g., “only accept images signed with keys listed in the trusted‑key store”). As long as the public key appears in that store, any image signed with the matching private key is accepted.

Think of the public key like a government‑issued ID that you present at an airport. The ID isn’t “signed” by a separate authority, but the airport trusts it because it follows a known verification process.

How Cosign Signing Works – A Quick Walkthrough

1. Generate a key pair on your development machine

   cosign generate-key-pair
   

   • cosign.key → private key (kept secret)

   • cosign.pub → public key (shared with Harbor)

2. Upload the public key to Harbor

   • In the Harbor UI, navigate to Administration → Interoperability → Notary V2 (or the “Signature Trust” section) and add cosign.pub.

3. Sign a container image

   cosign sign -key cosign.key myregistry.example.com/myapp:1.2.3
   

4. Push the signed image to Harbor. Harbor automatically verifies the signature using the stored public key.

If the verification succeeds, the image is marked as trusted and can be promoted through your CI/CD pipeline.

What Is revision_id and Why It Matters

When you work with pre‑trained models from platforms like Hugging Face, the underlying model files can change over time (bug fixes, new weights, licensing updates). To guarantee reproducibility in labs and exams, you need a stable reference to a specific version of the model.

• revision_id: A unique identifier (usually a Git commit SHA) that pins the model to an exact snapshot in the repository.

• Why pin it?

  • Prevents breaking changes when the model author pushes updates.

  • Ensures that every learner runs the same code and gets identical inference results.

  • Makes debugging easier because the exact code base is known.

In practice, you add revision_id to your requirements.txt, Dockerfile, or pipeline configuration to lock the model version.

Locating the revision_id of a Hugging Face Model

1. Open the model’s page on huggingface.co (e.g., https://huggingface.co/facebook/opt-125m).

2. Click the “Files and versions” tab.

3. Locate the commit hash displayed near the top of the file list – this is the revision_id. It looks like a 40‑character string, e.g., a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0.

4. Use that string in your code:

   from transformers import AutoModelForCausalLM, AutoTokenizer
   
   model_name = "facebook/opt-125m"
   revision_id = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
   
   tokenizer = AutoTokenizer.from_pretrained(model_name, revision=revision_id)
   model = AutoModelForCausalLM.from_pretrained(model_name, revision=revision_id)
   

Tip: Some repositories also expose the revision_id via the API endpoint https://huggingface.co/api/models/<repo_id>. Look for the sha field in the JSON response.

Practical Example: Signing an Image and Pinning a Model Version

Below is a concise end‑to‑end scenario that combines both concepts:

# 1️⃣ Generate Cosign keys (once per developer)
cosign generate-key-pair -output-key cosign.key

# 2️⃣ Register the public key in Harbor (UI step)

# 3️⃣ Build a Docker image that includes a specific model version
cat > Dockerfile <<'EOF'
FROM python:3.11-slim
RUN pip install torch transformers
ENV MODEL_NAME=facebook/opt-125m
ENV REVISION_ID=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
RUN python - <<PY
from transformers import AutoModelForCausalLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("$MODEL_NAME", revision="$REVISION_ID")
model = AutoModelForCausalLM.from_pretrained("$MODEL_NAME", revision="$REVISION_ID")
print("Model loaded successfully")
PY
EOF

docker build -t myregistry.example.com/nlp/opt:latest .
docker push myregistry.example.com/nlp/opt:latest

# 4️⃣ Sign the image
cosign sign -key cosign.key myregistry.example.com/nlp/opt:latest

• Result: Harbor verifies the signature using the public key you uploaded.

• Result: All learners pulling myregistry.example.com/nlp/opt:latest will use the exact same model snapshot defined by revision_id.

Common Questions & Tips

Quick Tips

• Store your private key in a secret manager (e.g., HashiCorp Vault, Azure Key Vault) rather than on disk.

• Version‑control your revision_id in a versions.yaml file so that updates are auditable.

• Enable Harbor’s “signature enforcement” policy to reject unsigned images automatically.

• Validate the model checksum (e.g., SHA256) after download to catch any tampering beyond the revision_id.

Wrap‑Up

Harbor’s trust model for Cosign hinges on explicit public‑key registration, not on traditional certificate authorities. By keeping the private key secret and sharing the public key with Harbor, you create a reliable chain of trust for your container images.

Meanwhile, the revision_id field is your safety net for AI/ML model reproducibility, allowing you to lock in an exact commit from Hugging Face (or any Git‑backed model hub). Knowing where to locate the SHA and how to embed it in your pipelines ensures that every learner, auditor, or production system works with the same model version, eliminating “it works on my machine” surprises.

Armed with these concepts, you can confidently build secure, reproducible DevSecOps labs that combine signed container images with pinned model versions—key ingredients for modern, trustworthy software delivery.