Generalise migration version iteration modes

Add `version-iteration` (false/major/minor/patch) and
`if-no-iterations` (error/pass) inputs to give explicit control over
which intermediate versions are generated during multi-version jumps.

The old `iterate-v0-minors` input is deprecated and mutually exclusive
with `version-iteration`.  When neither input is set, the action
preserves the historical v0.x minor iteration behaviour but emits a
deprecation warning asking users to set `version-iteration` explicitly.
The implicit default will change in a future release.

Input resolution order:

  1. `version-iteration` set → use it directly; error if
     `iterate-v0-minors` is also set (mutually exclusive).
  2. `iterate-v0-minors` set → map to the new mode with a deprecation
     warning; `if-no-iterations` defaults to "pass" for v0.x.
  3. Neither set → backward-compatible default (v0.x minor iteration,
     `if-no-iterations` defaults to "pass"); deprecation warning
     emitted.

`if-no-iterations` defaults to "error" under explicit
`version-iteration` modes and "pass" under the deprecated and implicit
paths, so existing workflows see no behaviour change.  The
empty-versions path now distinguishes error (exit 1,
`migration_ran=false`) from pass (exit 0, `migration_ran=true`), fixing
the downstream labelling/auto-merge flow.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

AGENTS.md

@@ -56,9 +56,10 @@ conditions, output references, and step IDs are consistent.
 ## Repository layout
 
 ```
-action.yml                  # Composite action definition (19 steps)
+action.yml                  # Composite action definition
 scripts/run-migration.sh    # Helper: run migration scripts
 scripts/build-report.sh     # Helper: build Markdown summary
+scripts/check-update.sh     # Helper: decide if migration is needed
 scripts/create-label.sh     # Helper: ensure label exists/updated
 scripts/add-label.sh        # Helper: ensure/add PR labels
 scripts/remove-label.sh     # Helper: remove PR labels safely

README.md

@@ -37,6 +37,13 @@ script reports manual intervention is needed.
 4. For each version in the upgrade range, the migration script is
    downloaded from the URL template (or the inline script is used) and
    executed.
+   If the selected `version-iteration` mode produces no versions, the
+   action fails by default so the unexpected no-op is visible.  Set
+   `if-no-iterations: "pass"` to treat that edge case as a clean
+   migration with no file changes.  (When `version-iteration` is not
+   set, the implicit v0.x default and the deprecated
+   `iterate-v0-minors` fallback both default to `"pass"` for backward
+   compatibility.)
 5. File changes are committed to the PR branch.
 6. A PR comment and job summary are posted with the results.
 7. If all migrations succeed (exit code 0) **and** auto-merge is enabled
@@ -117,6 +124,21 @@ upgrade range.  Scripts must follow these conventions:
   This is always set, regardless of whether the script was provided
   via URL template or inline.
 
+* **Version iteration** — `version-iteration` controls which versions
+  are generated for multi-version jumps.  Explicit values are `"false"`,
+  `"major"`, `"minor"`, and `"patch"`.  When empty (the default), the
+  action preserves backward-compatible behaviour (v0.x bumps iterate
+  intermediate minors, other bumps target only the new version) and
+  emits a deprecation warning — set `version-iteration` explicitly to
+  silence the warning.  Boundary-only modes can legitimately produce no
+  versions when the Dependabot update does not cross that boundary.  In
+  that case, `if-no-iterations` controls whether the action fails
+  (`"error"`) or passes as a no-op migration (`"pass"`).  When
+  `if-no-iterations` is empty (the default), it uses `"error"` — except
+  under the implicit v0.x default and the deprecated
+  `iterate-v0-minors` fallback, where it uses `"pass"` for backward
+  compatibility.
+
 * **Exit code** — return **0** if the migration succeeded.  Return a
   **non-zero** exit code if manual intervention is needed.  A non-zero
   exit causes the action to add the `intervention-pending` label, fail
@@ -233,7 +255,9 @@ jobs:
 | `auto-merge-on-changes` | no | `"false"` | Auto-approve and auto-merge even when the migration produced commits (requires `token`) |
 | `sign-commits` | no | `"false"` | When `"true"`, create migration commits via API so commits have verified signatures (when supported, for example when using a GitHub App for `token`) |
 | `report-title` | no | `""` | Heading used for PR comments and job summaries; when empty, uses the calling workflow title |
-| `iterate-v0-minors` | no | `"true"` | Iterate through intermediate v0.x minor versions |
+| `version-iteration` | no | `""` | Controls generated migration versions: `"false"` runs only the target version; `"major"`, `"minor"`, and `"patch"` iterate semver boundaries.  When empty, the action preserves backward-compatible behaviour (v0.x minor iteration) and emits a deprecation warning — set this explicitly to silence the warning. |
+| `if-no-iterations` | no | `""` | What to do when `version-iteration` produces no versions: `"error"` fails the action; `"pass"` treats it as a clean no-op migration.  Defaults to `"error"` — except under the implicit v0.x default and the deprecated `iterate-v0-minors` fallback, where it defaults to `"pass"`. |
+| `iterate-v0-minors` | no | `""` | Deprecated; use `version-iteration` instead.  When set to "true", v0.x bumps iterate intermediate minor versions; when "false", only the target version is run.  When empty (default), the implicit v0.x minor iteration applies instead.  Mutually exclusive with `version-iteration`. |
 | `python-version` | no | `"3.14"` | Python version for running the script |
 | `expected-actor` | no | `dependabot[bot]` | GitHub actor whose PRs trigger migration and auto-approval (gates metadata fetch, migration decision, and patch-only auto-approve) |
 | `migrated-label` | no | `migrated` | Label name for migrated state |
@@ -253,9 +277,9 @@ jobs:
 
 | Output | Description |
 |---|---|
-| `migration_ran` | Whether the migration script(s) executed |
+| `migration_ran` | Whether migration has been handled: `"true"` when script(s) executed, no versions needed migrating, the PR was already migrated, or the update is patch-only without `version-iteration`; `"false"` otherwise. |
 | `overall_exit` | Consolidated exit code: `"0"` if all scripts succeeded, `"1"` if any required intervention |
-| `needs_migration` | `"true"` for minor/major bumps, `"false"` for patch-only |
+| `needs_migration` | `"true"` for minor/major bumps (always) and patch bumps (when `version-iteration` is set), `"false"` for patch-only without `version-iteration` |
 | `commit_made` | Whether the migration produced a commit |
 
 ### Requirements

action.yml

@@ -82,6 +82,7 @@
 #  21. Approve and auto-merge             – clean migration only
 #  22. Handle patch-only updates          – auto-merge with token,
 #                                           otherwise instruct manual review
+#  23. Resolve migration_ran              – always(), consolidate output
 #
 # Label ordering (step 19): intervention-pending-label is added BEFORE
 # migrated-label.  If interrupted between the two API calls, the PR
@@ -168,13 +169,38 @@ inputs:
       When empty, the calling workflow title is used.
     required: false
     default: ""
+  version-iteration:
+    description: >-
+      Controls which intermediate versions to run migration scripts
+      for when a multi-version jump is detected.  "false" runs only
+      the target version; "major" runs for each major boundary
+      (vX.0.0); "minor" also runs for each minor boundary within
+      the target major; "patch" also runs for each patch within the
+      target minor.  When empty (default), falls back to the
+      deprecated `iterate-v0-minors` input for backward
+      compatibility.
+    required: false
+    default: ""
+  if-no-iterations:
+    description: >-
+      Controls what happens when `version-iteration` produces no
+      versions to migrate.  "error" fails the action so the
+      unexpected no-op is not missed; "pass" treats it as a clean
+      migration with no file changes.  When empty (default), uses
+      "error" — except under the deprecated `iterate-v0-minors`
+      fallback, where it defaults to "pass" for backward
+      compatibility.
+    required: false
+    default: ""
   iterate-v0-minors:
     description: >-
-      When "true" (default), v0.x bumps iterate through each
-      intermediate minor version.  When "false", only the target
-      version is run.
+      Deprecated — use `version-iteration` instead.  When "true",
+      v0.x bumps iterate through each intermediate minor version.
+      When "false", only the target version is run.  When empty
+      (default), the input is inactive.  Mutually exclusive with
+      `version-iteration`.
     required: false
-    default: "true"
+    default: ""
   python-version:
     description: >-
       Python version to use for running the migration script.
@@ -261,17 +287,24 @@ inputs:
 
 outputs:
   migration_ran:
-    description: Whether the migration script(s) executed.
-    value: ${{ steps.run-migration.outputs.migration_ran }}
+    description: >-
+      Whether migration has been handled: "true" when script(s)
+      executed, when no versions needed migrating and
+      `if-no-iterations` is "pass", when a previous run already
+      migrated this PR, or when the update is patch-only without
+      `version-iteration`.  "false" otherwise.
+    value: ${{ steps.resolve-migration-ran.outputs.migration_ran }}
   overall_exit:
     description: >-
       Consolidated exit code: "0" if all scripts succeeded, "1" if
       any required intervention.
     value: ${{ steps.run-migration.outputs.overall_exit }}
   needs_migration:
     description: >-
-      Whether a migration was needed: "true" for minor/major bumps,
-      "false" for patch-only.
+      Whether the update entered the migration flow: "true" for
+      minor/major bumps (always) and patch bumps (when
+      version-iteration is set), "false" for patch-only bumps
+      without version-iteration.
     value: ${{ steps.check-update.outputs.needs_migration }}
   commit_made:
     description: Whether the migration produced a commit.
@@ -293,6 +326,9 @@ runs:
         AUTO_MERGE_ON_CHANGES: ${{ inputs.auto-merge-on-changes }}
         SCRIPT_URL_TEMPLATE: ${{ inputs.script-url-template }}
         MIGRATION_SCRIPT: ${{ inputs.migration-script }}
+        VERSION_ITERATION: ${{ inputs.version-iteration }}
+        IF_NO_ITERATIONS: ${{ inputs.if-no-iterations }}
+        ITERATE_V0_MINORS: ${{ inputs.iterate-v0-minors }}
       run: |
         if [ -n "$SCRIPT_URL_TEMPLATE" ] && [ -n "$MIGRATION_SCRIPT" ]; then
           echo "::error::\`script-url-template\` and \`migration-script\` are" \
@@ -312,6 +348,33 @@ runs:
           exit 1
         fi
 
+        if [ -n "$VERSION_ITERATION" ]; then
+          case "$VERSION_ITERATION" in
+            false|major|minor|patch) ;;
+            *)
+              echo "::error::\`version-iteration\` must be one of:" \
+                "false, major, minor, patch."
+              exit 1
+              ;;
+          esac
+        fi
+
+        if [ -n "$VERSION_ITERATION" ] && [ -n "$ITERATE_V0_MINORS" ]; then
+          echo "::error::\`version-iteration\` and \`iterate-v0-minors\` are" \
+            "mutually exclusive — remove \`iterate-v0-minors\` when using" \
+            "\`version-iteration\`."
+          exit 1
+        fi
+
+        case "$IF_NO_ITERATIONS" in
+          ""|error|pass) ;;
+          *)
+            echo "::error::\`if-no-iterations\` must be one of:" \
+              "error, pass."
+            exit 1
+            ;;
+        esac
+
     # ── 2. Determine current state from PR labels ──────────────────────
     #
     # Read the PR labels to figure out whether the migration has already
@@ -423,9 +486,16 @@ runs:
 
     # ── 6. Decide whether a migration is needed ────────────────────────
     #
-    # Patch-only bumps never need migration.  Versions are resolved
-    # from updated-dependencies-json for both single and grouped
-    # updates.
+    # Versions are resolved from updated-dependencies-json for both
+    # single and grouped updates.
+    #
+    # When version-iteration is NOT set (backward-compat path), patch-
+    # only bumps short-circuit here — run-migration.sh never runs and
+    # handle-patch-update.sh handles them instead.
+    #
+    # When version-iteration IS set, all update types — including
+    # patch — flow through run-migration.sh so that the configured
+    # iteration strategy is honoured.
     - name: Check update type
       if: >-
         steps.check-status.outputs.already_migrated == 'false'
@@ -437,53 +507,9 @@ runs:
       env:
         UPDATE_TYPE: ${{ steps.dependabot-metadata.outputs.update-type }}
         DEPS_JSON: ${{ steps.dependabot-metadata.outputs.updated-dependencies-json }}
+        VERSION_ITERATION: ${{ inputs.version-iteration }}
       run: |
-        if ! command -v jq >/dev/null 2>&1; then
-          echo "::error::jq is required to parse updated-dependencies-json."
-          exit 1
-        fi
-
-        OLD_VERSIONS=$(echo "$DEPS_JSON" \
-          | jq -r '.[].prevVersion | select(. != "" and . != null)')
-        NEW_VERSIONS=$(echo "$DEPS_JSON" \
-          | jq -r '.[].newVersion | select(. != "" and . != null)')
-
-        if [ -z "$OLD_VERSIONS" ] || [ -z "$NEW_VERSIONS" ]; then
-          echo "::error::Could not resolve versions from updated-dependencies-json."
-          echo "::error::updated-dependencies-json: $DEPS_JSON"
-          exit 1
-        fi
-
-        OLD_VERSION=$(echo "$OLD_VERSIONS" | sort -V | head -1)
-        NEW_VERSION=$(echo "$NEW_VERSIONS" | sort -V | tail -1)
-        echo "Resolved update range: ${OLD_VERSION} → ${NEW_VERSION}"
-
-        if [ -z "$UPDATE_TYPE" ]; then
-          if echo "$DEPS_JSON" \
-            | jq -e '.[] | select(.updateType == "version-update:semver-major")' \
-              >/dev/null; then
-            UPDATE_TYPE="version-update:semver-major"
-          elif echo "$DEPS_JSON" \
-            | jq -e '.[] | select(.updateType == "version-update:semver-minor")' \
-              >/dev/null; then
-            UPDATE_TYPE="version-update:semver-minor"
-          else
-            UPDATE_TYPE="version-update:semver-patch"
-          fi
-        fi
-
-        {
-          echo "update_type=$UPDATE_TYPE"
-          echo "old_version=$OLD_VERSION"
-          echo "new_version=$NEW_VERSION"
-        } >>"$GITHUB_OUTPUT"
-
-        if [ "$UPDATE_TYPE" = "version-update:semver-patch" ]; then
-          echo "needs_migration=false" >>"$GITHUB_OUTPUT"
-          echo "Patch update only — no migration needed."
-        else
-          echo "needs_migration=true" >>"$GITHUB_OUTPUT"
-        fi
+        bash "${{ github.action_path }}/scripts/check-update.sh"
 
     # ── 7. Checkout the PR branch so the migration can modify files ────
     - name: Checkout PR branch
@@ -519,6 +545,8 @@ runs:
         UPDATED_DEPENDENCIES_JSON: ${{ steps.dependabot-metadata.outputs.updated-dependencies-json }}
         SCRIPT_URL_TEMPLATE: ${{ inputs.script-url-template }}
         MIGRATION_SCRIPT: ${{ inputs.migration-script }}
+        VERSION_ITERATION: ${{ inputs.version-iteration }}
+        IF_NO_ITERATIONS: ${{ inputs.if-no-iterations }}
         ITERATE_V0_MINORS: ${{ inputs.iterate-v0-minors }}
         MIGRATION_TOKEN_INPUT: ${{ inputs.migration-token }}
         ACTION_PATH: ${{ github.action_path }}
@@ -851,3 +879,29 @@ runs:
           ${{ inputs.auto-merged-label-description }}
         REPORT_TITLE: ${{ inputs.report-title || github.workflow }}
       run: "${{ github.action_path }}/scripts/handle-patch-update.sh"
+
+    # ── 23. Resolve migration_ran ───────────────────────────────────────
+    #
+    # Runs with `always()` so the output is set in every code path:
+    # migration ran, no-iteration pass/error, patch-only update, or
+    # already-migrated re-trigger.  Internal steps (10-22) still gate
+    # on steps.run-migration.outputs.migration_ran; this step only
+    # feeds the external output.
+    - name: Resolve migration_ran
+      id: resolve-migration-ran
+      if: always()
+      shell: bash
+      env:
+        SCRIPT_MIGRATION_RAN: ${{ steps.run-migration.outputs.migration_ran }}
+        ALREADY_MIGRATED: ${{ steps.check-status.outputs.already_migrated }}
+        NEEDS_MIGRATION: ${{ steps.check-update.outputs.needs_migration }}
+      run: |
+        if [ -n "$SCRIPT_MIGRATION_RAN" ]; then
+          echo "migration_ran=$SCRIPT_MIGRATION_RAN" >>"$GITHUB_OUTPUT"
+        elif [ "$ALREADY_MIGRATED" = "true" ]; then
+          echo "migration_ran=true" >>"$GITHUB_OUTPUT"
+        elif [ "$NEEDS_MIGRATION" = "false" ]; then
+          echo "migration_ran=true" >>"$GITHUB_OUTPUT"
+        else
+          echo "migration_ran=false" >>"$GITHUB_OUTPUT"
+        fi

scripts/check-update.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# License: MIT
+# Copyright © 2026 Frequenz Energy-as-a-Service GmbH
+#
+# Decide whether a migration is needed based on the Dependabot
+# update metadata.
+#
+# Resolves the old/new version range from the updated-dependencies
+# JSON and determines the update type.  When version-iteration is
+# NOT set (backward-compat path), patch-only bumps short-circuit
+# with needs_migration=false so that handle-patch-update.sh can
+# handle them.  When version-iteration IS set, all update types
+# — including patch — are forwarded to run-migration.sh.
+#
+# Expected environment variables (set by the composite action):
+#   UPDATE_TYPE        – update type from dependabot/fetch-metadata
+#                        (may be empty for grouped updates)
+#   DEPS_JSON          – updated-dependencies-json from
+#                        dependabot/fetch-metadata
+#   VERSION_ITERATION  – iteration mode (empty when not set)
+
+set -euo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "::error::jq is required to parse updated-dependencies-json."
+  exit 1
+fi
+
+OLD_VERSIONS=$(echo "$DEPS_JSON" \
+  | jq -r '.[].prevVersion | select(. != "" and . != null)')
+NEW_VERSIONS=$(echo "$DEPS_JSON" \
+  | jq -r '.[].newVersion | select(. != "" and . != null)')
+
+if [ -z "$OLD_VERSIONS" ] || [ -z "$NEW_VERSIONS" ]; then
+  echo "::error::Could not resolve versions from updated-dependencies-json."
+  echo "::error::updated-dependencies-json: $DEPS_JSON"
+  exit 1
+fi
+
+OLD_VERSION=$(echo "$OLD_VERSIONS" | sort -V | head -1)
+NEW_VERSION=$(echo "$NEW_VERSIONS" | sort -V | tail -1)
+echo "Resolved update range: ${OLD_VERSION} → ${NEW_VERSION}"
+
+if [ -z "$UPDATE_TYPE" ]; then
+  if echo "$DEPS_JSON" \
+    | jq -e '.[] | select(.updateType == "version-update:semver-major")' \
+      >/dev/null; then
+    UPDATE_TYPE="version-update:semver-major"
+  elif echo "$DEPS_JSON" \
+    | jq -e '.[] | select(.updateType == "version-update:semver-minor")' \
+      >/dev/null; then
+    UPDATE_TYPE="version-update:semver-minor"
+  else
+    UPDATE_TYPE="version-update:semver-patch"
+  fi
+fi
+
+{
+  echo "update_type=$UPDATE_TYPE"
+  echo "old_version=$OLD_VERSION"
+  echo "new_version=$NEW_VERSION"
+} >>"$GITHUB_OUTPUT"
+
+if [ -z "$VERSION_ITERATION" ] \
+  && [ "$UPDATE_TYPE" = "version-update:semver-patch" ]; then
+  echo "needs_migration=false" >>"$GITHUB_OUTPUT"
+  echo "Patch update only — no migration needed."
+else
+  echo "needs_migration=true" >>"$GITHUB_OUTPUT"
+fi