Configure shared and release S3 build cache namespaces

.gitlab-ci.yml

@@ -240,6 +240,16 @@ default:
   before_script:
     - source .gitlab/gitlab-utils.sh
     - *container_info
+    - |
+      if [ -z "${S3_BUILD_CACHE_PREFIX+x}" ]; then
+        s3_cache_arch=$(uname -m)
+        s3_cache_os=$(uname -s | tr '[:upper:]' '[:lower:]')
+        if [[ "${CI_COMMIT_TAG:-}" =~ [^[:space:]] ]]; then
+          export S3_BUILD_CACHE_PREFIX="v1/release/${CI_PIPELINE_ID:?}/$s3_cache_arch/$s3_cache_os/"
+        else
+          export S3_BUILD_CACHE_PREFIX="v1/$s3_cache_arch/$s3_cache_os/"
+        fi
+      fi
     # Akka token added to SSM from https://account.akka.io/token
     - export ORG_GRADLE_PROJECT_akkaRepositoryToken=$(aws ssm get-parameter --region us-east-1 --name ci.dd-trace-java.akka_repo_token --with-decryption --query "Parameter.Value" --out text)
     - export ORG_GRADLE_PROJECT_mavenRepositoryProxy=$MAVEN_REPOSITORY_PROXY
@@ -575,6 +585,8 @@ validate_build:
   variables:
     CACHE_TYPE: "lib"
   script:
+    # Rebuild independently of the cache used to produce the reference artifacts.
+    - export GRADLE_ARGS="$GRADLE_ARGS --no-build-cache --rerun-tasks"
     # Preserve the `build` job artifacts before Gradle rebuilds and overwrites them under
     # workspace/**/build/libs, so jardiff can compare the rebuilt jars against them.
     - mkdir -p reference-artifacts
@@ -586,7 +598,6 @@ validate_build:
     # Refresh them here as well so the candidate uses the same dependency resolution.
     - if [ $CI_PIPELINE_SOURCE == "schedule" ] ; then ./gradlew resolveAndLockAll --write-locks $GRADLE_ARGS; fi
     - ./gradlew --version
-    # This will run the shadowJar task and exercise the build cache, allowing to identify build-cache issues
     # Keep both JAR sets for direct inspection when the comparison fails.
     - |
       if ! ./gradlew compareToReferenceJar -PjardiffReferenceDir="$CI_PROJECT_DIR/reference-artifacts" -PskipTests $GRADLE_ARGS; then

dd-java-agent/build.gradle

@@ -309,6 +309,15 @@ def traceShadowJar = tasks.register('traceShadowJar', ShadowJar) {
 }
 includeShadowJar(traceShadowJar, 'trace', includedJarFileTree)
 
+[sharedShadowJar, traceShadowJar].each { shadowJarTask ->
+  shadowJarTask.configure {
+    // Track packaged bytes, including version files ignored by classpath normalization.
+    inputs.files(includedDependencies)
+      .withPropertyName('packagedDependencies')
+      .withPathSensitivity(PathSensitivity.NONE)
+  }
+}
+
 tasks.named("shadowJar", ShadowJar) {
   // Include AgentPreCheck compiled with Java 6.
   from sourceSets.main_java6.output

docs/how_to_work_with_gradle.md

@@ -1799,6 +1799,15 @@ When Gradle builds fail or behave unexpectedly, several tools and techniques can
 > [!TIP]
 > In general following the [Gradle best practices](https://docs.gradle.org/current/userguide/best_practices.html) is safe bet to avoid isses.
 
+### S3 Build Cache in GitLab CI
+
+`S3_BUILD_CACHE_PREFIX` overrides the full prefix; Gradle appends the task cache key.
+Defaults are `v1/<architecture>/<os>/` for non-tag builds (including master) and
+`v1/release/<CI_PIPELINE_ID>/<architecture>/<os>/` for tags. Include the pipeline ID
+in release overrides to preserve isolation.
+
+`validate_build` compares build artifacts against an uncached rebuild.
+
 ### Forcing Fresh CI Task Execution
 
 Set the GitLab CI variable `SKIP_BUILD_CACHE=true` when starting a pipeline.

settings.gradle.kts

@@ -40,8 +40,6 @@ plugins {
 
 val isCI = providers.environmentVariable("CI")
 val isGitLabCI = providers.environmentVariable("GITLAB_CI")
-val isGitLabTag = providers.environmentVariable("CI_COMMIT_TAG")
-val gitLabRefSlug = providers.environmentVariable("CI_COMMIT_REF_SLUG")
 val skipBuildscan = providers.environmentVariable("SKIP_BUILDSCAN").map { it.toBoolean() }.orElse(false)
 
 develocity {
@@ -58,12 +56,15 @@ if (isCI.isPresent) {
     local {
       directory = File(rootDir, "workspace/build-cache")
     }
-    if (isGitLabCI.isPresent && !isGitLabTag.isPresent) {
+    if (isGitLabCI.isPresent) {
+      val cachePrefix = providers.environmentVariable("S3_BUILD_CACHE_PREFIX").orNull?.trim()?.trim('/')
+      require(!cachePrefix.isNullOrBlank()) {
+        "S3_BUILD_CACHE_PREFIX must be set to a non-empty path in GitLab CI"
+      }
       remote<com.github.burrunan.s3cache.AwsS3BuildCache> {
         region = providers.environmentVariable("S3_BUILD_CACHE_REGION").get()
         bucket = providers.environmentVariable("S3_BUILD_CACHE_BUCKET").get()
-        prefix =
-          "trial/v1/${gitLabRefSlug.get()}/${System.getProperty("os.arch")}/"
+        prefix = "$cachePrefix/"
         isPush = true
         lookupDefaultAwsCredentials = true
         isReducedRedundancy = false