feat(cli): plumb release tag into mergify --version (#1576)

`Cargo.toml` is pinned at `0.0.0` because cargo's semver rejects the
project's 4-component calver (`2026.4.23.1`), so `--version` reported
the placeholder on every release wheel — bad signal for support and
diagnostics, and the reason the flag had been disabled outright.

Solution: keep `Cargo.toml` at the placeholder, but accept the real
version via a `MERGIFY_RELEASE_VERSION` env var the release workflow
sets from `$GITHUB_REF`. `crates/mergify-cli/build.rs` re-exports it
as a `rustc-env` so `option_env!` at compile time can fold it into a
`VERSION` const, with `CARGO_PKG_VERSION` as the dev-build fallback.
Clap reads `VERSION` directly (re-enabling `--version`), and the CLI
schema generator (`_internal dump-cli-schema`) routes through the
same const so the published reference matches what the binary says.

The release path is the same as before: `build-wheels.yml`'s stamp
step still writes the tag into `pyproject.toml`; it now also pushes
the same value into `$GITHUB_ENV` so the maturin build sees it. PR
smoke builds skip the stamp step, so the binary reports `0.0.0` —
locked in by a new `mergify --version` smoke test in CI and two
unit tests pinning the `--version` flag and the env fallback.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jd

.github/workflows/build-wheels.yml

@@ -76,6 +76,12 @@ jobs:
           rm -f pyproject.toml.bak
           echo "Stamped pyproject.toml:"
           grep '^version = ' pyproject.toml
+          # Propagate the tag into the maturin build so `mergify
+          # --version` reports it. `Cargo.toml` stays at `0.0.0`
+          # (cargo's semver rejects the 4-component calver), and
+          # `crates/mergify-cli/build.rs` re-exports this env var
+          # as a `rustc-env` for the binary's `VERSION` const.
+          echo "MERGIFY_RELEASE_VERSION=${VERSION}" >> "${GITHUB_ENV}"
 
       - name: Build wheel
         uses: PyO3/maturin-action@v1

.github/workflows/ci.yaml

@@ -85,6 +85,23 @@ jobs:
         shell: bash
         run: mergify --help
 
+      # Lock the dev-build version fallback in. Release builds get
+      # `MERGIFY_RELEASE_VERSION` from the stamp step in
+      # `build-wheels.yml`; PR smoke builds don't, so the binary
+      # must report `Cargo.toml`'s `0.0.0` placeholder. If this
+      # ever changes silently, every release-version assumption
+      # downstream (PyPI install reporting, support diagnostics)
+      # rests on the same code path — catch the drift here.
+      - name: mergify --version reports placeholder on unstamped build
+        shell: bash
+        run: |
+          out=$(mergify --version)
+          echo "$out"
+          [[ "$out" == "mergify 0.0.0" ]] || {
+            echo "expected 'mergify 0.0.0', got '$out'"
+            exit 1
+          }
+
   ci-gate:
     if: ${{ !cancelled() }}
     needs:

crates/mergify-cli/build.rs

@@ -0,0 +1,22 @@
+//! Plumb the release version through to the binary.
+//!
+//! Cargo's semver rejects the project's 4-component calver
+//! (`2026.4.23.1`), so `Cargo.toml` is pinned at the `0.0.0`
+//! placeholder and the real version comes in via the
+//! `MERGIFY_RELEASE_VERSION` env var the release workflow sets
+//! from `$GITHUB_REF`. This script normalises that input into a
+//! single rustc-env (`MERGIFY_CLI_VERSION`) the binary reads
+//! unconditionally — empty / unset both collapse to
+//! `CARGO_PKG_VERSION` here, so `main.rs` is a one-liner that
+//! can't accidentally surface an empty version string.
+
+fn main() {
+    // Rebuild when the env var changes so a release rebuild after a
+    // dev build actually picks up the new value.
+    println!("cargo:rerun-if-env-changed=MERGIFY_RELEASE_VERSION");
+    let resolved = std::env::var("MERGIFY_RELEASE_VERSION")
+        .ok()
+        .filter(|v| !v.is_empty())
+        .unwrap_or_else(|| env!("CARGO_PKG_VERSION").to_string());
+    println!("cargo:rustc-env=MERGIFY_CLI_VERSION={resolved}");
+}

crates/mergify-cli/src/cli_schema.rs

@@ -117,7 +117,7 @@ pub fn build() -> CliSchema {
         generator: "mergify _internal dump-cli-schema",
         cli: CliInfo {
             name: root.get_name().to_string(),
-            version: env!("CARGO_PKG_VERSION"),
+            version: crate::VERSION,
             about: root.get_about().map(ToString::to_string),
         },
         command,

crates/mergify-cli/src/main.rs

@@ -39,6 +39,14 @@ use mergify_queue::unpause::UnpauseOptions;
 
 mod cli_schema;
 
+/// User-visible CLI version. `build.rs` normalises the
+/// `MERGIFY_RELEASE_VERSION` env var the release workflow sets
+/// from `$GITHUB_REF` (unset or empty => `CARGO_PKG_VERSION`,
+/// i.e. the `0.0.0` placeholder), and writes the result to the
+/// `MERGIFY_CLI_VERSION` rustc-env. Reading the normalised var
+/// directly means this side can't surface an empty string.
+const VERSION: &str = env!("MERGIFY_CLI_VERSION");
+
 fn main() -> ExitCode {
     let argv: Vec<String> = env::args().skip(1).collect();
 
@@ -2607,8 +2615,7 @@ fn run_native(cmd: NativeCommand) -> ExitCode {
 }
 
 #[derive(Parser)]
-#[command(name = "mergify", disable_help_subcommand = true)]
-#[command(disable_version_flag = true)]
+#[command(name = "mergify", disable_help_subcommand = true, version = VERSION)]
 struct CliRoot {
     /// Enable verbose debug logging. Mirrors the Python CLI's
     /// top-level `--debug` flag so the same invocations work
@@ -4100,6 +4107,44 @@ mod tests {
         );
     }
 
+    #[test]
+    fn version_const_matches_release_env_or_falls_back_to_cargo_pkg_version() {
+        // Mirror `build.rs` exactly: empty `MERGIFY_RELEASE_VERSION`
+        // is treated the same as unset, both collapse to
+        // `CARGO_PKG_VERSION`. The release path is exercised in
+        // `build-wheels.yml`'s stamp step (sets a non-empty calver,
+        // expects it in `--version`); this test pins both fallback
+        // branches so build.rs's normalisation can't drift.
+        let expected = match option_env!("MERGIFY_RELEASE_VERSION") {
+            Some(v) if !v.is_empty() => v,
+            _ => env!("CARGO_PKG_VERSION"),
+        };
+        assert_eq!(VERSION, expected);
+    }
+
+    #[test]
+    fn cli_root_exposes_version_flag() {
+        // Locked-in regression: a previous incarnation had
+        // `disable_version_flag = true` because the version source
+        // was wrong; switching to the env-driven const lets clap
+        // render `--version` properly. If a future refactor
+        // removes the `version = VERSION` attribute, `--version`
+        // silently becomes an unknown flag and this catches it.
+        //
+        // `try_parse_from(...).err().expect(...)` over `expect_err`
+        // because the Ok variant is `CliRoot` which doesn't
+        // implement `Debug` (and shouldn't — it carries no debug
+        // intent).
+        let err = CliRoot::try_parse_from(["mergify", "--version"])
+            .err()
+            .expect("--version exits");
+        assert_eq!(err.kind(), clap::error::ErrorKind::DisplayVersion);
+        assert!(
+            err.to_string().contains(VERSION),
+            "version output should contain VERSION ({VERSION}), got: {err}",
+        );
+    }
+
     #[test]
     fn ci_scopes_parses_when_mergify_config_path_env_var_is_empty() {
         // Regression for monorepo#33423 / gha-mergify-ci: