Stabilize MicroShift upstream versioning scheme

.github/actions/build-deb/action.yaml

@@ -2,8 +2,8 @@ name: build-deb-packages
 description: Reusable action to build MicroShift Debian packages
 
 inputs:
-  ushift-branch:
-    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_BRANCH=${{ inputs.ushift-branch }} \
+          USHIFT_GITREF=${{ inputs.ushift-gitref }} \
           OKD_VERSION_TAG=${{ inputs.okd-version-tag }} \
           RPM_OUTDIR=/mnt/rpms
 

.github/actions/build-okd/action.yaml

@@ -2,8 +2,8 @@ name: build-okd-images
 description: Reusable action to build OKD images
 
 inputs:
-  ushift-branch:
-    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-branch }}" \
+          "${{ 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_BRANCH="${{ inputs.ushift-branch }}" \
+          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

.github/actions/build/action.yaml

@@ -2,8 +2,8 @@ name: build-microshift
 description: Reusable action to build MicroShift RPMs and container images
 
 inputs:
-  ushift-branch:
-    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_BRANCH="${{ inputs.ushift-branch }}" \
+          USHIFT_GITREF="${{ inputs.ushift-gitref }}" \
           OKD_VERSION_TAG="${{ inputs.okd-version-tag }}" \
           RPM_OUTDIR=/mnt/rpms
 

.github/workflows/builders.yaml

@@ -19,7 +19,7 @@ jobs:
       - name: Run the build action
         uses: ./.github/actions/build
         with:
-          ushift-branch: 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-branch: 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-branch: 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-branch: 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-branch: main
+          ushift-gitref: main
           okd-version-tag: ${{ steps.detect-okd-version.outputs.okd-version-tag }}
           isolated-network: 1
           ovnk-networking: ${{ matrix.ovnk-networking }}

.github/workflows/release-okd.yaml

@@ -6,9 +6,9 @@ on:
     - cron: '0 3 * * *'
   workflow_dispatch:
     inputs:
-      ushift-branch:
+      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_BRANCH: ${{ github.event.inputs.ushift-branch || '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-branch: ${{ env.USHIFT_BRANCH }}
+          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 }}

.github/workflows/release.yaml

@@ -7,9 +7,9 @@ name: release-packages-and-images
 on:
   workflow_dispatch:
     inputs:
-      ushift-branch:
+      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-branch: ${{ inputs.ushift-branch }}
+          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 }}
 
@@ -73,13 +73,30 @@ 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
+          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
+        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
         if: contains(fromJSON('["all", "packages"]'), inputs.build)
         uses: ./.github/actions/build-deb
         with:
-          ushift-branch: ${{ inputs.ushift-branch }}
+          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
 
@@ -94,7 +111,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: ${{ steps.version.outputs.version }}
           files: |
             /mnt/release/microshift-rpms-*.tgz
             /mnt/release/microshift-debs-*.tgz
@@ -114,9 +131,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-branch }}-${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 +144,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 +167,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-branch }}-${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 +184,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: ${{ steps.version.outputs.version }}
           body_path: /tmp/release.md

Makefile

@@ -4,7 +4,7 @@
 #
 
 # Options used in the 'rpm' target
-USHIFT_BRANCH ?= 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_BRANCH="${USHIFT_BRANCH}" \
+        --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,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_GITREF}" \
+        --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}" \

README.md

@@ -70,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)

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_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_BRANCH` 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.

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)

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_BRANCH=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
@@ -13,6 +16,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 \
@@ -36,7 +40,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_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
 
@@ -46,6 +50,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 +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 MICROSHIFT_VARIANT="community" make -C "${HOME}/microshift" 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"
@@ -63,15 +68,15 @@ 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"
 COPY --chown=${USER}:${USER} ./src/topolvm/assets/  "${HOME}/microshift/assets/optional/topolvm/"
 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}