From 9749e9770a2133afc135f38ceda553af9e5dc916 Mon Sep 17 00:00:00 2001
From: Simon Mundy <simon.mundy@peptolab.com>
Date: Wed, 4 Nov 2026 10:48:29 +1100
Subject: [PATCH] Pin Mago to 1.59.0 in CI

setup-php installed whatever Mago release was latest, so a new release
could fail every consumer's CI with no change on their side. 1.59.0
did exactly that to php-db/phpdb's 0.6.x.

The mago and mutation-test jobs now install the release named by a new
mago-version input, defaulting to 1.59.0. mago.toml pins the same
version, so a local binary that differs is flagged with a warning.
---
 .github/workflows/continuous-integration.yml | 9 +++++++--
 docs/workflow-architecture.md                | 3 ++-
 mago.toml                                    | 2 +-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
index 7908cc2..2900b0f 100644
--- a/.github/workflows/continuous-integration.yml
+++ b/.github/workflows/continuous-integration.yml
@@ -73,6 +73,11 @@ on:
         type: string
         required: false
         default: "10"
+      mago-version:
+        description: "Mago release installed for the format, lint, analyze, guard and mutation-test jobs. Keep in step with the version in mago.toml."
+        type: string
+        required: false
+        default: "1.59.0"
       test-env-json:
         description: "JSON object of extra env vars exported before running tests (e.g. to override a phpunit.xml.dist connection setting for CI, since PHPUnit's <env> won't override an already-set real env var)."
         type: string
@@ -101,7 +106,7 @@ jobs:
         with:
           php-version: ${{ matrix.php }}
           coverage: none
-          tools: mago
+          tools: mago:${{ inputs.mago-version }}
 
       - name: Install dependencies
         run: composer install --no-interaction --no-progress ${{ inputs.composer-options }}
@@ -248,7 +253,7 @@ jobs:
         with:
           php-version: ${{ inputs.coverage-php-version }}
           coverage: pcov
-          tools: mago
+          tools: mago:${{ inputs.mago-version }}
 
       - name: Start DB service
         if: inputs.db-image != '' && inputs.run-integration
diff --git a/docs/workflow-architecture.md b/docs/workflow-architecture.md
index 0184b30..5a286d4 100644
--- a/docs/workflow-architecture.md
+++ b/docs/workflow-architecture.md
@@ -25,7 +25,7 @@ graph LR
 ## `mago` job
 
 Matrix: `php-versions` only. Runs `mago format --check`, `mago lint`,
-`mago analyze`, `mago guard`. No DB, no dependency-strategy matrix — the
+`mago analyze`, `mago guard` with the Mago release named by `mago-version`. No DB, no dependency-strategy matrix — the
 committed `composer.lock` is enough for type resolution.
 
 ## `test` job
@@ -162,6 +162,7 @@ within the same GitHub org.
 | `coverage-php-version` | Which matrix leg is canonical for coverage/mutation. |
 | `min-msi` | Minimum MSI (%) required to pass `mutation-test` (default `"10"`, config-based per repo). |
 | `min-covered-msi` | Minimum covered-code MSI (%) required to pass `mutation-test` (default `"10"`, config-based per repo). |
+| `mago-version` | Mago release installed by `mago` and `mutation-test` (default `"1.59.0"`). Pinned so a new Mago release can't fail CI without a code change; keep it in step with `version` in `mago.toml`. |
 | `test-env-json` | JSON object of extra env vars exported (via `$GITHUB_ENV`) before running tests in `test` and `mutation-test`. |
 
 Plus `secrets: CODECOV_TOKEN`, `INFECTION_DASHBOARD_API_KEY` on
diff --git a/mago.toml b/mago.toml
index 00b28b6..147c1b7 100644
--- a/mago.toml
+++ b/mago.toml
@@ -10,7 +10,7 @@
 #   [source]
 #   paths = ["src", "test"]
 #   includes = ["vendor"]
-version = "1"
+version = "1.59.0"
 
 [formatter]
 preset = "default"