From 2f42ab9ae8239bd7559c82bf6a2f7f65db6eaf05 Mon Sep 17 00:00:00 2001
From: Patryk Matuszak <pmatusza@redhat.com>
Date: Tue, 25 Nov 2025 17:56:19 +0100
Subject: [PATCH 1/5] Change USHIFT_BRANCH to USHIFT_REF

---
 .github/actions/build-deb/action.yaml      |  4 ++--
 .github/actions/build-okd/action.yaml      |  6 +++---
 .github/actions/build/action.yaml          |  4 ++--
 .github/workflows/builders.yaml            | 10 +++++-----
 .github/workflows/release-okd.yaml         |  6 +++---
 .github/workflows/release.yaml             | 14 +++++++-------
 Makefile                                   |  8 ++++----
 docs/build.md                              |  4 ++--
 packaging/microshift-builder.Containerfile |  4 ++--
 9 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/.github/actions/build-deb/action.yaml b/.github/actions/build-deb/action.yaml
index b619199f..8c7ccd88 100644
--- a/.github/actions/build-deb/action.yaml
+++ b/.github/actions/build-deb/action.yaml
@@ -2,7 +2,7 @@ name: build-deb-packages
 description: Reusable action to build MicroShift Debian packages
 
 inputs:
-  ushift-branch:
+  ushift-ref:
     description: MicroShift branch from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
@@ -40,7 +40,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_BRANCH=${{ inputs.ushift-branch }} \
+          USHIFT_REF=${{ inputs.ushift-ref }} \
           OKD_VERSION_TAG=${{ inputs.okd-version-tag }} \
           RPM_OUTDIR=/mnt/rpms
 
diff --git a/.github/actions/build-okd/action.yaml b/.github/actions/build-okd/action.yaml
index dcb126f8..7d89825e 100644
--- a/.github/actions/build-okd/action.yaml
+++ b/.github/actions/build-okd/action.yaml
@@ -2,7 +2,7 @@ name: build-okd-images
 description: Reusable action to build OKD images
 
 inputs:
-  ushift-branch:
+  ushift-ref:
     description: MicroShift branch from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
@@ -53,7 +53,7 @@ runs:
         cd ${GITHUB_WORKSPACE}/
         TARGET_REGISTRY="${{ inputs.target-registry }}" ./src/okd/build_images.sh \
           "${{ inputs.okd-version-tag }}" \
-          "${{ inputs.ushift-branch }}" \
+          "${{ inputs.ushift-ref }}" \
           "${{ inputs.target-arch }}"
 
     - name: Build MicroShift RPMs
@@ -65,7 +65,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_BRANCH="${{ inputs.ushift-branch }}" \
+          USHIFT_REF="${{ inputs.ushift-ref }}" \
           OKD_VERSION_TAG="${{ inputs.okd-version-tag }}" \
           OKD_RELEASE_IMAGE="${{ inputs.target-registry }}/okd-release-${{ steps.detect-cpu-arch.outputs.go_arch }}" \
           RPM_OUTDIR=/mnt/rpms
diff --git a/.github/actions/build/action.yaml b/.github/actions/build/action.yaml
index 3e7e81ad..45b3be02 100644
--- a/.github/actions/build/action.yaml
+++ b/.github/actions/build/action.yaml
@@ -2,7 +2,7 @@ name: build-microshift
 description: Reusable action to build MicroShift RPMs and container images
 
 inputs:
-  ushift-branch:
+  ushift-ref:
     description: MicroShift branch from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
@@ -51,7 +51,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_BRANCH="${{ inputs.ushift-branch }}" \
+          USHIFT_REF="${{ inputs.ushift-ref }}" \
           OKD_VERSION_TAG="${{ inputs.okd-version-tag }}" \
           RPM_OUTDIR=/mnt/rpms
 
diff --git a/.github/workflows/builders.yaml b/.github/workflows/builders.yaml
index 304e2ef7..af7a9d61 100644
--- a/.github/workflows/builders.yaml
+++ b/.github/workflows/builders.yaml
@@ -19,7 +19,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: main
+          ushift-ref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: quay.io/centos-bootc/centos-bootc
           bootc-image-tag: stream9
@@ -40,7 +40,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: main
+          ushift-ref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: quay.io/centos-bootc/centos-bootc
           bootc-image-tag: stream10
@@ -64,7 +64,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: main
+          ushift-ref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: registry.fedoraproject.org/fedora-bootc
           bootc-image-tag: 42
@@ -85,7 +85,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build-deb
         with:
-          ushift-branch: main
+          ushift-ref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
 
   isolated-network:
@@ -111,7 +111,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: main
+          ushift-ref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           isolated-network: 1
           ovnk-networking: ${{ matrix.ovnk-networking }}
diff --git a/.github/workflows/release-okd.yaml b/.github/workflows/release-okd.yaml
index b1016ed0..cc3bddab 100644
--- a/.github/workflows/release-okd.yaml
+++ b/.github/workflows/release-okd.yaml
@@ -6,7 +6,7 @@ on:
     - cron: '0 3 * * *'
   workflow_dispatch:
     inputs:
-      ushift-branch:
+      ushift-ref:
         default: "main"
         description: MicroShift branch from https://github.com/openshift/microshift/branches
         type: string
@@ -22,7 +22,7 @@ on:
 # The workflow dispatch inputs are not inherited by the scheduled workflow runs.
 # Use environment variables to pass the inputs to the build action.
 env:
-  USHIFT_BRANCH: ${{ github.event.inputs.ushift-branch || 'main' }}
+  USHIFT_REF: ${{ github.event.inputs.ushift-ref || 'main' }}
   OKD_VERSION_TAG: ${{ github.event.inputs.okd-version-tag || 'latest' }}
   OKD_TARGET_REGISTRY: ${{ github.event.inputs.okd-target-registry || 'ghcr.io/microshift-io/okd' }}
 
@@ -41,7 +41,7 @@ jobs:
       - name: Run the OKD release images build action
         uses: ./.github/actions/build-okd
         with:
-          ushift-branch: ${{ env.USHIFT_BRANCH }}
+          ushift-ref: ${{ env.USHIFT_REF }}
           okd-version-tag: ${{ env.OKD_VERSION_TAG != 'latest' && env.OKD_VERSION_TAG || steps.detect-okd-version.outputs.okd-version-tag }}
           target-arch: arm64
           target-registry: ${{ env.OKD_TARGET_REGISTRY }}
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 0a75666f..5a8420d9 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -7,7 +7,7 @@ name: release-packages-and-images
 on:
   workflow_dispatch:
     inputs:
-      ushift-branch:
+      ushift-ref:
         default: "main"
         description: MicroShift branch from https://github.com/openshift/microshift/branches
         type: string
@@ -46,7 +46,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: ${{ inputs.ushift-branch }}
+          ushift-ref: ${{ inputs.ushift-ref }}
           okd-version-tag: ${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           build: ${{ inputs.build }}
 
@@ -79,7 +79,7 @@ jobs:
         if: contains(fromJSON('["all", "packages"]'), inputs.build)
         uses: ./.github/actions/build-deb
         with:
-          ushift-branch: ${{ inputs.ushift-branch }}
+          ushift-ref: ${{ inputs.ushift-ref }}
           okd-version-tag: ${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           build-rpms: false
 
@@ -94,7 +94,7 @@ jobs:
         if: contains(fromJSON('["all", "packages"]'), inputs.build)
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ inputs.ushift-branch }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
+          tag_name: ${{ inputs.ushift-ref }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           files: |
             /mnt/release/microshift-rpms-*.tgz
             /mnt/release/microshift-debs-*.tgz
@@ -116,7 +116,7 @@ jobs:
 
           OKD_VERSION_TAG="${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}"
           TARGET_IMAGE="ghcr.io/${{ github.repository_owner }}/microshift"
-          TARGET_TAG="${{ inputs.ushift-branch }}-${OKD_VERSION_TAG}-${{ steps.detect-cpu-arch.outputs.go_arch }}"
+          TARGET_TAG="${{ inputs.ushift-ref }}-${OKD_VERSION_TAG}-${{ steps.detect-cpu-arch.outputs.go_arch }}"
 
           sudo podman tag microshift-okd "${TARGET_IMAGE}:${TARGET_TAG}"
           sudo podman push "${TARGET_IMAGE}:${TARGET_TAG}"
@@ -147,7 +147,7 @@ jobs:
 
           OKD_VERSION_TAG="${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}"
           TARGET_IMAGE="ghcr.io/${{ github.repository_owner }}/microshift"
-          TARGET_TAG="${{ inputs.ushift-branch }}-${OKD_VERSION_TAG}"
+          TARGET_TAG="${{ inputs.ushift-ref }}-${OKD_VERSION_TAG}"
 
           sudo podman manifest create "${TARGET_IMAGE}:${TARGET_TAG}"
           sudo podman manifest add "${TARGET_IMAGE}:${TARGET_TAG}" "${TARGET_IMAGE}:${TARGET_TAG}-amd64"
@@ -163,5 +163,5 @@ jobs:
         if: contains(fromJSON('["all", "bootc-image"]'), inputs.build)
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ inputs.ushift-branch }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
+          tag_name: ${{ inputs.ushift-ref }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           body_path: /tmp/release.md
diff --git a/Makefile b/Makefile
index e001ef01..3a240d9b 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@
 #
 
 # Options used in the 'rpm' target
-USHIFT_BRANCH ?= main
+USHIFT_REF ?= main
 OKD_VERSION_TAG ?= $$(curl -s --max-time 60 https://quay.io/api/v1/repository/okd/scos-release/tag/ | jq -r ".tags[].name" | sort | tail -1)
 RPM_OUTDIR ?=
 # Options used in the 'image' target
@@ -62,7 +62,7 @@ rpm:
 	sudo podman build \
         -t "${BUILDER_IMAGE}" \
         --ulimit nofile=524288:524288 \
-        --build-arg USHIFT_BRANCH="${USHIFT_BRANCH}" \
+        --build-arg USHIFT_REF="${USHIFT_REF}" \
         --build-arg OKD_VERSION_TAG="${OKD_VERSION_TAG}" \
         --build-arg OKD_RELEASE_IMAGE="${OKD_RELEASE_IMAGE}" \
         -f packaging/microshift-builder.Containerfile .
@@ -98,8 +98,8 @@ image:
 	sudo podman build \
 		-t "${USHIFT_IMAGE}" \
         --ulimit nofile=524288:524288 \
-     	--label microshift.branch="${USHIFT_BRANCH}" \
-     	--label okd.version="${OKD_VERSION_TAG}" \
+        --label microshift.ref="${USHIFT_REF}" \
+        --label okd.version="${OKD_VERSION_TAG}" \
         --build-arg BOOTC_IMAGE_URL="${BOOTC_IMAGE_URL}" \
         --build-arg BOOTC_IMAGE_TAG="${BOOTC_IMAGE_TAG}" \
     	--env WITH_KINDNET="${WITH_KINDNET}" \
diff --git a/docs/build.md b/docs/build.md
index 60bbad08..37520fe9 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -24,7 +24,7 @@ The following options can be specified in the make command line using the `NAME=
 
 | Name            | Required | Default  | Comments |
 |-----------------|----------|----------|----------|
-| USHIFT_BRANCH   | no       | main     | [MicroShift repository branches](https://github.com/openshift/microshift/branches) |
+| USHIFT_REF      | no       | main     | [MicroShift repository branches](https://github.com/openshift/microshift/branches) |
 | OKD_VERSION_TAG | no       | latest   | [OKD version tags](https://quay.io/repository/okd/scos-release?tab=tags) |
 | RPM_OUTDIR      | no       | /tmp/... | RPM repository output directory |
 
@@ -50,7 +50,7 @@ RPMs are available in '/tmp/microshift-rpms-EI3IXg'
 
 Notes:
 - The MicroShift repository branch and the OKD version tag used to build the
-  packages can be overriden by specifying `USHIFT_BRANCH` and `OKD_VERSION_TAG`
+  packages can be overriden by specifying `USHIFT_REF` and `OKD_VERSION_TAG`
   make command line arguments.
 - The path to the `RPM_OUTDIR` directory (either temporary or specified in
   the `make rpm` command line) is displayed in the end of the build procedure.
diff --git a/packaging/microshift-builder.Containerfile b/packaging/microshift-builder.Containerfile
index 6e99b1cc..35bf06fc 100644
--- a/packaging/microshift-builder.Containerfile
+++ b/packaging/microshift-builder.Containerfile
@@ -1,7 +1,7 @@
 FROM quay.io/centos-bootc/centos-bootc:stream9
 
 # Variables controlling the source of MicroShift components to build
-ARG USHIFT_BRANCH=main
+ARG USHIFT_REF=main
 ARG OKD_RELEASE_IMAGE=quay.io/okd/scos-release
 ARG OKD_VERSION_TAG
 
@@ -36,7 +36,7 @@ USER ${USER}:${USER}
 WORKDIR ${HOME}
 
 # Preparing the OS configuration for the build
-RUN git clone --branch "${USHIFT_BRANCH}" --single-branch "${USHIFT_GIT_URL}" "${HOME}/microshift" && \
+RUN git clone --branch "${USHIFT_REF}" --single-branch "${USHIFT_GIT_URL}" "${HOME}/microshift" && \
     echo '{"auths":{"fake":{"auth":"aWQ6cGFzcwo="}}}' > /tmp/.pull-secret && \
     "${HOME}/microshift/scripts/devenv-builder/configure-vm.sh" --no-build --no-set-release-version --skip-dnf-update /tmp/.pull-secret
 

From b118c9cbafd7b7a312432a406904423d921066f1 Mon Sep 17 00:00:00 2001
From: Patryk Matuszak <pmatusza@redhat.com>
Date: Tue, 25 Nov 2025 18:42:12 +0100
Subject: [PATCH 2/5] Script to build RPMs with deterministic version

---
 packaging/microshift-builder.Containerfile |  8 +--
 src/image/build-rpms.sh                    | 60 ++++++++++++++++++++++
 2 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 src/image/build-rpms.sh

diff --git a/packaging/microshift-builder.Containerfile b/packaging/microshift-builder.Containerfile
index 35bf06fc..a9ce3913 100644
--- a/packaging/microshift-builder.Containerfile
+++ b/packaging/microshift-builder.Containerfile
@@ -13,6 +13,7 @@ ARG BUILDER_RPM_REPO_PATH=${HOME}/microshift/_output/rpmbuild/RPMS
 ARG USHIFT_PREBUILD_SCRIPT=/tmp/prebuild.sh
 ARG USHIFT_POSTBUILD_SCRIPT=/tmp/postbuild.sh
 ARG USHIFT_MODIFY_SPEC_SCRIPT=/tmp/modify-spec.py
+ARG USHIFT_BUILDRPMS_SCRIPT=/tmp/build-rpms.sh
 
 # Verify mandatory build arguments
 RUN if [ -z "${OKD_VERSION_TAG}" ] ; then \
@@ -46,6 +47,7 @@ WORKDIR ${HOME}/microshift/
 COPY --chmod=755 ./src/image/prebuild.sh ${USHIFT_PREBUILD_SCRIPT}
 RUN "${USHIFT_PREBUILD_SCRIPT}" --replace "${OKD_RELEASE_IMAGE}" "${OKD_VERSION_TAG}"
 
+COPY --chmod=755 ./src/image/build-rpms.sh ${USHIFT_BUILDRPMS_SCRIPT}
 # Modify the microshift.spec to remove packages not yet supported by the upstream.
 COPY --chmod=755 ./src/image/modify-spec.py ${USHIFT_MODIFY_SPEC_SCRIPT}
 # Disable the RPM and SRPM checks in the make-rpm.sh script.
@@ -54,7 +56,7 @@ RUN sed -i -e 's,CHECK_RPMS="y",,g' -e 's,CHECK_SRPMS="y",,g' ./packaging/rpm/ma
 
 # Building all MicroShift downstream RPMs and SRPMs
 # hadolint ignore=DL3059
-RUN MICROSHIFT_VARIANT="community" make -C "${HOME}/microshift" rpm srpm
+RUN "${USHIFT_BUILDRPMS_SCRIPT}" rpm srpm
 
 # Building Kindnet upstream RPM
 COPY --chown=${USER}:${USER} ./src/kindnet/kindnet.spec "${HOME}/microshift/packaging/rpm/microshift.spec"
@@ -63,7 +65,7 @@ COPY --chown=${USER}:${USER} ./src/kindnet/dropins/ "${HOME}/microshift/packagin
 COPY --chown=${USER}:${USER} ./src/kindnet/crio.conf.d/ "${HOME}/microshift/packaging/crio.conf.d/"
 # Prepare and build Kindnet upstream RPM
 RUN "${USHIFT_PREBUILD_SCRIPT}" --replace-kindnet "${OKD_RELEASE_IMAGE}" "${OKD_VERSION_TAG}" && \
-    MICROSHIFT_VARIANT="community" make -C "${HOME}/microshift" rpm
+    "${USHIFT_BUILDRPMS_SCRIPT}" rpm
 
 # Building TopoLVM upstream RPM
 COPY --chown=${USER}:${USER} ./src/topolvm/topolvm.spec "${HOME}/microshift/packaging/rpm/microshift.spec"
@@ -71,7 +73,7 @@ COPY --chown=${USER}:${USER} ./src/topolvm/assets/  "${HOME}/microshift/assets/o
 COPY --chown=${USER}:${USER} ./src/topolvm/dropins/ "${HOME}/microshift/packaging/microshift/dropins/"
 COPY --chown=${USER}:${USER} ./src/topolvm/greenboot/ "${HOME}/microshift/packaging/greenboot/"
 COPY --chown=${USER}:${USER} ./src/topolvm/release/ "${HOME}/microshift/assets/optional/topolvm/"
-RUN MICROSHIFT_VARIANT="community" make -C "${HOME}/microshift" rpm
+RUN "${USHIFT_BUILDRPMS_SCRIPT}" rpm
 
 # Post-build MicroShift configuration
 COPY --chmod=755 ./src/image/postbuild.sh ${USHIFT_POSTBUILD_SCRIPT}
diff --git a/src/image/build-rpms.sh b/src/image/build-rpms.sh
new file mode 100644
index 00000000..240cda3a
--- /dev/null
+++ b/src/image/build-rpms.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -xeuo pipefail
+
+# Primary purpose of this script is to build the MicroShift RPMs and SRPMs
+# with adjusted version string.
+# Using `make {rpm,srpm}` it would hardcode a meaningless version string based on downstream git variables
+# which would not provide good information to identify the build and trace back its contents.
+# Following script overrides the version to include information about the downstream version and commit, and OKD tag.
+
+target=all
+if [[ "$#" -eq 1 ]]; then
+    if [[ "${1}" != "all" && "${1}" != "rpm" && "${1}" != "srpm" ]]; then
+        echo "Script accepts at most one argument: all, rpm or srpm"
+        echo "If no argument is provided, the default is 'all'"
+        exit 1
+    fi
+    target="${1}"
+fi
+
+cd "${HOME}/microshift"
+
+SOURCE_GIT_COMMIT="$(git rev-parse --short 'HEAD^{commit}')"
+
+# MICROSHIFT_VERSION must start with X.Y.Z for the internals to correctly parse the version.
+# If USHIFT_REF is a tag, use it. Otherwise parse the version from Makefile.version.*.var file.
+if [[ $(git tag -l "${USHIFT_REF}") ]]; then
+    MICROSHIFT_VERSION="${USHIFT_REF}"
+else
+    MICROSHIFT_VERSION="$(awk -F'[=.-]' '{print $2 "." $3 "." $4}' Makefile.version.aarch64.var | sed -e 's/ //g')"
+fi
+# Example results:
+# - 4.21.0_ga9cd00b34_4.21.0_okd_scos.ec.5                for build against HEAD of main which was 4.21 at the time.
+# - 4.20.0-202510201126.p0-g1c4675ace_4.20.0-okd-scos.6   for build against a specific tag.
+MICROSHIFT_VERSION="${MICROSHIFT_VERSION}-g${SOURCE_GIT_COMMIT}-${OKD_VERSION_TAG}"
+# MicroShift's make-rpm.sh makes this substitution. Although we don't use the script,
+# let's do it as well for keeping the version consistent with existing downstream RPMs.
+# Version is also used for release.md file.
+MICROSHIFT_VERSION=${MICROSHIFT_VERSION//-/_}
+
+RPM_RELEASE="1"
+SOURCE_GIT_TAG="$(git describe --long --tags --abbrev=7 --match 'v[0-9]*' || echo "v0.0.0-unknown-${SOURCE_GIT_COMMIT}")"
+SOURCE_GIT_TREE_STATE=clean # Because we're updating downstream specfile, but that shouldn't be a reason to have -dirty suffix.
+MICROSHIFT_VARIANT=community
+
+export MICROSHIFT_VERSION
+export RPM_RELEASE
+export SOURCE_GIT_TAG
+export SOURCE_GIT_COMMIT
+export SOURCE_GIT_TREE_STATE
+export MICROSHIFT_VARIANT
+
+if [[ "${target}" == "all" || "${target}" == "rpm" ]]; then
+    ./packaging/rpm/make-rpm.sh rpm local
+fi
+
+if [[ "${target}" == "all" || "${target}" == "srpm" ]]; then
+    ./packaging/rpm/make-rpm.sh srpm local
+fi
+
+echo "${MICROSHIFT_VERSION}" > "${HOME}/microshift/_output/rpmbuild/RPMS/version.txt"

From bd113b066919e110113699c33c61b1c97156d85a Mon Sep 17 00:00:00 2001
From: Patryk Matuszak <pmatusza@redhat.com>
Date: Tue, 25 Nov 2025 18:42:56 +0100
Subject: [PATCH 3/5] Use new version schema for releases

---
 .github/workflows/release.yaml | 35 +++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 5a8420d9..0f36ba2c 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -73,6 +73,19 @@ jobs:
           cd /mnt/rpms
           sudo tar zcvf /mnt/release/microshift-rpms-$(uname -m).tgz .
 
+      - name: Store version in a variable
+        id: version
+        run: |
+          set -euo pipefail
+          echo "version=$(cat /mnt/rpms/version.txt)" >> "${GITHUB_OUTPUT}"
+
+      - name: Push version.txt to artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: version.txt
+          path: /mnt/rpms/version.txt
+          overwrite: true
+
         # This step is run after the RPM archives are prepared to avoid
         # including DEB packages in the RPM archive.
       - name: Convert the RPMs to DEB packages
@@ -94,7 +107,7 @@ jobs:
         if: contains(fromJSON('["all", "packages"]'), inputs.build)
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ inputs.ushift-ref }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
+          tag_name: ${{ steps.version.outputs.version }}
           files: |
             /mnt/release/microshift-rpms-*.tgz
             /mnt/release/microshift-debs-*.tgz
@@ -114,9 +127,8 @@ jobs:
           set -euo pipefail
           set -x
 
-          OKD_VERSION_TAG="${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}"
           TARGET_IMAGE="ghcr.io/${{ github.repository_owner }}/microshift"
-          TARGET_TAG="${{ inputs.ushift-ref }}-${OKD_VERSION_TAG}-${{ steps.detect-cpu-arch.outputs.go_arch }}"
+          TARGET_TAG="${{ steps.version.outputs.version }}-${{ steps.detect-cpu-arch.outputs.go_arch }}"
 
           sudo podman tag microshift-okd "${TARGET_IMAGE}:${TARGET_TAG}"
           sudo podman push "${TARGET_IMAGE}:${TARGET_TAG}"
@@ -128,9 +140,15 @@ jobs:
       - name: Check out MicroShift upstream repository
         uses: actions/checkout@v4
 
-      - name: Detect OKD version tag
-        id: detect-okd-version
-        uses: ./.github/actions/okd-version
+      - uses: actions/download-artifact@v4
+        with:
+          name: version.txt
+          path: /tmp/
+
+      - name: Store version in a variable
+        id: version
+        run: |
+          echo "version=$(cat /tmp/version.txt)" >> "${GITHUB_OUTPUT}"
 
       - name: Login to GitHub Container Registry
         if: contains(fromJSON('["all", "bootc-image"]'), inputs.build)
@@ -145,9 +163,8 @@ jobs:
           set -euo pipefail
           set -x
 
-          OKD_VERSION_TAG="${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}"
           TARGET_IMAGE="ghcr.io/${{ github.repository_owner }}/microshift"
-          TARGET_TAG="${{ inputs.ushift-ref }}-${OKD_VERSION_TAG}"
+          TARGET_TAG="${{ steps.version.outputs.version }}"
 
           sudo podman manifest create "${TARGET_IMAGE}:${TARGET_TAG}"
           sudo podman manifest add "${TARGET_IMAGE}:${TARGET_TAG}" "${TARGET_IMAGE}:${TARGET_TAG}-amd64"
@@ -163,5 +180,5 @@ jobs:
         if: contains(fromJSON('["all", "bootc-image"]'), inputs.build)
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ inputs.ushift-ref }}-${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
+          tag_name: ${{ steps.version.outputs.version }}
           body_path: /tmp/release.md

From 48af9ab6be23741c21beb033c10b3dbf832b5770 Mon Sep 17 00:00:00 2001
From: Patryk Matuszak <pmatusza@redhat.com>
Date: Thu, 27 Nov 2025 13:35:38 +0100
Subject: [PATCH 4/5] Add versioning scheme to readme

---
 README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/README.md b/README.md
index 0f6b7ad9..b920683b 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,28 @@ Notes:
   build procedure until [OKD Build of OpenShift on Arm](https://issues.redhat.com/browse/OKD-215)
   is implemented by the OKD team.
 
+# Version scheme
+
+Upstream packages are based on MicroShift's code and OKD's images.
+To allow for easy identification and tracking back of what's included in the package,
+following version scheme is used: `MICROSHIFT_VERSION`-g`MICROSHIFT_GIT_COMMIT`-`OKD_VERSION`:
+
+- `MICROSHIFT_VERSION` can have two forms:
+  - `X.Y.Z-YYYYMMDDHHSS.pN` or `X.Y.Z-{e,r}c.M-YYYYMMDDHHSS.pN` if it's based on [openshift/microshift's tag](https://github.com/openshift/microshift/tags).
+  - `X.Y.Z` if it was build against a branch (e.g. `main` or `release-X.Y`), value of `X.Y.Z` is  based on version stored in `Makefile.version.*.var` file.
+- `MICROSHIFT_GIT_COMMIT` is the [openshift/microshift](https://github.com/openshift/microshift) commit.
+- `OKD_VERSION` is tag of the OKD release image from which the component image references are sourced.
+
+Examples:
+- `4.21.0_ga9cd00b34_4.21.0_okd_scos.ec.5`
+  - Missing `YYYYMMDDHHSS.pN` means it was built against a branch, not a tag (release)
+  - `4.21.0` means that commit [a9cd00b34](https://github.com/openshift/microshift/commit/a9cd00b341191e2091937a1f982168964c105297) was part of 4.21 release (but it could be built from main)
+  - Component image references are sourced from [4.21.0-okd-scos.ec.5 release](https://github.com/okd-project/okd/releases/tag/4.21.0-okd-scos.ec.5)
+- `4.20.0-202510201126.p0-g1c4675ace_4.20.0-okd-scos.6`
+  - `202510201126.p0` is present which means it was built from [MicroShift's release tag 4.20.0-202510201126.p0](https://github.com/openshift/microshift/releases/tag/4.20.0-202510201126.p0)
+  - MicroShift's tag points to [1c4675ace](https://github.com/openshift/microshift/commit/1c4675ace39e1ef9c4919218c15d21e8793f6254) commit.
+  - Component image references are sourced from [4.20.0-okd-scos.6 release](https://github.com/okd-project/okd/releases/tag/4.20.0-okd-scos.6)
+
 ## Quick Start
 
 Prebuilt MicroShift artifacts are published at the

From e09d367b081fcc941bb372c91d82b5cc1661c423 Mon Sep 17 00:00:00 2001
From: Patryk Matuszak <pmatusza@redhat.com>
Date: Fri, 28 Nov 2025 09:21:07 +0100
Subject: [PATCH 5/5] Address review comments

---
 .github/actions/build-deb/action.yaml      |  6 +--
 .github/actions/build-okd/action.yaml      |  8 ++--
 .github/actions/build/action.yaml          |  6 +--
 .github/workflows/builders.yaml            | 10 ++---
 .github/workflows/release-okd.yaml         |  8 ++--
 .github/workflows/release.yaml             | 12 +++--
 Makefile                                   |  6 +--
 README.md                                  | 23 +---------
 docs/build.md                              |  4 +-
 docs/versioning.md                         | 21 +++++++++
 packaging/microshift-builder.Containerfile |  9 ++--
 src/image/build-rpms.sh                    | 52 +++++++++++++++-------
 12 files changed, 97 insertions(+), 68 deletions(-)
 create mode 100644 docs/versioning.md
 mode change 100644 => 100755 src/image/build-rpms.sh

diff --git a/.github/actions/build-deb/action.yaml b/.github/actions/build-deb/action.yaml
index 8c7ccd88..d9a8e495 100644
--- a/.github/actions/build-deb/action.yaml
+++ b/.github/actions/build-deb/action.yaml
@@ -2,8 +2,8 @@ name: build-deb-packages
 description: Reusable action to build MicroShift Debian packages
 
 inputs:
-  ushift-ref:
-    description: MicroShift branch from https://github.com/openshift/microshift/branches
+  ushift-gitref:
+    description: MicroShift git ref (branch, tag, commit) from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
     description: OKD version tag from https://quay.io/repository/okd/scos-release?tab=tags
@@ -40,7 +40,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_REF=${{ inputs.ushift-ref }} \
+          USHIFT_GITREF=${{ inputs.ushift-gitref }} \
           OKD_VERSION_TAG=${{ inputs.okd-version-tag }} \
           RPM_OUTDIR=/mnt/rpms
 
diff --git a/.github/actions/build-okd/action.yaml b/.github/actions/build-okd/action.yaml
index 7d89825e..60e37fa3 100644
--- a/.github/actions/build-okd/action.yaml
+++ b/.github/actions/build-okd/action.yaml
@@ -2,8 +2,8 @@ name: build-okd-images
 description: Reusable action to build OKD images
 
 inputs:
-  ushift-ref:
-    description: MicroShift branch from https://github.com/openshift/microshift/branches
+  ushift-gitref:
+    description: MicroShift git ref (branch, tag, commit) from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
     description: OKD version tag from https://quay.io/repository/okd/scos-release?tab=tags
@@ -53,7 +53,7 @@ runs:
         cd ${GITHUB_WORKSPACE}/
         TARGET_REGISTRY="${{ inputs.target-registry }}" ./src/okd/build_images.sh \
           "${{ inputs.okd-version-tag }}" \
-          "${{ inputs.ushift-ref }}" \
+          "${{ inputs.ushift-gitref }}" \
           "${{ inputs.target-arch }}"
 
     - name: Build MicroShift RPMs
@@ -65,7 +65,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_REF="${{ inputs.ushift-ref }}" \
+          USHIFT_GITREF="${{ inputs.ushift-gitref }}" \
           OKD_VERSION_TAG="${{ inputs.okd-version-tag }}" \
           OKD_RELEASE_IMAGE="${{ inputs.target-registry }}/okd-release-${{ steps.detect-cpu-arch.outputs.go_arch }}" \
           RPM_OUTDIR=/mnt/rpms
diff --git a/.github/actions/build/action.yaml b/.github/actions/build/action.yaml
index 45b3be02..bc113db5 100644
--- a/.github/actions/build/action.yaml
+++ b/.github/actions/build/action.yaml
@@ -2,8 +2,8 @@ name: build-microshift
 description: Reusable action to build MicroShift RPMs and container images
 
 inputs:
-  ushift-ref:
-    description: MicroShift branch from https://github.com/openshift/microshift/branches
+  ushift-gitref:
+    description: MicroShift git ref (branch, tag, commit) from https://github.com/openshift/microshift/branches
     required: true
   okd-version-tag:
     description: OKD version tag from https://quay.io/repository/okd/scos-release?tab=tags
@@ -51,7 +51,7 @@ runs:
         # Run the RPM build process.
         cd ${GITHUB_WORKSPACE}/
         make rpm \
-          USHIFT_REF="${{ inputs.ushift-ref }}" \
+          USHIFT_GITREF="${{ inputs.ushift-gitref }}" \
           OKD_VERSION_TAG="${{ inputs.okd-version-tag }}" \
           RPM_OUTDIR=/mnt/rpms
 
diff --git a/.github/workflows/builders.yaml b/.github/workflows/builders.yaml
index af7a9d61..bec3bfb1 100644
--- a/.github/workflows/builders.yaml
+++ b/.github/workflows/builders.yaml
@@ -19,7 +19,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-ref: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: quay.io/centos-bootc/centos-bootc
           bootc-image-tag: stream9
@@ -40,7 +40,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-ref: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: quay.io/centos-bootc/centos-bootc
           bootc-image-tag: stream10
@@ -64,7 +64,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-ref: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           bootc-image-url: registry.fedoraproject.org/fedora-bootc
           bootc-image-tag: 42
@@ -85,7 +85,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build-deb
         with:
-          ushift-ref: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
 
   isolated-network:
@@ -111,7 +111,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-ref: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           isolated-network: 1
           ovnk-networking: ${{ matrix.ovnk-networking }}
diff --git a/.github/workflows/release-okd.yaml b/.github/workflows/release-okd.yaml
index cc3bddab..9c36d720 100644
--- a/.github/workflows/release-okd.yaml
+++ b/.github/workflows/release-okd.yaml
@@ -6,9 +6,9 @@ on:
     - cron: '0 3 * * *'
   workflow_dispatch:
     inputs:
-      ushift-ref:
+      ushift-gitref:
         default: "main"
-        description: MicroShift branch from https://github.com/openshift/microshift/branches
+        description: MicroShift git ref (branch, tag, commit) from https://github.com/openshift/microshift/branches
         type: string
       okd-version-tag:
         default: "latest"
@@ -22,7 +22,7 @@ on:
 # The workflow dispatch inputs are not inherited by the scheduled workflow runs.
 # Use environment variables to pass the inputs to the build action.
 env:
-  USHIFT_REF: ${{ github.event.inputs.ushift-ref || 'main' }}
+  USHIFT_GITREF: ${{ github.event.inputs.ushift-gitref || 'main' }}
   OKD_VERSION_TAG: ${{ github.event.inputs.okd-version-tag || 'latest' }}
   OKD_TARGET_REGISTRY: ${{ github.event.inputs.okd-target-registry || 'ghcr.io/microshift-io/okd' }}
 
@@ -41,7 +41,7 @@ jobs:
       - name: Run the OKD release images build action
         uses: ./.github/actions/build-okd
         with:
-          ushift-ref: ${{ env.USHIFT_REF }}
+          ushift-gitref: ${{ env.USHIFT_GITREF }}
           okd-version-tag: ${{ env.OKD_VERSION_TAG != 'latest' && env.OKD_VERSION_TAG || steps.detect-okd-version.outputs.okd-version-tag }}
           target-arch: arm64
           target-registry: ${{ env.OKD_TARGET_REGISTRY }}
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 0f36ba2c..87bf55da 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -7,9 +7,9 @@ name: release-packages-and-images
 on:
   workflow_dispatch:
     inputs:
-      ushift-ref:
+      ushift-gitref:
         default: "main"
-        description: MicroShift branch from https://github.com/openshift/microshift/branches
+        description: MicroShift git ref (branch, tag, commit) from https://github.com/openshift/microshift/branches
         type: string
       okd-version-tag:
         default: "latest"
@@ -46,7 +46,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-ref: ${{ inputs.ushift-ref }}
+          ushift-gitref: ${{ inputs.ushift-gitref }}
           okd-version-tag: ${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           build: ${{ inputs.build }}
 
@@ -77,6 +77,10 @@ jobs:
         id: version
         run: |
           set -euo pipefail
+          if [ ! -f /mnt/rpms/version.txt ]; then
+            echo "ERROR: version.txt not found at /mnt/rpms/version.txt"
+            exit 1
+          fi
           echo "version=$(cat /mnt/rpms/version.txt)" >> "${GITHUB_OUTPUT}"
 
       - name: Push version.txt to artifacts
@@ -92,7 +96,7 @@ jobs:
         if: contains(fromJSON('["all", "packages"]'), inputs.build)
         uses: ./.github/actions/build-deb
         with:
-          ushift-ref: ${{ inputs.ushift-ref }}
+          ushift-gitref: ${{ inputs.ushift-gitref }}
           okd-version-tag: ${{ inputs.okd-version-tag != 'latest' && inputs.okd-version-tag || steps.detect-okd-version.outputs.okd-version-tag }}
           build-rpms: false
 
diff --git a/Makefile b/Makefile
index 3a240d9b..1c851773 100644
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@
 #
 
 # Options used in the 'rpm' target
-USHIFT_REF ?= main
+USHIFT_GITREF ?= main
 OKD_VERSION_TAG ?= $$(curl -s --max-time 60 https://quay.io/api/v1/repository/okd/scos-release/tag/ | jq -r ".tags[].name" | sort | tail -1)
 RPM_OUTDIR ?=
 # Options used in the 'image' target
@@ -62,7 +62,7 @@ rpm:
 	sudo podman build \
         -t "${BUILDER_IMAGE}" \
         --ulimit nofile=524288:524288 \
-        --build-arg USHIFT_REF="${USHIFT_REF}" \
+        --build-arg USHIFT_GITREF="${USHIFT_GITREF}" \
         --build-arg OKD_VERSION_TAG="${OKD_VERSION_TAG}" \
         --build-arg OKD_RELEASE_IMAGE="${OKD_RELEASE_IMAGE}" \
         -f packaging/microshift-builder.Containerfile .
@@ -98,7 +98,7 @@ image:
 	sudo podman build \
 		-t "${USHIFT_IMAGE}" \
         --ulimit nofile=524288:524288 \
-        --label microshift.ref="${USHIFT_REF}" \
+        --label microshift.ref="${USHIFT_GITREF}" \
         --label okd.version="${OKD_VERSION_TAG}" \
         --build-arg BOOTC_IMAGE_URL="${BOOTC_IMAGE_URL}" \
         --build-arg BOOTC_IMAGE_TAG="${BOOTC_IMAGE_TAG}" \
diff --git a/README.md b/README.md
index b920683b..392cea32 100644
--- a/README.md
+++ b/README.md
@@ -35,28 +35,6 @@ Notes:
   build procedure until [OKD Build of OpenShift on Arm](https://issues.redhat.com/browse/OKD-215)
   is implemented by the OKD team.
 
-# Version scheme
-
-Upstream packages are based on MicroShift's code and OKD's images.
-To allow for easy identification and tracking back of what's included in the package,
-following version scheme is used: `MICROSHIFT_VERSION`-g`MICROSHIFT_GIT_COMMIT`-`OKD_VERSION`:
-
-- `MICROSHIFT_VERSION` can have two forms:
-  - `X.Y.Z-YYYYMMDDHHSS.pN` or `X.Y.Z-{e,r}c.M-YYYYMMDDHHSS.pN` if it's based on [openshift/microshift's tag](https://github.com/openshift/microshift/tags).
-  - `X.Y.Z` if it was build against a branch (e.g. `main` or `release-X.Y`), value of `X.Y.Z` is  based on version stored in `Makefile.version.*.var` file.
-- `MICROSHIFT_GIT_COMMIT` is the [openshift/microshift](https://github.com/openshift/microshift) commit.
-- `OKD_VERSION` is tag of the OKD release image from which the component image references are sourced.
-
-Examples:
-- `4.21.0_ga9cd00b34_4.21.0_okd_scos.ec.5`
-  - Missing `YYYYMMDDHHSS.pN` means it was built against a branch, not a tag (release)
-  - `4.21.0` means that commit [a9cd00b34](https://github.com/openshift/microshift/commit/a9cd00b341191e2091937a1f982168964c105297) was part of 4.21 release (but it could be built from main)
-  - Component image references are sourced from [4.21.0-okd-scos.ec.5 release](https://github.com/okd-project/okd/releases/tag/4.21.0-okd-scos.ec.5)
-- `4.20.0-202510201126.p0-g1c4675ace_4.20.0-okd-scos.6`
-  - `202510201126.p0` is present which means it was built from [MicroShift's release tag 4.20.0-202510201126.p0](https://github.com/openshift/microshift/releases/tag/4.20.0-202510201126.p0)
-  - MicroShift's tag points to [1c4675ace](https://github.com/openshift/microshift/commit/1c4675ace39e1ef9c4919218c15d21e8793f6254) commit.
-  - Component image references are sourced from [4.20.0-okd-scos.6 release](https://github.com/okd-project/okd/releases/tag/4.20.0-okd-scos.6)
-
 ## Quick Start
 
 Prebuilt MicroShift artifacts are published at the
@@ -92,6 +70,7 @@ To uninstall MicroShift, run the following command:
 ## Documentation
 
 * [Build MicroShift](./docs/build.md)
+* [Versioning Scheme](./docs/versioning.md)
 * [MicroShift Host Deployment](./docs/run.md)
 * [MicroShift Bootc Deployment](./docs/run-bootc.md)
 * [GitHub Workflows](./docs/workflows.md)
diff --git a/docs/build.md b/docs/build.md
index 37520fe9..1d1c96d5 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -24,7 +24,7 @@ The following options can be specified in the make command line using the `NAME=
 
 | Name            | Required | Default  | Comments |
 |-----------------|----------|----------|----------|
-| USHIFT_REF      | no       | main     | [MicroShift repository branches](https://github.com/openshift/microshift/branches) |
+| USHIFT_GITREF   | no       | main     | [MicroShift repository branches](https://github.com/openshift/microshift/branches) |
 | OKD_VERSION_TAG | no       | latest   | [OKD version tags](https://quay.io/repository/okd/scos-release?tab=tags) |
 | RPM_OUTDIR      | no       | /tmp/... | RPM repository output directory |
 
@@ -50,7 +50,7 @@ RPMs are available in '/tmp/microshift-rpms-EI3IXg'
 
 Notes:
 - The MicroShift repository branch and the OKD version tag used to build the
-  packages can be overriden by specifying `USHIFT_REF` and `OKD_VERSION_TAG`
+  packages can be overridden by specifying `USHIFT_GITREF` and `OKD_VERSION_TAG`
   make command line arguments.
 - The path to the `RPM_OUTDIR` directory (either temporary or specified in
   the `make rpm` command line) is displayed in the end of the build procedure.
diff --git a/docs/versioning.md b/docs/versioning.md
new file mode 100644
index 00000000..7ed1ba3f
--- /dev/null
+++ b/docs/versioning.md
@@ -0,0 +1,21 @@
+# Versioning Scheme
+
+Upstream packages are based on MicroShift code and OKD images.
+To allow for easy identification and tracking of what is included in the package,
+following versioning scheme is used: `MICROSHIFT-VERSION`_g`MICROSHIFT-GIT-COMMIT`_`OKD-VERSION`:
+
+- `MICROSHIFT-VERSION` can have two forms:
+  - `X.Y.Z-YYYYMMDDHHMM.pN` or `X.Y.Z-{e,r}c.M-YYYYMMDDHHMM.pN` if it is based on [openshift/microshift tags](https://github.com/openshift/microshift/tags).
+  - `X.Y.Z` if it was build against a branch (e.g. `main` or `release-X.Y`), value of `X.Y.Z` is  based on version stored in `Makefile.version.*.var` file.
+- `MICROSHIFT-GIT-COMMIT` is the [openshift/microshift](https://github.com/openshift/microshift) commit.
+- `OKD-VERSION` is a tag of the OKD release image from which the component image references are sourced.
+
+Examples:
+- `4.21.0_ga9cd00b34_4.21.0_okd_scos.ec.5`
+  - Missing `YYYYMMDDHHMM.pN` means it was built against a branch, not a tag (release)
+  - `4.21.0` means that commit [a9cd00b34](https://github.com/openshift/microshift/commit/a9cd00b341191e2091937a1f982168964c105297) was part of 4.21 release (but it could be built from main)
+  - Component image references are sourced from [4.21.0-okd-scos.ec.5 release](https://github.com/okd-project/okd/releases/tag/4.21.0-okd-scos.ec.5)
+- `4.20.0-202510201126.p0-g1c4675ace_4.20.0-okd-scos.6`
+  - `202510201126.p0` is present which means it was built from [MicroShift release tag 4.20.0-202510201126.p0](https://github.com/openshift/microshift/releases/tag/4.20.0-202510201126.p0)
+  - MicroShift tag points to [1c4675ace](https://github.com/openshift/microshift/commit/1c4675ace39e1ef9c4919218c15d21e8793f6254) commit.
+  - Component image references are sourced from [4.20.0-okd-scos.6 release](https://github.com/okd-project/okd/releases/tag/4.20.0-okd-scos.6)
diff --git a/packaging/microshift-builder.Containerfile b/packaging/microshift-builder.Containerfile
index a9ce3913..b9035568 100644
--- a/packaging/microshift-builder.Containerfile
+++ b/packaging/microshift-builder.Containerfile
@@ -1,10 +1,13 @@
 FROM quay.io/centos-bootc/centos-bootc:stream9
 
 # Variables controlling the source of MicroShift components to build
-ARG USHIFT_REF=main
+ARG USHIFT_GITREF=main
 ARG OKD_RELEASE_IMAGE=quay.io/okd/scos-release
 ARG OKD_VERSION_TAG
 
+ENV OKD_VERSION_TAG=${OKD_VERSION_TAG}
+ENV USHIFT_GITREF=${USHIFT_GITREF}
+
 # Internal variables
 ARG USHIFT_GIT_URL=https://github.com/openshift/microshift.git
 ENV USER=microshift
@@ -37,7 +40,7 @@ USER ${USER}:${USER}
 WORKDIR ${HOME}
 
 # Preparing the OS configuration for the build
-RUN git clone --branch "${USHIFT_REF}" --single-branch "${USHIFT_GIT_URL}" "${HOME}/microshift" && \
+RUN git clone --branch "${USHIFT_GITREF}" --single-branch "${USHIFT_GIT_URL}" "${HOME}/microshift" && \
     echo '{"auths":{"fake":{"auth":"aWQ6cGFzcwo="}}}' > /tmp/.pull-secret && \
     "${HOME}/microshift/scripts/devenv-builder/configure-vm.sh" --no-build --no-set-release-version --skip-dnf-update /tmp/.pull-secret
 
@@ -56,7 +59,7 @@ RUN sed -i -e 's,CHECK_RPMS="y",,g' -e 's,CHECK_SRPMS="y",,g' ./packaging/rpm/ma
 
 # Building all MicroShift downstream RPMs and SRPMs
 # hadolint ignore=DL3059
-RUN "${USHIFT_BUILDRPMS_SCRIPT}" rpm srpm
+RUN "${USHIFT_BUILDRPMS_SCRIPT}" all
 
 # Building Kindnet upstream RPM
 COPY --chown=${USER}:${USER} ./src/kindnet/kindnet.spec "${HOME}/microshift/packaging/rpm/microshift.spec"
diff --git a/src/image/build-rpms.sh b/src/image/build-rpms.sh
old mode 100644
new mode 100755
index 240cda3a..0b3e24e3
--- a/src/image/build-rpms.sh
+++ b/src/image/build-rpms.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-set -xeuo pipefail
+set -euo pipefail
 
 # Primary purpose of this script is to build the MicroShift RPMs and SRPMs
 # with adjusted version string.
@@ -7,24 +7,46 @@ set -xeuo pipefail
 # which would not provide good information to identify the build and trace back its contents.
 # Following script overrides the version to include information about the downstream version and commit, and OKD tag.
 
-target=all
-if [[ "$#" -eq 1 ]]; then
-    if [[ "${1}" != "all" && "${1}" != "rpm" && "${1}" != "srpm" ]]; then
-        echo "Script accepts at most one argument: all, rpm or srpm"
-        echo "If no argument is provided, the default is 'all'"
-        exit 1
-    fi
-    target="${1}"
+usage() {
+    echo "Usage: $(basename "$0") <all | rpm | srpm>"
+    echo ""
+    echo "Script expects to be run from the root of the MicroShift repository"
+    echo "Following env vars are required: USHIFT_GITREF, OKD_VERSION_TAG"
+    exit 1
+}
+
+if [[ "${#}" -ne 1 ]]; then
+    usage
+fi
+
+target="${1}"
+
+case "${target}" in
+    all) :;;
+    rpm) :;;
+    srpm) :;;
+    *)
+        echo -e "ERROR: Unknown command: ${target}\n"
+        usage
+        ;;
+esac
+
+if [[ -z "${USHIFT_GITREF}" ]]; then
+    echo "ERROR: USHIFT_GITREF is not set"
+    usage
 fi
 
-cd "${HOME}/microshift"
+if [[ -z "${OKD_VERSION_TAG}" ]]; then
+    echo "ERROR: OKD_VERSION_TAG is not set"
+    usage
+fi
 
 SOURCE_GIT_COMMIT="$(git rev-parse --short 'HEAD^{commit}')"
 
 # MICROSHIFT_VERSION must start with X.Y.Z for the internals to correctly parse the version.
-# If USHIFT_REF is a tag, use it. Otherwise parse the version from Makefile.version.*.var file.
-if [[ $(git tag -l "${USHIFT_REF}") ]]; then
-    MICROSHIFT_VERSION="${USHIFT_REF}"
+# If USHIFT_GITREF is a tag, use it. Otherwise parse the version from Makefile.version.*.var file.
+if [[ $(git tag -l "${USHIFT_GITREF}") ]]; then
+    MICROSHIFT_VERSION="${USHIFT_GITREF}"
 else
     MICROSHIFT_VERSION="$(awk -F'[=.-]' '{print $2 "." $3 "." $4}' Makefile.version.aarch64.var | sed -e 's/ //g')"
 fi
@@ -38,7 +60,7 @@ MICROSHIFT_VERSION="${MICROSHIFT_VERSION}-g${SOURCE_GIT_COMMIT}-${OKD_VERSION_TA
 MICROSHIFT_VERSION=${MICROSHIFT_VERSION//-/_}
 
 RPM_RELEASE="1"
-SOURCE_GIT_TAG="$(git describe --long --tags --abbrev=7 --match 'v[0-9]*' || echo "v0.0.0-unknown-${SOURCE_GIT_COMMIT}")"
+SOURCE_GIT_TAG="${MICROSHIFT_VERSION}"
 SOURCE_GIT_TREE_STATE=clean # Because we're updating downstream specfile, but that shouldn't be a reason to have -dirty suffix.
 MICROSHIFT_VARIANT=community
 
@@ -57,4 +79,4 @@ if [[ "${target}" == "all" || "${target}" == "srpm" ]]; then
     ./packaging/rpm/make-rpm.sh srpm local
 fi
 
-echo "${MICROSHIFT_VERSION}" > "${HOME}/microshift/_output/rpmbuild/RPMS/version.txt"
+echo "${MICROSHIFT_VERSION}" > _output/rpmbuild/RPMS/version.txt