Tested dependency upgrade PRs

Use aegis upgrade-pr in a clean local checkout or disposable runner. Select and review an exact published target version for your release line, then supply your project's test commands.

On a scan result, Create dependency upgrade PR fills that command from the finding. The package is the affected coordinate. When the finding lists published fixed versions, the version is the lowest stable release newer than the scanned version. Maven and Gradle keep the published form, including two and four numeric parts and a qualifier such as -jre. Other ecosystems use a stable three-part release. When the finding says a direct dependency installs the advisory, the command upgrades that dependency. The version is the release that pulls in a fix when the scan computed one; otherwise replace it with a newer exact release. Review the version before you run it.

Every ecosystem below runs end to end against its real package manager in .github/workflows/upgrade-adapters.yml (see Testing against the real tools). An adapter added later is marked experimental until it does: the command says so on stderr and adds "experimental": true to its result.

npm, for a direct dependency in package.json / package-lock.json or npm-shrinkwrap.json v2 or v3:

aegis upgrade-pr --package lodash --version 4.17.21 --test "npm test" --output upgrade.json

Python, for one direct dependency in a single-project pyproject.toml with uv.lock:

aegis upgrade-pr --ecosystem python --package requests --version 2.32.3 --test "pytest" --output upgrade.json

Poetry 2, for one direct dependency in pyproject.toml / poetry.lock:

aegis upgrade-pr --ecosystem poetry --package requests --version 2.32.3 --test "pytest" --output upgrade.json

Pipenv, for one direct dependency in Pipfile / Pipfile.lock:

aegis upgrade-pr --ecosystem pipenv --package requests --version 2.32.3 --test "pytest" --output upgrade.json

Yarn Classic, for one direct dependency in package.json / yarn.lock v1:

aegis upgrade-pr --ecosystem yarn --package lodash --version 4.17.21 --test "yarn test" --output upgrade.json

Yarn Berry, for one direct dependency in package.json / yarn.lock with __metadata versions 4–8:

aegis upgrade-pr --ecosystem yarn-berry --package lodash --version 4.17.21 --test "yarn test" --output upgrade.json

Gradle, for one direct dependency in build.gradle / gradle.lockfile:

aegis upgrade-pr --ecosystem gradle --package junit:junit --version 4.13.2 --test "gradle test" --output upgrade.json

Maven, for one direct dependency in pom.xml:

aegis upgrade-pr --ecosystem maven --package junit:junit --version 4.13.2 --test "mvn -B test" --output upgrade.json

requirements.txt, for one exact PyPI pin:

aegis upgrade-pr --ecosystem requirements --package requests --version 2.32.3 --test "python -m pytest" --output upgrade.json

Bundler, for one direct gem in Gemfile / Gemfile.lock:

aegis upgrade-pr --ecosystem bundler --package rack --version 2.2.9 --test "bundle exec rake" --output upgrade.json

NuGet, for one direct PackageReference in a project file / packages.lock.json:

aegis upgrade-pr --ecosystem nuget --package Newtonsoft.Json --version 13.0.3 --test "dotnet test" --output upgrade.json

Composer, for one direct dependency in composer.json / composer.lock:

aegis upgrade-pr --ecosystem composer --package psr/log --version 3.0.2 --test "composer test" --output upgrade.json

Cargo, for one direct dependency in Cargo.toml / Cargo.lock:

aegis upgrade-pr --ecosystem cargo --package libc --version 0.2.158 --test "cargo test --locked" --output upgrade.json

Go, for one direct requirement in go.mod / go.sum:

aegis upgrade-pr --ecosystem go --package golang.org/x/text --version v0.21.0 --test "go test ." --output upgrade.json

pnpm, for one direct dependency in package.json / pnpm-lock.yaml:

aegis upgrade-pr --ecosystem pnpm --package lodash --version 4.17.21 --test "pnpm test" --output upgrade.json

Give each test command with --test, and repeat it for more commands. AEGIS splits the text into arguments the way a shell would, but no shell runs it, so pipes, && and redirects are not available. --tests takes the commands as a JSON array of argument arrays instead, for example --tests '[["npm","test"]]'. Without --ecosystem, AEGIS picks the ecosystem from the lockfile in the project directory (a yarn.lock with a __metadata entry is Yarn Berry) and says which on stderr. With no lockfile, or lockfiles of two ecosystems, it asks for --ecosystem.

Use --project web when the project is in a repository-relative subdirectory. Tests run in that project directory. Git, registry access and OSV access are required. npm also requires Node.js and npm. --ecosystem python requires uv. --ecosystem poetry requires Poetry 2. --ecosystem pipenv requires a pipenv with the upgrade command. --ecosystem yarn requires Yarn Classic 1.x. --ecosystem yarn-berry requires Corepack and a packageManager of Yarn 2, 3, or 4. --ecosystem pnpm requires pnpm. --ecosystem go requires Go 1.x. --ecosystem cargo requires cargo. --ecosystem composer requires Composer 2. --ecosystem nuget requires the .NET SDK. --ecosystem maven requires Maven. --ecosystem gradle requires Gradle 8. --ecosystem bundler requires Bundler. --ecosystem requirements requires uv. This command explicitly queries OSV with public package names and resolved versions, independently of the normal scanner's opt-in setting. It does not send source code or use a model.

AEGIS prepares the change in a separate temporary Git clone. It pins the selected direct dependency to the exact version, regenerates the lockfile with that ecosystem's package manager, and installs it. npm regeneration and npm ci disable lifecycle scripts. yarn install for Yarn Classic and pnpm install do the same with --ignore-scripts. uv lock and uv sync --frozen, and Poetry lock and poetry sync --no-root, install into a disposable environment in the clone; uv build hooks, Poetry install, pipenv install, and your supplied tests can execute code. Yarn Classic and pnpm disable install lifecycle scripts; the supplied tests can still execute code. Use a disposable runner for untrusted projects. Installation downloads public packages. GitHub CLI authentication is additionally required for publication.

Several of these tools also read configuration from every folder above the project, up to the filesystem root, so a file at the repository root (or above the temporary clone) would apply to a project in a subfolder. AEGIS refuses to run when one exists: Maven's .mvn, Cargo's .cargo/config.toml and a Rust toolchain file that names a path, Go's go.work, Yarn Berry's .yarnrc.yml, Gradle's settings.gradle, and NuGet's NuGet.Config, Directory.Build.props, .targets, .rsp, Directory.Packages.props and global.json. The error names the file.

Package managers and your tests run without your credentials in their environment. AEGIS removes variables named like a token, secret, password, key or webhook (GH_TOKEN, GITHUB_TOKEN, NPM_TOKEN, AWS_SECRET_ACCESS_KEY, TWINE_PASSWORD and so on), DATABASE_URL and REDIS_URL, SSH agent and askpass settings, GIT_CONFIG_* overrides, and any URL with a password in it. Proxy settings are kept so registries stay reachable. Only git and gh, which push the branch and open the draft, see your full environment. If a test needs one of the removed variables, put it in that test command on purpose, for example ["env", "DATABASE_URL=postgresql://localhost/app_test", "pytest"].

That stops repository code reading credentials from its environment. It is not isolation. The code still runs as you, so it can read anything you can read, including credential files such as ~/.config/gh/hosts.yml, ~/.npmrc and ~/.netrc, and it can change files that later git and gh commands use. For a repository you do not trust, run the command on a disposable runner or account whose only credential is a token limited to that repository. For npm, the dashboard's isolated runner runs the tests in a container with no credentials and no network.

Python resolution follows the lockfile's requires-python range and dependency markers across CPython 3.8–3.14 on Linux, macOS and Windows. Transitive packages that can actually be installed in that range are part of the advisory inventory. Packages whose markers never match are not treated as installed.

Verification requires complete supported inventory and live OSV answers before and after the change. The selected package must have an advisory before the upgrade and none afterward, including other installed copies of that package. Additional advisory identifiers for other packages cause rejection. Existing unrelated advisories remain visible in the result. An outage, pagination, malformed response, stale base, failed tests, an incompatible resolution, changed tracked files or unexpected lockfile resolution prevents a verified result.

Review upgrade.json and its diff. Repeat with --publish to push the verified manifest and lockfile and create a draft GitHub PR. --base BRANCH selects another base. The local base must match GitHub before and after verification. No existing branch is overwritten and nothing is automatically merged. A passing OSV check is time-bound evidence, not proof of security or application compatibility.

npm supports one direct dependencies, devDependencies, or optionalDependencies entry in a package-lock.json or npm-shrinkwrap.json v2/v3 project with up to 500 integrity-pinned public registry packages. The project has one of those lockfiles, not both. Targets must be newer stable three-part versions. A direct dependency with no advisory of its own can be bumped when every advisory on a package it installs disappears, no new advisory appears, and advisories outside that set stay unchanged. Selecting the transitive package itself is still rejected. npm workspaces, overrides, aliases, custom .npmrc files, private registries, git/local/bundled packages, a parent shrinkwrap require separate workflows. One peerDependency can be pinned when it is not also a dependency, devDependency, or optionalDependency. A literal workspace member path, with the lockfile at the repository root, can be selected with --project. AEGIS_UPGRADE_NPM_REGISTRY can name one https registry with no credentials; otherwise the public npm registry is used.

Python supports one direct [project].dependencies, [dependency-groups], or [project.optional-dependencies] entry in a single-project pyproject.toml plus uv.lock version 1, with up to 500 resolved public PyPI packages. Targets must be newer canonical stable versions. One [dependency-groups] entry is included: the dev group is installed by uv sync, and any other group is passed with --group. One optional extra is installed with uv sync --extra. A package listed in more than one of those tables is rejected. A direct dependency with no advisory of its own can be bumped when every advisory on a package it installs disappears, no new advisory appears, and advisories outside that set stay unchanged. AEGIS_UPGRADE_PYPI_INDEX can name one https index with no credentials. uv workspaces, uv.toml, private indexes, and git/path/URL dependencies require separate workflows.

Poetry supports the same direct-dependency rule for a Poetry 2 project with poetry.lock lock-version 2, including one [dependency-groups] entry. The dev group is installed by poetry sync --no-root; any other group is passed with --with. One [project.optional-dependencies] extra is installed with --extras. aegis upgrade-pr --ecosystem poetry regenerates the lock with Poetry and installs it with that sync. Private indexes, poetry.toml, git/path dependencies and workspaces are rejected. Poetry install and the supplied tests can execute code.

Pipenv supports one direct [packages] or [dev-packages] entry in a Pipfile plus Pipfile.lock (pipfile-spec 6). aegis upgrade-pr --ecosystem pipenv updates the lock with pipenv upgrade for that package only (pipenv lock would move every unpinned package too), puts back the Pipfile line exactly as AEGIS pinned it (pipenv reorders the file), checks the lock with pipenv verify, and installs it with pipenv sync into an in-project environment. pipenv does not load the project's .env. A dev package is installed with pipenv sync --dev. The Pipfile python_version selects which markers count. A package listed in both tables is rejected. Private indexes and git/path dependencies are rejected. AEGIS_UPGRADE_PYPI_INDEX selects the index. When the selected package has no advisory of its own, pipenv installs the current lock and reads wheel metadata so every advisory in a package it installs must disappear. pipenv install and the supplied tests can execute code.

Yarn Classic supports one direct dependencies, devDependencies, or optionalDependencies entry in package.json plus a v1 yarn.lock, with up to 500 integrity-pinned packages resolved from registry.yarnpkg.com or registry.npmjs.org. aegis upgrade-pr --ecosystem yarn regenerates the lock with yarn install and installs it again with --frozen-lockfile. Both commands pass --ignore-scripts. Targets must be newer stable three-part versions. A direct dependency with no advisory of its own can be bumped when every advisory on a package it installs disappears. One literal workspace member, with yarn.lock at the repository root, can be selected with --project. AEGIS_UPGRADE_YARN_REGISTRY can name one https registry with no credentials. Globs, nested workspaces, Yarn Berry, resolutions, .yarnrc, git/path dependencies and alias declarations are rejected. Supplied tests can execute code.

Yarn Berry supports one direct dependencies, devDependencies, or optionalDependencies entry in a project whose packageManager is yarn@2, yarn@3, or yarn@4, plus a yarn.lock whose __metadata version is 4–8, with one workspace root and up to 500 checksum-pinned npm: packages. aegis upgrade-pr --ecosystem yarn-berry regenerates the lock with Corepack's yarn install and installs it again with --immutable. YARN_ENABLE_SCRIPTS=0 and YARN_NPM_REGISTRY_SERVER point at the public Yarn registry, or at AEGIS_UPGRADE_YARN_REGISTRY when that https URL is set. .yarnrc.yml may only set nodeLinker: node-modules, enableScripts: false, and that public registry. Workspaces, plugins, patches, vendored Yarn releases, private registries, and git/path dependencies are rejected. enableScripts covers dependencies only, so a project with its own preinstall, install or postinstall script is rejected too. Supplied tests can execute code.

pnpm supports one direct dependencies, devDependencies, or optionalDependencies entry in package.json plus pnpm-lock.yaml version 5, 6, or 9, with up to 500 integrity-pinned packages. aegis upgrade-pr --ecosystem pnpm regenerates the lock with pnpm install --lockfile-only and installs it with --frozen-lockfile. Both commands pass --ignore-scripts and use https://registry.npmjs.org/. Lockfile version 9 omits the tarball URL when pnpm used that default registry; a non-default registry tarball or registry field is rejected unless AEGIS_UPGRADE_PNPM_REGISTRY names that https registry. Targets must be newer stable three-part versions. A direct dependency with no advisory of its own can be bumped when every advisory on a package it installs disappears. One literal member listed in the repository-root pnpm-workspace.yaml can be selected with --project; globs are still rejected. .npmrc, overrides, patches, and git/path dependencies are rejected. Supplied tests can execute code.

Go supports one direct require in go.mod plus go.sum, with up to 500 modules. aegis upgrade-pr --ecosystem go runs go get [email protected], go mod tidy, and go mod download with GOPROXY=https://proxy.golang.org (AEGIS_UPGRADE_GOPROXY can name another https proxy), GOSUMDB=sum.golang.org, and GOTOOLCHAIN=local. A direct module with no advisory of its own can be bumped when every advisory on a module it installs disappears. Targets must be newer stable vMAJOR.MINOR.PATCH versions. GOWORK=off is set. replace and exclude directives, a go.work here or in any parent folder, and a vendor directory are rejected. Tidy reads module source. Supplied tests can execute code.

Cargo supports one direct dependencies, dev-dependencies, or build-dependencies entry in Cargo.toml plus Cargo.lock version 3 or 4, with up to 500 checksum-pinned crates.io packages. { version = "...", optional = true } is included when that crate is already in the lock. One target-specific dependency in a cfg expression or target triple is accepted when that crate is already locked. aegis upgrade-pr --ecosystem cargo pins the requirement to an exact version, runs cargo update -p CRATE --precise VERSION, and fetches with cargo fetch --locked. The crates.io protocol is sparse and CARGO_HOME is temporary. Git, path, private registries, workspaces, and patch/replace are rejected, as are Cargo configuration in a parent folder and a rust-toolchain file there that names a toolchain path: rustup would run that folder's cargo. A channel such as 1.80 is fine. cargo fetch does not compile. Supplied tests can execute code, including build scripts.

Composer supports one direct require or require-dev entry in composer.json plus composer.lock, with up to 500 packages whose dist zip is on Packagist or GitHub. aegis upgrade-pr --ecosystem composer pins that requirement and runs composer update --with-dependencies and composer install, both with plugins and scripts disabled. Private repositories, path packages, and git dists are rejected, as are config settings that move Composer's folders (vendor-dir, bin-dir and the cache and data folders), because Composer writes there even with plugins off, and settings that weaken TLS (secure-http, disable-tls, cafile, capath). Supplied tests can execute code.

NuGet supports one direct PackageReference in a single project file plus packages.lock.json version 1 or 2, with one target framework and up to 500 content-hashed packages. aegis upgrade-pr --ecosystem nuget sets that reference to an exact version and runs dotnet restore twice, the second time with --locked-mode, using only https://api.nuget.org/v3/index.json. dotnet restore evaluates the project file, so only SDK-style projects on a Microsoft.NET.Sdk SDK are accepted. Imports, targets, tasks and restore feed settings in the project, NuGet and MSBuild files in it or any parent folder, private feeds, central package management, and project references are rejected. The .NET SDK is not installed where these checks were written, so this adapter has not run against a real dotnet restore. Supplied tests can execute code.

Maven supports one direct compile, runtime, or test dependency in a single pom.xml, including one marked <optional>true</optional>, with groupId, artifactId, then a literal version, and up to 500 resolved artifacts. aegis upgrade-pr --ecosystem maven sets that version and runs mvn dependency:list before and after, using Maven Central, or AEGIS_UPGRADE_MAVEN_REPO when that https repository is set. When the selected coordinate has no advisory of its own, dependency:tree must show a package it installs whose advisories all disappear. A test-scoped dependency is resolved on the test classpath; compile and runtime dependencies, optional or not, stay on the runtime classpath. Provided scope stays rejected. Versions take the shapes Maven Central uses: one to four numbers and an optional qualifier (20231013, 2.7, 2.13.4.2, 32.1.3-jre, 4.1.100.Final). Snapshots, milestones, release candidates and previews are refused, and so is 2.7 → 2.7.0, which Maven ranks as the same version. A parent with a literal group, artifact and version and no relativePath is allowed. Modules, BOMs, repositories, wrappers, build extensions (the <build><extensions> list and plugins with <extensions>true</extensions>), and a .mvn folder here or in any parent folder are rejected. Supplied tests can execute code.

Gradle supports one direct dependency in build.gradle with the built-in java or java-library plugin, dependency locking for every configuration, and gradle.lockfile, with up to 500 coordinates. aegis upgrade-pr --ecosystem gradle sets that coordinate and runs gradle dependencies --write-locks --update-locks. Resolution is forced to Maven Central, or to AEGIS_UPGRADE_MAVEN_REPO. When the selected coordinate has no advisory of its own, the runtime classpath tree must show a package it installs whose advisories all disappear. Gradle unlocks only the selected coordinate, but moves other locked modules the new version needs (upgrading netty-handler moves the rest of Netty with it), so review the whole lockfile diff; an advisory new anywhere in it fails the check. Any dependency Gradle cannot resolve stops the upgrade, and the error names it and the reason. The report alone would print FAILED, exit successfully and keep that configuration's old lock entries. Versions follow the Maven rules above, except that Gradle ranks 2.7.0 above 2.7. Wrappers, settings files (here or in any parent folder, where Gradle would run them), buildSrc, and other plugins are rejected. Gradle evaluates the build script, which can execute code. Supplied tests can execute code.

Bundler supports one direct gem that declares a version in a Gemfile whose only source is https://rubygems.org, plus Gemfile.lock, with up to 500 gems. aegis upgrade-pr --ecosystem bundler pins that gem and runs bundle lock --update then bundle install with the lock frozen. Bundler evaluates the Gemfile as Ruby, and the install can build native extensions, so both can execute code. Project .bundle config is ignored and rejected if present. Git, path, and private gem sources are rejected. Tests run with Bundler pointed at the verified install, so run them through bundle exec. Supplied tests can execute code.

requirements.txt supports 1–500 exact name==version pins and no other requirement syntax. aegis upgrade-pr --ecosystem requirements changes one pin and installs the file twice with uv pip install --only-binary :all: from https://pypi.org/simple (AEGIS_UPGRADE_PYPI_INDEX can name another https index), into a disposable environment. When the selected pin has no advisory of its own, installed wheel metadata must show a dependency whose advisories all disappear. Includes, hashes, URLs, markers, requirements.in, and another Python lockfile in the same directory are rejected. Tests run with that environment first on PATH, so list your test runner in requirements.txt and call it through Python: --test "python -m pytest". A bare pytest from elsewhere on your PATH would test your system packages instead. Supplied tests can execute code.

Testing against the real tools

The adapters' parsers were first written against hand-made sample files, and the real tools wrote things they refused: Yarn 3's bare ranges, Maven's module suffixes, two-part and four-part Maven versions, Guava's 9999.0-empty-to-avoid-conflict-with-guava, Bundler 4's version line. The regular test suite fakes every package manager, so it could not notice. Two checks now use the real tools:

TestUpgradeAdaptersOnRealToolOutput runs the parsers over them. Its README names the tool, version and command for each file.

manager and upgrades one dependency through the adapter, end to end. Only the OSV lookup is a stand-in. It runs with AEGIS_REAL_TOOLS=1 and skips a tool that is not installed:

``sh AEGIS_REAL_TOOLS=1 python -m pytest tests/test_clients_and_migrations.py -k RealTools -rs ``

.github/workflows/upgrade-adapters.yml runs it with every tool installed, when an adapter, a lockfile reader or a fixture changes, every week, and on demand.