feat(build): Add CLI version metadata to build upload archives (#2890)

## Summary

Adds CLI version metadata to all zip archives created during build
uploads for debugging purposes.

Resolves EME-471

## Changes

- Adds a `.sentry-cli-metadata.txt` file at the root of each build
upload zip archive
- The file contains: `sentry-cli-version: <version>`
- Applied to both single-file uploads (APK, AAB) and directory uploads
(XCArchive)
- Uses the same compression and timestamp settings as other files to
maintain consistent checksums
- Adds support for `SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE`
environment variable to override the version in tests and allow for
deterministic chunk hashes
- The version override is checked at runtime (not just during
`cfg(test)`), allowing integration tests that spawn the CLI as a
subprocess to use the override

## Testing

- Integration tests use
`SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE=0.0.0-test` to ensure
stable chunk hashes across releases
- The environment variable is properly passed to CLI subprocesses in
integration tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### New Features
 
 - Promote `sentry-cli build upload` command to non-experimental ([#2899](https://github.com/getsentry/sentry-cli/pull/2899), [#2905](https://github.com/getsentry/sentry-cli/pull/2905)).
+- Build uploads now include CLI version metadata in the uploaded archive ([#2890](https://github.com/getsentry/sentry-cli/pull/2890))
 
 ### Deprecations
 

src/commands/build/upload.rs

@@ -17,7 +17,9 @@ use crate::config::Config;
 use crate::utils::args::ArgExt as _;
 #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
 use crate::utils::build::{handle_asset_catalogs, ipa_to_xcarchive, is_apple_app, is_ipa_file};
-use crate::utils::build::{is_aab_file, is_apk_file, is_zip_file, normalize_directory};
+use crate::utils::build::{
+    is_aab_file, is_apk_file, is_zip_file, normalize_directory, write_version_metadata,
+};
 use crate::utils::chunks::{upload_chunks, Chunk};
 use crate::utils::fs::get_sha1_checksums;
 use crate::utils::fs::TempDir;
@@ -455,6 +457,8 @@ fn normalize_file(path: &Path, bytes: &[u8]) -> Result<TempFile> {
     zip.start_file(file_name, options)?;
     zip.write_all(bytes)?;
 
+    write_version_metadata(&mut zip)?;
+
     zip.finish()?;
     debug!("Successfully created normalized zip for file");
     Ok(temp_file)

src/utils/build/mod.rs

@@ -5,7 +5,7 @@ mod validation;
 
 #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
 pub use self::apple::{handle_asset_catalogs, ipa_to_xcarchive};
-pub use self::normalize::normalize_directory;
+pub use self::normalize::{normalize_directory, write_version_metadata};
 pub use self::validation::{is_aab_file, is_apk_file, is_zip_file};
 #[cfg(all(target_os = "macos", target_arch = "aarch64"))]
 pub use self::validation::{is_apple_app, is_ipa_file};

src/utils/build/normalize.rs

@@ -1,3 +1,4 @@
+use std::borrow::Cow;
 #[cfg(not(windows))]
 use std::fs;
 use std::fs::File;
@@ -6,6 +7,7 @@ use std::io::Write as _;
 use std::os::unix::fs::PermissionsExt as _;
 use std::path::{Path, PathBuf};
 
+use crate::constants::VERSION;
 use crate::utils::fs::TempFile;
 use anyhow::{Context as _, Result};
 use itertools::Itertools as _;
@@ -15,6 +17,16 @@ use walkdir::WalkDir;
 use zip::write::SimpleFileOptions;
 use zip::{DateTime, ZipWriter};
 
+fn get_version() -> Cow<'static, str> {
+    let version = Cow::Borrowed(VERSION);
+
+    // Integration tests can override the version for consistent test results.
+    // This ensures deterministic checksums in test fixtures by using a fixed version.
+    std::env::var("SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE")
+        .map(Cow::Owned)
+        .unwrap_or(version)
+}
+
 fn sort_entries(path: &Path) -> Result<impl Iterator<Item = (PathBuf, PathBuf)>> {
     Ok(WalkDir::new(path)
         .into_iter()
@@ -76,6 +88,21 @@ fn add_entries_to_zip(
     Ok(file_count)
 }
 
+fn metadata_file_options() -> SimpleFileOptions {
+    SimpleFileOptions::default()
+        .compression_method(zip::CompressionMethod::Deflated)
+        .last_modified_time(DateTime::default())
+}
+
+pub fn write_version_metadata<W: std::io::Write + std::io::Seek>(
+    zip: &mut ZipWriter<W>,
+) -> Result<()> {
+    let version = get_version();
+    zip.start_file(".sentry-cli-metadata.txt", metadata_file_options())?;
+    writeln!(zip, "sentry-cli-version: {version}")?;
+    Ok(())
+}
+
 // For XCArchive directories, we'll zip the entire directory
 // It's important to not change the contents of the directory or the size
 // analysis will be wrong and the code signature will break.
@@ -108,6 +135,8 @@ pub fn normalize_directory(path: &Path, parsed_assets_path: &Path) -> Result<Tem
         )?;
     }
 
+    write_version_metadata(&mut zip)?;
+
     zip.finish()?;
     debug!("Successfully created normalized zip for directory with {file_count} files");
     Ok(temp_file)

tests/integration/_expected_requests/build/apk_chunk.bin

@@ -162,7 +162,7 @@ fn command_build_upload_apk_chunked() {
                 if is_first_assemble_call.swap(false, Ordering::Relaxed) {
                     r#"{
                         "state": "created",
-                        "missingChunks": ["18e40e6e932d0b622d631e887be454cc2003dbb5"]
+                        "missingChunks": ["60863d91bb673a1b1b92dbbe91b1de5cc0dde146"]
                     }"#
                 } else {
                     r#"{
@@ -176,6 +176,7 @@ fn command_build_upload_apk_chunked() {
             .expect(2),
         )
         .register_trycmd_test("build/build-upload-apk.trycmd")
+        .env("SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE", "0.0.0-test")
         .with_default_token();
 }