Skip to content

feat: pin and automate library defaults for v3 #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
juan-fernandez merged 8 commits into from
Jul 16, 2026
Merged

feat: pin and automate library defaults for v3 #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a534fe0
fix: pin default library versions
juan-fernandez Jul 15, 2026
a95ec10
chore: add local dependency release tooling
juan-fernandez Jul 15, 2026
1ac61b7
feat: prepare pinned defaults for v3
juan-fernandez Jul 15, 2026
3de9217
docs: clarify library bump workflows
juan-fernandez Jul 15, 2026
e3e6e0f
docs: add v3 migration guide
juan-fernandez Jul 15, 2026
bb4d7f6
docs: explain per-library version pins
juan-fernandez Jul 15, 2026
5b4d576
fix: prevent duplicate library bump PRs
juan-fernandez Jul 15, 2026
04225d8
fix: verify release commits with GitHub
juan-fernandez Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/release.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,7 @@ jobs:
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
- name: Release
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
with:
generate_release_notes: true
env:
GITHUB_TOKEN: ${{ secrets.RELEASE_ACCESS_TOKEN }}
84 changes: 74 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ It can help you investigate and mitigate performance problems and test failures
```yaml
steps:
- name: Configure Datadog Test Optimization
uses: datadog/test-visibility-github-action@v2
uses: datadog/test-visibility-github-action@v3
with:
languages: java
api_key: ${{ secrets.DD_API_KEY }}
Expand All @@ -31,6 +31,53 @@ It can help you investigate and mitigate performance problems and test failures
> Otherwise, installed tracing libraries might be removed by the steps that precede tests execution
> (for example, `actions/checkout` will wipe out whatever was installed in the action workspace).

### Choose an action version

Starting with v3, each action release pins its default library versions instead of resolving `latest` at runtime. The action reference after `@` determines whether your workflow receives newer action releases and their pinned library versions:

| Reference | Example | Advantages | Disadvantages |
| --------- | ------- | ---------- | ------------- |
| Moving major | `datadog/test-visibility-github-action@v3` | Automatically receives reviewed bug fixes and library bumps released within v3. It will not move to v4. | The action code and default library versions can change between workflow runs. |
| Exact release tag | `datadog/test-visibility-github-action@v3.0.0` | Uses a readable, known action release and its pinned library versions. Release notes make changes easy to review before upgrading. | Does not receive bug fixes or library bumps automatically. Tags can technically be moved, so this is not as strong an immutability guarantee as a full commit SHA. |
| Full commit SHA | `datadog/test-visibility-github-action@<full-commit-sha> # v3.0.0` | Strongest reproducibility and supply-chain protection: every run uses the exact same action code and pinned library versions. | Does not receive fixes or new releases automatically. Replace the placeholder with the full SHA for the release you reviewed and use an update mechanism such as Dependabot. |

These references select the action code and its default library snapshot. To keep an individual library on a specific version independently of the action reference, [set its version input explicitly](#pin-an-individual-library-version).

For most workflows, `@v3` provides the simplest way to receive compatible updates. For workflows that require an immutable action, use the full commit SHA associated with a v3 release. Keeping the release tag as an inline comment lets readers identify the version and allows Dependabot to update the comment with the SHA.

To have Dependabot propose updates for an action pinned to a SHA, add the following to `.github/dependabot.yml` in the repository that uses the action:

```yaml
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
```

Dependabot then opens pull requests when newer action releases are available, so the new SHA and any changes to the pinned library versions can be reviewed before merging. See GitHub's guidance on [keeping actions up to date with Dependabot](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/auto-update-actions) and [pinning actions securely](https://docs.github.com/en/actions/reference/security/secure-use#using-third-party-actions).

### Migrate from v2 to v3

The `v2` reference does not move to v3 automatically. Update the action reference in each workflow you want to migrate:

```diff
- uses: datadog/test-visibility-github-action@v2
+ uses: datadog/test-visibility-github-action@v3
```

No input names or required configuration change. The migration only changes how omitted library-version inputs are resolved:

| Your workflow | Experience after migrating |
| ------------- | -------------------------- |
| No library-version inputs | The first v3 run uses the versions listed in the [configuration table](#configuration), which may differ from the versions resolved by the last v2 run. Defaults no longer change independently on every run. |
| Explicit library-version inputs | Your selected versions continue to override the action defaults, so the installed library versions do not change as part of the migration. |

With `@v3`, pinned defaults change only when a reviewed v3 release moves the major reference. Use an exact release tag or full commit SHA instead if the action and its defaults must remain unchanged until you explicitly update the reference.

Before migrating, review the v3 defaults and run a representative test workflow. If you need to preserve a specific library version, set its version input explicitly.

## Configuration

The action has the following parameters:
Expand All @@ -41,13 +88,13 @@ The action has the following parameters:
| api_key | Datadog API key. Can be found at <https://app.datadoghq.com/organization-settings/api-keys> | true | |
| site | Datadog site. See <https://docs.datadoghq.com/getting_started/site> for more information about sites. | false | datadoghq.com |
| service | The name of the service or library being tested. | false | |
| dotnet-tracer-version | The version of Datadog .NET tracer to use. Defaults to the latest release. | false | |
| java-tracer-version | The version of Datadog Java tracer to use. Defaults to the latest release. | false | |
| js-tracer-version | The version of Datadog JS tracer to use. Defaults to the latest release. | false | |
| python-tracer-version | The version of Datadog Python tracer to use. Defaults to the latest release. | false | |
| python-coverage-version | The version of the Python `coverage` package to use. Defaults to `7.13.5`. | false | |
| ruby-tracer-version | The version of datadog-ci Ruby gem to use. Defaults to the latest release. | false | |
| go-tracer-version | The version of Orchestrion to use. Defaults to the latest release. | false | |
| dotnet-tracer-version | The version of Datadog .NET tracer to use. | false | 3.49.0 |
| java-tracer-version | The version of Datadog Java tracer to use. | false | 1.64.0 |
| js-tracer-version | The version of Datadog JS tracer to use. | false | 6.3.0 |
| python-tracer-version | The version of Datadog Python tracer to use. | false | 4.11.0 |
| python-coverage-version | The version of the Python `coverage` package to use. | false | 7.15.1 |
| ruby-tracer-version | The version of datadog-ci Ruby gem to use. | false | 1.34.0 |
| go-tracer-version | The version of Orchestrion to use. | false | v1.11.0 |
| go-module-dir | Path to the Go module root directory to instrument. Use this when the repository contains multiple Go modules or the Go module is not in the workspace root. | false | |
| java-instrumented-build-system | If provided, only the specified build systems will be instrumented (allowed values are `gradle`,`maven`,`sbt`,`ant`,`all`). `all` is a special value that instruments every Java process. If this property is not provided, all known build systems will be instrumented (Gradle, Maven, SBT, Ant). | false | |
| java-tracer-repository-url | Base URL of a Maven repository (or proxy/mirror) used to download the Java tracer JAR and its sha256. The path under the base must follow the standard Maven layout for `com.datadoghq:dd-java-agent`. Defaults to Maven Central. | false | |
Expand All @@ -56,6 +103,23 @@ The action has the following parameters:
| cache | Enable caching of downloaded tracers. | false | true |
| print-github-step-summary | Print a summary of the installed tracers to the GitHub step summary. If set to false, the summary is printed to console instead. | false | true |

### Pin an individual library version

Set a library's version input to override the default selected by the action release. The explicit version remains in effect when the action reference moves or is updated:

```yaml
- name: Configure Datadog Test Optimization
uses: datadog/test-visibility-github-action@v3
with:
languages: java
api_key: ${{ secrets.DD_API_KEY }}
java-tracer-version: 1.64.0
```

This lets you receive action updates while holding a particular library at a version you have validated. That library will not receive automatic bumps, so update the input explicitly when you want a newer version. The same behavior applies to every library-version input in the table above.

Maintainers can use the local scripts described in [RELEASE.md](RELEASE.md) to create a batched library bump PR and publish the resulting action release.

### Additional configuration

Any [additional configuration values](https://docs.datadoghq.com/tracing/trace_collection/library_config/) can be added directly to the step that runs your tests:
Expand All @@ -75,7 +139,7 @@ By default the Java tracer JAR is fetched from Maven Central (`https://repo1.mav

```yaml
- name: Configure Datadog Test Optimization
uses: datadog/test-visibility-github-action@v2
uses: datadog/test-visibility-github-action@v3
with:
languages: java
api_key: ${{ secrets.DD_API_KEY }}
Expand All @@ -91,7 +155,7 @@ If your repository contains multiple Go modules, or the Go module you want to in

```yaml
- name: Configure Datadog Test Optimization
uses: datadog/test-visibility-github-action@v2
uses: datadog/test-visibility-github-action@v3
with:
languages: go
api_key: ${{ secrets.DD_API_KEY }}
Expand Down
93 changes: 93 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Release Process

This repository ships a composite GitHub Action. Releases use immutable semantic-version tags such as `v3.0.0` and a moving major branch such as `v3`.

## Requirements

The local release scripts require `curl`, `git`, `gh`, and Ruby. Authenticate the GitHub CLI before using them:

```bash
gh auth login
gh auth status
```

The scripts that create commits use signed commits and verify the signature before pushing. Run the bump and release helpers from a clean working tree.

## Release labels

Every PR intended for a release must have one of these labels:

- `semver-patch`: requests the next patch release
- `semver-minor`: requests the next minor release
- `semver-major`: requests the next major release

If a release includes multiple merged PRs, the highest requested version change wins. A major release can also be selected explicitly by passing `--tag vX.0.0` to the release script.

## Bump pinned library versions

Use `scripts/create-library-version-bump-pr.sh` for the normal maintainer workflow. It discovers available updates and handles the complete branch, signed commit, push, and PR flow.

Preview all currently available library updates:

```bash
scripts/create-library-version-bump-pr.sh --dry-run
```

Create a single PR containing every available update:

```bash
scripts/create-library-version-bump-pr.sh
```

The script reads the official package sources for .NET, Java, JavaScript, Python, Python coverage, Ruby, and Go/Orchestrion. If at least one pinned default is outdated, it creates a branch, updates `action.yml` and `README.md`, creates and verifies a signed commit, pushes the branch, and opens a PR.

The PR receives:

- `library-version-bump`
- `semver-patch` when every update is a patch
- `semver-minor` when at least one library changes its major or minor version

Use `scripts/bump-library-versions.sh` only as a lower-level manual tool when you already know the exact versions to apply, such as for a targeted update or when testing the file changes. It only updates `action.yml` and `README.md`; it does not query package sources, create a branch or commit, push, or open a PR.

```bash
scripts/bump-library-versions.sh --java 1.65.0 --js 6.3.1
scripts/bump-library-versions.sh --go v1.12.0
```

Review and merge the resulting changes normally.

## Release the action

Preview the next release first:

```bash
scripts/release-action.sh --dry-run
```

The script fetches `main` and tags, finds merged PRs since the latest immutable action tag, reads their `semver-patch`, `semver-minor`, and `semver-major` labels, and chooses the next action tag. It requires GitHub to report the release commit's signature as verified, then atomically pushes the immutable tag and moving major branch. The existing release workflow creates the GitHub Release with generated notes.

Publish the inferred release:

```bash
scripts/release-action.sh
```

Release a specific commit on `main`:

```bash
scripts/release-action.sh --sha abc1234 --dry-run
scripts/release-action.sh --sha abc1234
```

Choose the tag manually:

```bash
scripts/release-action.sh --tag v3.0.0 --dry-run
scripts/release-action.sh --tag v3.0.0
```

If the requested tag is lower than the merged PR labels imply, the script fails. To publish that tag intentionally:

```bash
scripts/release-action.sh --tag v3.0.1 --allow-version-mismatch
```
Loading
Loading