Verificando autenticación…

Skip to main content

Semantic Versioning in ANDES Pipelines

ANDES DX pipelines version your application automatically on every pipeline run. You don't need to create tags or write version numbers manually — the pipeline handles it following Semantic Versioning 2.0.0.

This guide is for developers using the standard language pipelines (golang-service, java-service, react-service, python-service).

Using components directly to build your own pipeline? See the Technical reference for code/version.

What happens in each pipeline​

Every merge to main produces a Release Candidate (RC). When you decide that RC is ready for production, you run the pipeline with the release_candidate input and a stable version is created.

The two moments of the version cycle​

1. Merge to main → Release Candidate​

Every time a MR is merged to main, the pipeline:

  1. Reads the version declared in your project.
  2. Generates a Git tag with a -rc.<pipeline_number> suffix — for example 1.4.2-rc.314.
  3. Publishes the image to the internal registry with that tag.
  4. Registers the release in GitLab.

This RC is internal — it does not go to production automatically.

Where does the image end up?

RC images are published to the project's internal GitLab registry. Stable images are promoted to the production registry. See Docker Images for available registries.

2. Pipeline with release_candidate → Stable version​

When the RC is validated and you want to release to production:

  1. Go to GitLab → CI/CD → Run pipeline on the main branch.
  2. Add the variable release_candidate with the Jira ticket for the change — for example ANDES-1234. The ticket links the technical release to the business decision that authorizes it. The full process is described in Release to production.
  3. Run the pipeline.

The pipeline:

  1. Promotes the image from the internal registry to the production registry.
  2. Creates the stable Git tag — for example 1.4.2 (or v1.4.2 for Go projects).
  3. Publishes the GitLab release with notes from CHANGELOG.md.
  4. Deletes all RC tags for that version (1.4.2-rc.*).
The Jira ticket is not optional

Without a valid ticket in release_candidate, the promotion step does not run and the pipeline fails. The expected format is PROJECT-NNN — for example ANDES-1234.

How the pipeline knows your version​

The pipeline detects the version from your project file based on the language:

StackPrimary source
GoStable Git tags on the commit → CHANGELOG.md
Javagradle.properties → pom.xml → build.gradle
React / Nodepackage.json ("version" field)
Pythonpyproject.toml → setup.cfg → setup.py

That base version is the VERSION_CORE — for example 1.4.2. The pipeline appends the channel suffix (-rc.314) and build metadata to form the final version.

Keep your project version up to date

If you don't update the version number in your manifest before releasing, the pipeline will keep using the same base version even if the code has changed. Update the version before making the merge you want to turn into a stable release.

Tags produced by the pipeline​

ChannelExample (Go)Example (other stacks)
RCv1.4.2-rc.3141.4.2-rc.314
Stablev1.4.21.4.2

Go projects use the v prefix because the Go module system requires it — go get and go mod resolve versions by Git tags and expect the vX.Y.Z format. The golang-service pipeline enables it automatically.

When you release a stable, the image in the registry also gets alias tags if it is the highest version in its series: 1.4.2, 1.4 and 1. This lets other services use :1.4 without updating their reference on every patch release.

Rules to follow​

Do not create version tags manually​

danger

Creating a Git tag with SemVer format (1.2.3 or v1.2.3) outside the pipeline may cause the next pipeline run to fail due to a version collision. All tag management is done by the pipeline.

CHANGELOG.md must have an entry for your version​

On main and MRs targeting main, the pipeline validates that CHANGELOG.md has a ## [X.Y.Z] entry with content matching the current VERSION_CORE. If the entry is missing or empty, the pipeline fails before publishing anything.

An empty heading also fails — the entry must have at least one line of content.

A stable version is permanent​

Once the stable tag 1.4.2 is created, that version is locked to that commit. If you need to fix something in production:

  1. Fix it on main.
  2. Bump the version in your manifest (1.4.2 → 1.4.3).
  3. Merge → 1.4.3-rc.N is generated → then release 1.4.3.

Frequently asked questions​

What happens if I re-run the pipeline on the same commit?

The pipeline detects that the RC tag already exists on that commit and does not create a new one — the run is idempotent. If the RC tag exists on a different commit, the pipeline fails to avoid collision.

Can I have 1.4.2-rc.N and 1.5.0-rc.N at the same time?

Yes. Each VERSION_CORE is independent. RC tags for older versions remain until you release their stable counterpart.

Does the RC go to production automatically?

No. The RC stays in the internal registry. Only the stable version reaches the production registry. See Release to production.

Can I override the detected version?

Yes, with the package_version input. See Direct component usage.

Next step​

When your RC is validated, follow the Release to production process to manage the change and release the stable version.