release: add archive installs and automate draft releases

.github/workflows/release.yml

@@ -111,11 +111,11 @@ jobs:
         shell: bash
         run: ./tools/tests/integration/run_mock_server_tests.sh
 
-      - name: Release checklist reminder
+      - name: Release validation completed
         shell: bash
         run: |
           echo "Release validation completed."
-          echo "Before publishing, follow CONTRIBUTING.md release runbook steps."
+          echo "Tag runs prepare a draft only after every release gate succeeds."
 
   release-hermetic:
     timeout-minutes: 45
@@ -355,3 +355,101 @@ jobs:
         if: runner.os == 'Windows'
         shell: pwsh
         run: ./tools/tests/integration/run_mock_server_tests.ps1
+
+  release-archive:
+    timeout-minutes: 45
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the release revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Test release packaging
+        run: python3 -m unittest tools.tests.python.test_release_tools
+
+      - name: Build the release archive and installation notes
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+          args=()
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            args+=(--tag "${GITHUB_REF#refs/tags/}")
+          fi
+          python3 tools/dev/check_module_versions.py
+          python3 tools/dev/check_release_archive_contents.py
+          python3 tools/dev/build_release.py --ref "$GITHUB_SHA" --output "$RUNNER_TEMP/release" "${args[@]}"
+          (cd "$RUNNER_TEMP/release" && sha256sum --check SHA256SUMS)
+
+      - name: Test the packaged Go consumer in Bzlmod and WORKSPACE
+        timeout-minutes: 35
+        shell: bash
+        run: |
+          set -euo pipefail
+          RTO_RELEASE_ARCHIVE="$RUNNER_TEMP/release/$(python3 -c 'import json, os; print(json.load(open(os.environ["RUNNER_TEMP"] + "/release/release.json"))["archive"])')"
+          RTO_RELEASE_PREFIX="$(python3 -c 'import json, os; print(json.load(open(os.environ["RUNNER_TEMP"] + "/release/release.json"))["strip_prefix"])')"
+          export RTO_RELEASE_ARCHIVE RTO_RELEASE_PREFIX
+          INTEGRATION_SCENARIO_MODE=release bash tools/tests/integration/run_bzlmod_go_integration.sh
+          INTEGRATION_SCENARIO_MODE=release bash tools/tests/integration/run_workspace_go_integration.sh
+
+      - name: Save the validated release bundle
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-bundle
+          path: ${{ runner.temp }}/release/
+          if-no-files-found: error
+          retention-days: 14
+
+  release-draft:
+    # A manual validation run never publishes, creates a tag, or edits a release.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && github.repository == 'DataDog/rules_test_optimization'
+    needs:
+      - release-validation
+      - release-hermetic
+      - release-shared-validation
+      - release-docs-links
+      - release-platform-smoke
+      - release-archive
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download the validated bundle from this run
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-bundle
+          path: release
+
+      - name: Create a draft with changelog, checksums, and install snippets
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          cd release
+          sha256sum --check SHA256SUMS
+          python3 - <<'PY'
+          import json, os
+          metadata = json.load(open("release.json"))
+          assert metadata["commit"] == os.environ["GITHUB_SHA"], "bundle revision differs from validated checkout"
+          assert "refs/tags/" + metadata["tag"] == os.environ["GITHUB_REF"], "bundle tag mismatch"
+          PY
+          test "$(gh api "repos/$GH_REPO/commits/${GITHUB_REF#refs/tags/}" --jq .sha)" = "$GITHUB_SHA"
+          # No --clobber or edit path: an existing release is left untouched.
+          gh release create "${GITHUB_REF#refs/tags/}" \
+            --draft --verify-tag --title "${GITHUB_REF#refs/tags/}" \
+            --notes-file RELEASE_NOTES.md \
+            ./*.tar.gz SHA256SUMS release.json INSTALL.md RELEASE_NOTES.md

BUILD.bazel

@@ -7,5 +7,6 @@
 # Root package exists to expose repository-level utility files to tests.
 exports_files([
     ".bazelversion",
+    ".github/workflows/release.yml",
     "bazelw",
 ])

CHANGELOG.md

@@ -15,6 +15,19 @@ versioning.
 
 ## [Unreleased]
 
+### Added
+
+- Release bundles with SHA256 checksums, archive-based installation snippets
+  for core/companions/Go forks, and notes generated from this changelog. Tag
+  workflows prepare a draft only after all release validations pass; manual
+  branch runs produce a downloadable preview without publishing.
+
+### Changed
+
+- Recommend release archives for installation. Go Bzlmod bootstrap now infers
+  and preserves checksum-pinned archive overrides and mirrors without requiring
+  a Git override for the Orchestrion-enabled fork.
+
 ## [1.3.0] - 2026-10-21
 
 ### Added

CONTRIBUTING.md

@@ -305,7 +305,34 @@ This product includes software developed at Datadog
 
 - CI release gate:
   - Trigger `.github/workflows/release.yml` via `workflow_dispatch` (or push a version tag) before publication.
-  - The workflow now always executes the full validation suite for release safety.
+  - Both paths execute the full validation suite and test the packaged archive
+    with real Go consumers in Bzlmod and WORKSPACE. A branch dispatch saves the
+    bundle as a workflow artifact but never creates a tag or release.
+  - A version-tag push prepares a **draft** GitHub release only after every
+    release job passes. It does not publish the draft or submit BCR changes.
+    Review the generated notes/assets, then publish explicitly.
+  - The draft contains `rules_test_optimization-X.Y.Z.tar.gz`, `SHA256SUMS`,
+    `release.json`, `INSTALL.md`, and `RELEASE_NOTES.md`. Notes come from the
+    matching `CHANGELOG.md` section. Installation blocks cover core, all six
+    companions, and every maintained Go fork, with one archive and checksum.
+  - The archive contains only the committed revision, including executable
+    modes. Packaging uses a fixed gzip header, so repeated builds of the same
+    revision with the same toolchain produce the same bytes. The workflow
+    verifies its checksums before attaching the exact validated bundle.
+  - An existing release is not edited or overwritten. If draft creation fails
+    partway through, inspect the existing draft and its assets before deciding
+    how to resume; rerunning must not replace published checksums.
+
+- Local bundle preview (Python 3.11+ and Git; no publication):
+
+  ```sh
+  python3 tools/dev/build_release.py --ref HEAD --tag vX.Y.Z --output /path/to/empty-directory
+  ```
+
+  The expected tag must match `MODULE.bazel` and have a nonempty changelog
+  section. Omit `--tag` for a branch validation preview. Uncommitted edits are
+  not included. Do not relabel an older release archive or regenerate a
+  published asset in place.
 
 - Version alignment:
   - Keep root `MODULE.bazel` and all companion `modules/*/MODULE.bazel` versions aligned.

README.md

@@ -10,7 +10,7 @@ This product includes software developed at Datadog
 
 This repository provides Bazel integrations that fetch Datadog Test Optimization metadata during module/repository resolution and materialize JSON files for use in your build. It also generates public filegroups so consumers can depend on stable labels instead of wiring files manually.
 
-> Release status: this branch prepares `1.3.0`; it is not published yet. Bazel Central Registry publication is also pending. Use `git_override` (Bzlmod) or commit-pinned `git_repository` / `http_archive` (WORKSPACE), with the same commit for core and companions. The historical `v1.2.0` pins below still refer to that release, not this candidate.
+> `v1.3.0` is published. For releases with an `INSTALL.md` asset, copy its checksum-pinned `archive_override` (Bzlmod) or `http_archive` (WORKSPACE) blocks. Keep core, companions, and the Go fork on the same archive. `v1.3.0` predates those assets; its commit-based installation remains supported. See [release installation](docs/Installation_Reference.md#option-a-install-from-a-release-archive-recommended).
 
 ## Onboarding paths
 
@@ -286,7 +286,7 @@ the default `dd-trace-go` version, and the default Orchestrion version.
 Published GitHub pins use `tar.gz`; other archive types must be mirrored and
 documented outside this helper.
 
-Historical `v1.2.0` GitHub pins (not the `1.3.0` candidate):
+Historical `v1.2.0` GitHub pins (not `v1.3.0`):
 
 ```bash
 RTO_COMMIT="69953536d4ef1252c8181c267d16c61263f0aa4c"
@@ -327,17 +327,24 @@ check as the dev helper.
 
 ## Quickstart by scenario
 
+Replace `<release-archive-url>`, `<release-archive-sha256>`, and
+`<archive-prefix>` with the values from the release's `INSTALL.md`. Match the
+Datadog `bazel_dep` versions to that release; the snippets below use `1.3.0`
+API examples. For `v1.3.0` or an unreleased commit without these assets, use
+the [Git alternative](docs/Installation_Reference.md#option-b-install-from-a-git-commit).
+
 ### Bzlmod + core only (any language)
 
 Use this when you do not need `dd_topt_go_test`:
 
 ```bzl
 # MODULE.bazel
 bazel_dep(name = "datadog-rules-test-optimization", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>",
 )
 
 test_optimization_sync = use_extension(
@@ -425,18 +432,19 @@ setup.
 
 ```bzl
 bazel_dep(name = "datadog-rules-test-optimization", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>",
 )
 
 bazel_dep(name = "datadog-rules-test-optimization-go", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-go",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/go",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/go",
 )
 bazel_dep(name = "rules_go", version = "0.60.0")
 ```
@@ -607,18 +615,19 @@ Orchestrion build flag.
 
 ```bzl
 bazel_dep(name = "datadog-rules-test-optimization", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>",
 )
 
 bazel_dep(name = "datadog-rules-test-optimization-python", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-python",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/python",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/python",
 )
 
 python_topt = use_extension(
@@ -756,11 +765,11 @@ absent.
 
 ```bzl
 bazel_dep(name = "datadog-rules-test-optimization-java", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-java",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/java",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/java",
 )
 ```
 
@@ -818,11 +827,11 @@ not include `srcs` by default and the extra files cost runfiles size.
 bazel_dep(name = "aspect_rules_js", version = "3.0.0-rc5")
 bazel_dep(name = "rules_nodejs", version = "6.7.3")
 bazel_dep(name = "datadog-rules-test-optimization-nodejs", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-nodejs",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/nodejs",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/nodejs",
 )
 
 node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")
@@ -851,11 +860,11 @@ dd_topt_nodejs_test(
 ```bzl
 bazel_dep(name = "rules_dotnet", version = "0.21.5")
 bazel_dep(name = "datadog-rules-test-optimization-dotnet", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-dotnet",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/dotnet",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/dotnet",
 )
 
 dotnet = use_extension("@rules_dotnet//dotnet:extensions.bzl", "dotnet")
@@ -906,11 +915,11 @@ def dotnet_csharp_test_adapter(name, data = None, env = None, **kwargs):
 ```bzl
 bazel_dep(name = "rules_ruby", version = "0.21.1")
 bazel_dep(name = "datadog-rules-test-optimization-ruby", version = "1.3.0")
-git_override(
+archive_override(
     module_name = "datadog-rules-test-optimization-ruby",
-    remote = "https://github.com/DataDog/rules_test_optimization.git",
-    commit = "<commit-sha>",
-    strip_prefix = "modules/ruby",
+    urls = ["<release-archive-url>"],
+    sha256 = "<release-archive-sha256>",
+    strip_prefix = "<archive-prefix>/modules/ruby",
 )
 
 ruby = use_extension("@rules_ruby//ruby:extensions.bzl", "ruby")
@@ -1360,7 +1369,7 @@ For a generic wrapper pattern, see [Other languages (without companion macro)](#
 | Bazel | `8.8.2` | Repository baseline (`.bazelversion`) and primary CI lanes |
 | rules_go (Go users) | `0.60.0` / `rules_go_upstream = "v0_60_0"` | README examples use the default support line; importpath inference requires `0.51.0+` |
 | Go toolchain (example) | `1.25.0` | Consumer repositories may use another supported version |
-| Module versions | `1.3.0` candidate | Not published yet; use commit pin/override install paths |
+| Module versions | `1.3.0` | Published; use release archives when available, or the Git alternative |
 
 - **Bazel 8.8.2 (repo baseline)** - Matches `.bazelversion` and primary CI lanes
 - **WORKSPACE compatibility lane** - CI intentionally validates `--noenable_bzlmod --enable_workspace` on Bazel `8.8.2` during migration away from WORKSPACE mode in Bazel 9+

docs/Configuration_Reference.md

@@ -41,12 +41,12 @@ local files and managed blocks; it never edits `WORKSPACE` itself:
 | `--plain-wrapper-name` | `dd_go_test` | Central local wrapper function name generated by the wrapper template |
 | `--optimized-wrapper-name` | `dd_topt_go_test` | Compatibility alias for the central wrapper; not a separate enablement path |
 | `--datadog-fetch` | `git` | Fetch mode for `datadog-rules-test-optimization-go`: `git` or `archive` |
-| `--rules-go-fetch` | `git` | Fetch mode for the Orchestrion-enabled `rules_go` fork: `git` or `archive` |
+| `--rules-go-fetch` | `git` | Fetch mode for the Orchestrion-enabled fork: `git` or `archive`. Bzlmod infers existing archive overrides unless an explicit Git/source flag is supplied. |
 | `--rules-go-upstream` | `default` | Datadog-managed upstream support line. Omit this to preserve the repository default; the current default resolves to `v0_60_0` |
 | `--rules-go-variant` | `base` | Published fork variant. Only `base` is supported. |
 | `--rules-go-repo-name` | `io_bazel_rules_go` | Bazel repository name that consumers use for `rules_go` |
 | `--rto-commit` | empty | Published rules_test_optimization commit used in generated WORKSPACE snippets. Required when either fetch mode is `git` |
-| `--rto-archive-url` | empty | Archive URL used when either fetch mode is `archive` |
+| `--rto-archive-url` | empty | Datadog source archive URL for WORKSPACE archive mode or explicit Bzlmod fork wiring |
 | `--rto-archive-sha256` | empty | Archive SHA256 used when either fetch mode is `archive` |
 | `--rto-archive-prefix` | empty | Archive root prefix used when either fetch mode is `archive` |
 | `--rto-archive-type` | `tar.gz` | Archive type passed to `http_archive` |