maven_artifact: resolve SNAPSHOT to latest using snapshot metadata block (#11501)

* fix(maven_artifact): resolve SNAPSHOT to latest using snapshot metadata block

Prefer the <snapshot> block (timestamp + buildNumber) from maven-metadata.xml
which always points to the latest build, instead of scanning <snapshotVersions>
and returning on the first match. Repositories like GitHub Packages keep all
historical entries in <snapshotVersions> (oldest first), causing the module to
resolve to the oldest snapshot instead of the latest.

Fixes #5117
Fixes #11489

* fix(maven_artifact): address review feedback

- Check both timestamp and buildNumber before using snapshot block,
  preventing IndexError when buildNumber is missing
- Remove unreliable snapshotVersions scanning fallback; use literal
  -SNAPSHOT version for non-unique snapshot repos instead
- Add tests for incomplete snapshot block and non-SNAPSHOT versions

* fix(maven_artifact): restore snapshotVersions scanning with last-match

Restore <snapshotVersions> scanning as primary resolution (needed for
per-extension accuracy per MNG-5459), but collect the last match instead
of returning on the first. Fall back to <snapshot> block when no
<snapshotVersions> match is found, then to literal -SNAPSHOT version.

* docs: update changelog fragment to match final implementation

* fix(maven_artifact): use updated timestamp for snapshot resolution

Use the <updated> attribute to select the newest snapshotVersion entry
instead of relying on list order. This works independently of how the
repository manager sorts entries in maven-metadata.xml.

Also fix test docstring and update changelog fragment per reviewer
feedback.

* test(maven_artifact): shuffle entries to verify updated timestamp sorting

Reorder snapshotVersion entries so the newest JAR is in the middle,
not at the end. This ensures the test actually validates that resolution
uses the <updated> timestamp rather than relying on list position.

changelogs/fragments/5117-maven-artifact-snapshot-resolution.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - maven_artifact - fix SNAPSHOT version resolution to pick the newest matching ``<snapshotVersion>`` entry by ``<updated>`` timestamp instead of the first. Repositories like GitHub Packages keep all historical entries in ``<snapshotVersions>`` (oldest first), causing the module to resolve to the oldest snapshot instead of the latest (https://github.com/ansible-collections/community.general/issues/5117, https://github.com/ansible-collections/community.general/issues/11489, https://github.com/ansible-collections/community.general/pull/11501).

plugins/modules/maven_artifact.py

@@ -465,17 +465,25 @@ class MavenDownloader:
             content = self._getContent(self.base + path, f"Failed to retrieve the maven metadata file: {path}")
             xml = etree.fromstring(content)
 
-            for snapshotArtifact in xml.xpath("/metadata/versioning/snapshotVersions/snapshotVersion"):
+            candidates = []
-                classifier = snapshotArtifact.xpath("classifier/text()")
+            for snapshot_artifact in xml.xpath("/metadata/versioning/snapshotVersions/snapshotVersion"):
-                artifact_classifier = classifier[0] if classifier else ""
+                classifier = snapshot_artifact.xpath("classifier/text()")
-                extension = snapshotArtifact.xpath("extension/text()")
+                extension = snapshot_artifact.xpath("extension/text()")
-                artifact_extension = extension[0] if extension else ""
+                if (classifier[0] if classifier else "") == artifact.classifier and (
-                if artifact_classifier == artifact.classifier and artifact_extension == artifact.extension:
+                    extension[0] if extension else ""
-                    return self._uri_for_artifact(artifact, snapshotArtifact.xpath("value/text()")[0])
+                ) == artifact.extension:
+                    value = snapshot_artifact.xpath("value/text()")
+                    updated = snapshot_artifact.xpath("updated/text()")
+                    if value:
+                        candidates.append((updated[0] if updated else "", value[0]))
+            if candidates:
+                # updated is yyyymmddHHMMSS, so lexical max == newest
+                return self._uri_for_artifact(artifact, max(candidates, key=lambda item: item[0])[1])
             timestamp_xmlpath = xml.xpath("/metadata/versioning/snapshot/timestamp/text()")
-            if timestamp_xmlpath:
+            build_number_xmlpath = xml.xpath("/metadata/versioning/snapshot/buildNumber/text()")
+            if timestamp_xmlpath and build_number_xmlpath:
                 timestamp = timestamp_xmlpath[0]
-                build_number = xml.xpath("/metadata/versioning/snapshot/buildNumber/text()")[0]
+                build_number = build_number_xmlpath[0]
                 return self._uri_for_artifact(
                     artifact, artifact.version.replace("SNAPSHOT", f"{timestamp}-{build_number}")
                 )

tests/unit/plugins/modules/test_maven_artifact.py

@@ -72,3 +72,166 @@ def test_find_version_by_spec(mocker, version_by_spec, version_choosed):
     mvn_downloader = maven_artifact.MavenDownloader(basic.AnsibleModule, "https://repo1.maven.org/maven2")
 
     assert mvn_downloader.find_version_by_spec(artifact) == version_choosed
+
+
+# Metadata with multiple snapshotVersion entries per extension (as produced by GitHub Packages).
+# The entries are deliberately NOT in chronological order to verify that
+# resolution uses the <updated> timestamp rather than relying on list position.
+snapshot_metadata_multiple_entries = b"""<?xml version="1.0" encoding="UTF-8"?>
+<metadata>
+  <groupId>com.example</groupId>
+  <artifactId>my-lib</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+  <versioning>
+    <snapshot>
+      <timestamp>20260210.152345</timestamp>
+      <buildNumber>3</buildNumber>
+    </snapshot>
+    <lastUpdated>20260210153158</lastUpdated>
+    <snapshotVersions>
+      <snapshotVersion>
+        <extension>jar</extension>
+        <value>1.0.0-20260205.091032-2</value>
+        <updated>20260205091858</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>jar</extension>
+        <value>1.0.0-20260210.152345-3</value>
+        <updated>20260210153154</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>pom</extension>
+        <value>1.0.0-20260210.152345-3</value>
+        <updated>20260210153153</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>jar</extension>
+        <value>1.0.0-20260203.123107-1</value>
+        <updated>20260203123944</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>pom</extension>
+        <value>1.0.0-20260203.123107-1</value>
+        <updated>20260203123943</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>pom</extension>
+        <value>1.0.0-20260205.091032-2</value>
+        <updated>20260205091857</updated>
+      </snapshotVersion>
+    </snapshotVersions>
+  </versioning>
+</metadata>
+"""
+
+# Metadata without a <snapshot> block but with <snapshotVersions> only.
+snapshot_metadata_no_snapshot_block = b"""<?xml version="1.0" encoding="UTF-8"?>
+<metadata>
+  <groupId>com.example</groupId>
+  <artifactId>my-lib</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+  <versioning>
+    <lastUpdated>20260210153158</lastUpdated>
+    <snapshotVersions>
+      <snapshotVersion>
+        <extension>jar</extension>
+        <value>1.0.0-20260203.123107-1</value>
+        <updated>20260203123944</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>pom</extension>
+        <value>1.0.0-20260203.123107-1</value>
+        <updated>20260203123943</updated>
+      </snapshotVersion>
+    </snapshotVersions>
+  </versioning>
+</metadata>
+"""
+
+
+@pytest.mark.parametrize("patch_ansible_module", [None])
+def test_find_uri_for_snapshot_resolves_to_latest(mocker):
+    """When metadata has multiple snapshotVersion entries per extension,
+    the entry with the newest updated timestamp should be resolved."""
+    _getContent = mocker.patch(
+        "ansible_collections.community.general.plugins.modules.maven_artifact.MavenDownloader._getContent"
+    )
+    _getContent.return_value = snapshot_metadata_multiple_entries
+
+    artifact = maven_artifact.Artifact("com.example", "my-lib", "1.0.0-SNAPSHOT", None, "", "jar")
+    mvn_downloader = maven_artifact.MavenDownloader(basic.AnsibleModule, "https://repo.example.com")
+
+    uri = mvn_downloader.find_uri_for_artifact(artifact)
+    assert "1.0.0-20260210.152345-3.jar" in uri
+
+
+@pytest.mark.parametrize("patch_ansible_module", [None])
+def test_find_uri_for_snapshot_without_snapshot_block_uses_snapshot_versions(mocker):
+    """When metadata lacks a <snapshot> block, fall back to scanning
+    <snapshotVersions> entries."""
+    _getContent = mocker.patch(
+        "ansible_collections.community.general.plugins.modules.maven_artifact.MavenDownloader._getContent"
+    )
+    _getContent.return_value = snapshot_metadata_no_snapshot_block
+
+    artifact = maven_artifact.Artifact("com.example", "my-lib", "1.0.0-SNAPSHOT", None, "", "jar")
+    mvn_downloader = maven_artifact.MavenDownloader(basic.AnsibleModule, "https://repo.example.com")
+
+    uri = mvn_downloader.find_uri_for_artifact(artifact)
+    assert "1.0.0-20260203.123107-1.jar" in uri
+
+
+# Metadata with a <snapshot> block that has <timestamp> but no <buildNumber>.
+# This is schema-valid but non-standard (e.g. produced by non-Maven tools).
+# The module should fall back to <snapshotVersions> scanning.
+snapshot_metadata_incomplete_snapshot_block = b"""<?xml version="1.0" encoding="UTF-8"?>
+<metadata>
+  <groupId>com.example</groupId>
+  <artifactId>my-lib</artifactId>
+  <version>1.0.0-SNAPSHOT</version>
+  <versioning>
+    <snapshot>
+      <timestamp>20260210.152345</timestamp>
+    </snapshot>
+    <lastUpdated>20260210153158</lastUpdated>
+    <snapshotVersions>
+      <snapshotVersion>
+        <extension>jar</extension>
+        <value>1.0.0-20260210.152345-3</value>
+        <updated>20260210153154</updated>
+      </snapshotVersion>
+      <snapshotVersion>
+        <extension>pom</extension>
+        <value>1.0.0-20260210.152345-3</value>
+        <updated>20260210153153</updated>
+      </snapshotVersion>
+    </snapshotVersions>
+  </versioning>
+</metadata>
+"""
+
+
+@pytest.mark.parametrize("patch_ansible_module", [None])
+def test_find_uri_for_snapshot_incomplete_snapshot_block_uses_snapshot_versions(mocker):
+    """When the <snapshot> block is incomplete (e.g. missing <buildNumber>),
+    fall back to <snapshotVersions> instead of raising an error."""
+    _getContent = mocker.patch(
+        "ansible_collections.community.general.plugins.modules.maven_artifact.MavenDownloader._getContent"
+    )
+    _getContent.return_value = snapshot_metadata_incomplete_snapshot_block
+
+    artifact = maven_artifact.Artifact("com.example", "my-lib", "1.0.0-SNAPSHOT", None, "", "jar")
+    mvn_downloader = maven_artifact.MavenDownloader(basic.AnsibleModule, "https://repo.example.com")
+
+    uri = mvn_downloader.find_uri_for_artifact(artifact)
+    assert "1.0.0-20260210.152345-3.jar" in uri
+
+
+@pytest.mark.parametrize("patch_ansible_module", [None])
+def test_find_uri_for_release_version_unaffected(mocker):
+    """Non-SNAPSHOT versions must not be affected by snapshot resolution logic."""
+    artifact = maven_artifact.Artifact("com.example", "my-lib", "2.1.0", None, "", "jar")
+    mvn_downloader = maven_artifact.MavenDownloader(basic.AnsibleModule, "https://repo.example.com")
+
+    uri = mvn_downloader.find_uri_for_artifact(artifact)
+    assert uri == "https://repo.example.com/com/example/my-lib/2.1.0/my-lib-2.1.0.jar"