mongodb · andrpac · Jul 18, 2025 · Jul 18, 2025 · Jul 18, 2025
@@ -53,12 +53,16 @@ jobs:
             PR_HEAD_REPONAME: ${{ github.event.pull_request.head.repo.full_name }}
             REPONAME: ${{ github.repository }}
             ACTOR: ${{ github.actor }}
+            PROMOTE: ${{ github.event.inputs.promote }}
           run: |
             # Evaluate whether or not cloud tests should run
             RUN_CLOUD_TESTS='false'
             # Scheduled runs on default branch always run all tests
             if [ "${EVENT}" == "schedule" ];then
               RUN_CLOUD_TESTS='true'
+            # Manual runs of tests that aim to create a promoted image should run all tests
+            elif [ "${EVENT}" == "workflow_dispatch" ] && [ "${PROMOTE}" == "true" ]; then
+              RUN_CLOUD_TESTS='true'
             # Release branches always run all tests
             elif [[ "${GH_HEAD_REF}" == release/* ]];then
               RUN_CLOUD_TESTS='true'

@@ -6,13 +6,39 @@ on:
     types: [completed]
 
 jobs:
+  # Check-test-status: Uses the hook called test-status on the test.yml job in order to 
+  # see if any test failed or was skipped; promotion should only run when all tests suceeded!
+  check-test-status:
+    runs-on: ubuntu-latest
+    outputs:
+      test-status: ${{ steps.set-status.outputs.status }}
+    steps:
+      - name: Ensure test-status job completed
+        id: set-status
+        env:
+          REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+        run: |
+          jobs=$(gh api /repos/$REPO/actions/runs/$RUN_ID/jobs --jq '.jobs[] | select(.name == "Final Test Status")')
+
+          if [[ -z "$jobs" ]]; then
+            echo "test-status job not found"
+            exit 1
+          fi
+
+          conclusion=$(echo "$jobs" | jq -r '.conclusion')
+          echo "status=$conclusion" >> "$GITHUB_OUTPUT"
+
+  # Promote image: this will be responbile for taking a tested image from an unofficial registry like
+  # ghcr.io and promote it by adding it to an official registry (docker.io and quay.io)
   promote-image:
     runs-on: ubuntu-latest
     environment: release
+    needs: check-test-status
     if: |
       github.event.workflow_run.head_branch == 'main' &&
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event == 'schedule'
+      needs.check-test-status.outputs.test-status == 'success'
     env:
       GHCR_REPO: ghcr.io/mongodb/mongodb-atlas-kubernetes-operator-prerelease
       DOCKER_REPO: docker.io/mongodb/mongodb-atlas-kubernetes-operator-prerelease
@@ -21,6 +47,7 @@ jobs:
       - name: Checkout PR commit
         uses: actions/checkout@v4
 
+      # Login in all the needed registries
       - name: Log in to the GitHub Container Registry
         uses: docker/login-action@v3
         with:
@@ -42,6 +69,7 @@ jobs:
           username: ${{ secrets.QUAY_USERNAME }}
           password: ${{ secrets.QUAY_PASSWORD }}
 
+      # Prepare tags
       - name: Prepare image tag
         id: set_tag
         uses: ./.github/actions/set-tag
@@ -56,6 +84,7 @@ jobs:
           COMMIT_SHA="${RAW_TAG##*-}"
           echo "tag=promoted-${COMMIT_SHA}" >> $GITHUB_OUTPUT
 
+      # Promote image to official prerelease registries
       - name: Move image to Docker Hub
         run: ./scripts/move-image.sh
         env:

@@ -16,6 +16,15 @@ on:
       - 'docs/**'
   merge_group:
   workflow_dispatch:
+    inputs:
+      promote:
+        description: "Flag to indicate whether to run all tests and promote the image"
+        required: false
+        type: choice
+        default: "false"
+        options:
+          - "true"
+          - "false"
 
 concurrency:
   group: test-${{ github.head_ref || github.ref_name }}
@@ -88,3 +97,19 @@ jobs:
       github.event_name == 'merge_group' || needs.cloud-tests-filter.outputs.run-cloud-tests == 'true'
     uses: ./.github/workflows/cloud-tests.yml
     secrets: inherit
+
+  # Test-status: this is a hook for jobs that require all the tests to succeed like promote-image
+  # in order to check the overall status of the tests (no test failed nor got skipped)
+  test-status:
+    name: Final Test Status
+    needs:
+      - lint
+      - unit-tests
+      - validate-manifests
+      - check-licenses
+      - e2e2
+      - cloud-tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: All tests status
+        run: echo "All tests successfully ran. This will get printed only on success!"
@@ -131,17 +131,28 @@ Finally, adjust the `com.redhat.openshift.versions` setting in all relevant file
 
 ## Release CI
 
-A **release PR** is prepared by the [release-branch.yml](../../.github/workflows/release-branch.yml) workflow.
+A **release** is initiated by the [`release-image.yml`](../../.github/workflows/release-image.yml) workflow, which takes three inputs: the version to release, the image SHA to be published, and the authors for compliance reporting. The process is fully automated: the only manual step required is approving and merging the release PR. This PR does not re-run any tests of the extensive tests.
 
-Once the PR is approved and **closed**, the [tag.yml](../../.github/workflows/release-branch.yml) workflow takes over:
-- The branch `release/X.Y.Z` would be tagged as release `vX.Y.Z`.
-  - A pre-release branch `prerelease/X.Y.Z-...` would become `vX.Y.Z-...`.
-- Then does a workflow call to [release-post-merge.yml](../../.github/workflows/release-opost-merge.yml).
+The `image_sha` refers to a previously tested and promoted operator image. This image is stored in official prerelease registries (`docker.io`, `quay.io`) and is traceable to a specific Git commit. The release workflow uses this to generate the `release/<version>` directory, which contains the `deploy`, `helm-charts`, and `bundle` folders required for every release, along with all associated metadata.
 
-Note `release-post-merge` can also be triggered by tagging a release or pre-release manually.
+A Git tag of the form v<version> is automatically created, and a GitHub release is published. This includes the zipped all-in-one.yml file and SDLC-compliant artifacts—such as SBOMs and compliance reports—as part of the release assets. 
 
-After a release is published, daily rebuilds are run by [rebuild-released-images](../../.github/workflows/rebuild-released-images.yaml):
-  - The list of [supported releases is computed dynamically](../../scripts/supported-releases.sh).
+For more information, see [`release.md`](./release.md).
+
+### Promotion Logic
+
+Operator images are promoted to official prerelease registries after passing all tests. Promotion occurs in one of three cases:
+- On **scheduled CI runs** of the `main` branch
+- On **merges to `main`** that modify production code
+- On **manual dispatch** of `tests.yml` with promotion explicitly enabled
+
+The [`promote-image.yml`](../../.github/workflows/promote-image.yml) workflow handles this promotion. It verifies that **all tests have passed**, including the **cloud-based Helm tests** that build and validate the dummy testing image. If successful:
+- The tested image is copied from `ghcr.io` to `docker.io` and `quay.io`
+- It is tagged as `promoted-<commit-sha>` for traceability
+- The `promoted-latest` tag is updated to point to this image
+
+Daily rebuilds of released images are triggered by [`rebuild-released-images`](../../.github/workflows/rebuild-released-images.yaml):
+- The list of [supported releases is computed dynamically](../../scripts/supported-releases.sh).
 
 ## Other Workflows
 

@@ -34,48 +34,57 @@ Please refer to the [CI documentation](ci.md#kubernetes-version-matrix) and subm
 
 The reason for this preparatory step is to avoid customers getting new or breaking changes before their supporting documentation.
 
-## Create the release branch
+## Create the Release
 
-Once the release notes and documentation are ready and got explicit approval to start the release:
+Once release notes and documentation are approved, trigger the [`release-image.yml`](../../.github/workflows/release-image.yml) workflow.
 
-- Use the [GitHub UI](https://github.com/mongodb/mongodb-atlas-kubernetes/actions/workflows/release-branch.yml) to create the new "Create Release Branch" workflow.
-- Specify the `version` to be released in the text box and the author MongoDB email or multiple emails in the case of multiple release authors involved in the release.
-Do not specify the whole team but only the release authors to respect SSDLC compliance requirements.
+You will be prompted to enter:
 
-The deployment scripts (K8s configs, OLM bundle) will be generated and PR will be created with new changes on behalf
-of the `github-actions` bot.
+- `version`: The version to be released (e.g., `1.10.3`), without the `v` prefix
+- `authors`: A comma-separated list of MongoDB email addresses responsible for the release
+- `image_sha`: The image tag corresponding to a previously promoted and tested operator image
 
-Pass the version with the `X.Y.Z` eg. `1.2.3`, **without** the `v...` prefix.
+### What Happens Next
 
-See [Troubleshooting](#troubleshooting) in case of issues, such as [errors with the major version](#major-version-issues-when-create-release-branch).
+Once triggered:
 
-Expect this branch to include the Software Security Development Lifecycle Policy Checklist (SSDLC) document at path `docs/releases/v${VERSION}/sdlc-compliance.md`.
-Note the SBOM files cannot be generated yet, as they require the image to have been published already.
+- A release PR is created that adds a new `release/<version>` directory (containing `deploy/`, `helm-charts/`, and `bundle/` folders)
+- A Git tag of the form `v<version>` is created and pushed
+- A GitHub release is published with:
+  - Zipped `all-in-one.yml`
+  - SDLC-compliant artifacts: SBOMs and compliance reports
 
-## Approve the Pull Request named "Release x.y.z"
+The only manual step is to **review and merge** the release PR. This PR does **not** re-run any of the expensive tests on cloud-qa.
 
-1. Review the Pull Request.
-1. Approve and merge it to `main`.
+**Note:** this directory-based approach avoids merge conflicts entirely. Because each release introduces a clean, isolated `release/<version>` folder, it can be merged directly into `main` without conflicting with prior or future releases. This enables a linear and conflict-free release history while maintaining clear traceability for each version.
 
-At this point `main` represents what would become the next release, cut the release by doing:
+---
 
-```shell
-$ export VERSION=x.y.z
-$ git checkout -b main origin/main
-$ git tag v${VERSION}
-$ git push origin v${VERSION}
-```
+## Image Promotion
+
+The `image_sha` used in a release must already be tested and promoted via CI. Promotion can occur in one of three ways:
+
+- A scheduled CI run on the `main` branch
+- A merge into `main` that includes production code changes
+- A manual dispatch of the `tests.yml` workflow with the `promote` flag enabled
+
+### How Promotion Works
+
+During promotion, the operator image used in Helm-based E2E tests is first built and published as a dummy image in `ghcr.io`. Once **all** tests—including the cloud-based Helm scenarios—complete successfully, the [`promote-image.yml`](../../.github/workflows/promote-image.yml) workflow is triggered.
+
+This workflow:
+
+- Verifies that all required tests succeeded
+- Moves the image from `ghcr.io` to both `docker.io` and `quay.io`
+- Tags the image as:
+  - `promoted-<git_sha>` — uniquely maps the image to the source Git commit
+  - `promoted-latest` — always points to the most recent image that passed all tests
 
-A new job "Create Release" will be triggered and the following will be done:
-* Atlas Operator image is built and pushed to DockerHub
-* Draft Release will be created with all commits since the previous release
-* A subsequent job will be triggered to create a SBOMs update PR
+The `promoted-latest` tag is **only updated** by scheduled runs or merges into `main` where **all** tests have executed and passed. Manual promotions will never overwrite this tag.
 
-### SSDLC SBOMs PR
+### Best Practice
 
-A new PR should have been created titled `Add SBOMs for version ...`. Please review all is as expected and merge. It should contain just a couple of new files at directory `docs/releases/v${VERSION}/`:
-- `linux-amd64.sbom.json`
-- `linux-arm64.sbom.json`
+Releases should generally use `promoted-latest` as the `image_sha`. This ensures that you are releasing the most recently tested and CI-verified image. The tag is reliably mapped to a Git commit through embedded metadata, allowing traceability without requiring the exact SHA to be specified manually. Every release run will have an echoing step which will indicate what Git commit will be used, allowing for easy debugging and validation of the source, especially when using `promoted-latest`.
 
 ## Manual SSDLC steps