3-3 · Chapter 3 · 5 min read

Why Every Artifact Needs a Name and a Number

Your team builds code every day. By Friday, you have seven different artifacts sitting in your repository. Nobody remembers which one was tested, which

Why Every Artifact Needs a Name and a Number

Your team builds code every day. By Friday, you have seven different artifacts sitting in your repository. Nobody remembers which one was tested, which one has the hotfix, and which one should go to production. Someone asks, "Which build do we deploy?" and the answer is a shrug.

This is the moment you realize that artifacts without clear naming are not artifacts at all. They are just files. Without a proper naming and numbering system, your pipeline produces noise instead of certainty.

The Problem of Unlabeled Artifacts

When artifacts have no clear identity, every deployment becomes a guessing game. Teams start relying on timestamps, folder names, or memory. "I think the build from Tuesday afternoon had the fix." That kind of thinking is dangerous. It leads to deploying the wrong version, rolling back to something that was never tested, or worse, deploying a broken artifact because nobody could tell which one was the latest.

The core issue is simple: if you cannot uniquely identify an artifact, you cannot reliably deploy it. And if you cannot reliably deploy, you cannot confidently release.

What Makes an Artifact Identifiable

Every artifact needs two things: a name and a number. The name tells you what the artifact is. The number tells you which version of that thing it is. Together, they create a unique identifier that everyone on the team can refer to without ambiguity.

The name is usually the application or component name. The number is the version. When you combine them, you get something like payment-service-2.1.3. That string points to exactly one artifact. Not the one from last week. Not the one with the similar name. Just that one.

Versioning Is Not Just for Show

Versioning is the system that gives meaning to the number part of your artifact identifier. It is not just a counter that goes up. A good versioning scheme tells you something about the artifact itself. It communicates the nature of the change, the risk level, and the relationship to previous versions.

The most widely used system is semantic versioning. It uses three numbers separated by dots: MAJOR.MINOR.PATCH. Each number has a specific meaning.

MAJOR increases when you make changes that break backward compatibility. If existing users need to change their code or workflow, that is a major version bump.
MINOR increases when you add new features that still work with the old way of doing things. Users can upgrade without breaking anything.
PATCH increases for bug fixes that do not introduce new features or break existing functionality.

When you see version 2.1.3, you know the application has gone through two major breaking changes, one feature addition, and three bug fixes. That is a lot of information packed into a small string.

Immutability Starts with Versioning

The version number is not just a label. It is a contract. Once an artifact is built and tagged with a version, that version should never change. If you rebuild the same code, you should get the same artifact. If something changes, the version must change.

This is what makes an artifact immutable. Version 2.1.3 always refers to the same binary, the same container image, the same package. It does not matter if you download it today, next week, or six months later. The artifact is identical. This certainty is what allows you to test something in staging, then deploy the exact same thing to production without surprises.

Versioning and Release Are Different Things

A common mistake is treating versioning and release as the same concept. They are not. Versioning is about labeling the artifact. Release is about deciding to make that artifact available to users.

You can build version 2.2.0-beta and deploy it to staging for testing. That version exists as an artifact, but it is not a release. After testing, you might decide to promote it to 2.2.0 and release it to production. Or you might find issues and build a 2.2.1 instead.

This separation gives you flexibility. You can build and version artifacts frequently, but only release when you are confident. The version number tracks the artifact's identity. The release decision tracks its readiness.

Practical Implications for Your Pipeline

Once you have a clear naming and versioning system, several things become easier.

Traceability becomes automatic. When a bug is reported in production, you look at the version running in that environment. You check what changes went into that version. You compare it with the previous stable version. All of this is possible because every artifact has a unique identifier that links back to the source code and build process.

Rollback becomes precise. You do not guess which version was working before. You know exactly which version was running last week, and you can deploy that same artifact again. Because the artifact is immutable, you are deploying the exact same binary, not a rebuild that might behave differently.

Communication becomes clearer. Instead of saying "deploy the latest build," you say "deploy payment-service 2.1.3 to production." Everyone knows exactly what that means. The DBA knows which database migration to expect. The QA team knows which tests were run. The operations team knows what to monitor.

A Simple Checklist for Artifact Naming

If you are setting up artifact naming for the first time, here is a short checklist to get started:

Every artifact has a name that matches the application or component name.
Every artifact has a version number that follows a consistent scheme.
The version number is assigned at build time and never changed afterward.
The artifact repository stores artifacts by name and version, not by timestamp or folder.
The team understands the difference between versioning (labeling) and release (making available).
The versioning scheme communicates the nature of changes (major, minor, patch).

The Takeaway

Artifact naming and versioning is not a bureaucratic exercise. It is the foundation of reliable deployment. Without it, your pipeline produces uncertainty. With it, every artifact has a clear identity, every deployment has a clear target, and every rollback has a clear destination. Name your artifacts. Number them consistently. Make them immutable. Then you can deploy with confidence.