Codependence checks and updates dependency versions using one-to-many project policies with support for Node, Python, Go, Rust, Docker, GitHub Actions, and Helm.
This means you control how you update and why you update. Versus other tools, Codependence caters to a project's context vs a dependency's context.
Main use case
Pin what matters and update the rest
Suppose a project must stay on React ^19.0.0, but its other dependencies should keep moving. Add that policy to .codependencerc:
The policy runs the same thing everywhere!—Locally in scripts or in CI; it's the same and you own it.
See more recipes below!
Install
Runtime support
Codependence officially supports Node.js 24 and newer.
Node.js 20 and 22 are best-effort compatible: the CLI may work there, and CI runs
non-blocking smoke checks, but failures below Node.js 24 do not block releases.
via npm in the project
npm install codependence
For direct CLI use:
npm install --global codependence
or via brew
brew install yowainwright/tap/codependence
It is a top priority to make this official to brew as quickly as possible for your security benefit!
Prompts you to seemlessly setup dependency policy and enforcement.
Creates or updates the configuration.
[!NOTE]
Use init config [directory] for configuration only and init actions to generate GitHub Actions workflows.
For a JavaScript project, you can use a codependence dependency policy object in package.json.
For larger or mixed-language projects, you can create Codependence config files for your project's dependency needs:
{+ "codependence": "./.codependencerc"}
The config path is relative to manifest files, e.g. package.json.
Each entry in config represents one manifest and requires path and manager; name is optional.
[!NOTE]
Editors can use the published configuration schema for validation and completion.
Seemless Maintenance
Once you're dependency policy is as you desire, all that's left is maintenance. AKA
npm run update
That's it but readme below for how you can be more nuanced about maintenance below!
CLI
Codependence, although it can be used with Node.js, or only ci, is a CLI-first policy tool.
The direct commands below assume the global npm or Homebrew install shown above.
Run codependence --help for every option.
Init
Codependence consists of just 1 commands, init.
Usage: codependence [command] [options]Commands: init [directory] Run guided project setup init config [directory] Create or update configuration only init actions [managers...] Generate GitHub Actions workflows
Init has sub commands and there are options but that's it.
This also hopefully feels pretty simple and understantable.
Option Reference
Configuration can live in package.json or a referenced .codependencerc.
Use CLI flags for execution choices such as checking, updating, and output formatting.
From policy to result
The config defines the manifest and dependency policy. The CLI decides whether to
check, preview, or write the result.
Defines the packages controlled by policy. String entries name a package; object entries name a package with an exact version or range. In verbose mode, listed packages are checked or updated. In precise mode, listed packages are held back while the rest can update.
[!NOTE]
Use dryRun: true or --dryRun to preview the same update without writing files.
rootDir
Type: string
Default: "./"
Set the manifest search directory. The default is "./".
{+ "rootDir": "packages/web"}
ignore
Type: Array<string>
Provide glob patterns to skip. An explicit array replaces the default ignores.
{+ // Replaces the default ignore patterns.+ "ignore": ["examples/**", "fixtures/**"]}
debug
Type: boolean
Default: false
Enable diagnostic logging. The default is false.
{+ "debug": true}
silent
Type: boolean
Default: false
Suppress normal output while preserving errors. The default is false.
{+ "silent": true}
--config
Type: string
Default: undefined
Use a specific configuration file instead of auto-discovery.
codependence --config ./config/.codependencerc
searchPath
Type: string
Default: undefined
Set where configuration discovery starts.
codependence --searchPath ./services/api
yarnConfig
Type: boolean
Default: false
Enable Yarn configuration support. The default is false.
codependence --yarnConfig
permissive
Type: boolean
Default: undefined
Treats listed codependencies as pins. When true, Codependence holds those packages back and updates everything else. This is equivalent to mode: "precise".
Limits how far an approved update can move. patch stays within the same minor version, minor stays within the same major version, and major allows any version change.
[!NOTE]
Exact-version providers can ignore semver level gates when their versions do not follow semver.
mode
Type: "verbose" | "precise"
Default: inferred from codependencies and permissive
Controls how codependencies is interpreted. verbose means "only work on the listed packages." precise means "hold back the listed packages and work on everything else."
The CLI writes the report and prints the destination:
Output written to dependency-report.json
CI
GitHub Actions
The GitHub Action runs the same policy as the CLI from a workflow.
init actions [managers...]
Type: command
Default: all configured manager areas
Generates scheduled workflow files from the configured manifests. Existing generated files are preserved unless --force is provided.
codependence init actions
The command creates stable workflow files for Node, Python, Go, Rust, Docker, and infrastructure targets such as GitHub Actions and Helm. Docker gets its own update-dependencies/docker pull-request branch.
uses: yowainwright/codependence@v1
Type: GitHub Action
Default: check mode
Runs the configured policy without repeating it in workflow YAML.
Limits the action to configured manager targets. Versioned targets need an exact tool version unless a Node package-manager version can be inferred from package.json.
Type: string | Record<"bun" | "npm" | "pnpm" | "yarn" | "go" | "rust" | "uv", string>
Default: inferred for Node package managers when possible
Pins the tool version installed before Codependence runs. Use one exact version for one versioned target, or manager=version entries for multiple targets.
Invalid or missing versions fail before dependency checks run.
::error::pnpm requires an exact version
with: Partial<Options>
Type: Partial<Options>
Default: CLI defaults
The action forwards policy inputs to the CLI, including codependencies, config, files, update, dryRun, permissive, mode, level, language, rootDir, ignore, silent, debug, yarnConfig, noCache, format, outputFile, and lockfile.
Creates or updates a stable pull request for the selected targets. PR mode requires schedule or workflow_dispatch, targets, token, post-update-command, and a clean checkout.
- uses: yowainwright/codependence@v1 with:+ targets: go+ version: 1.24.5+ pull-request: true+ token: ${{ secrets.CODEPENDENCE_TOKEN }}+ post-update-command: go mod tidy
The action exposes the created or updated pull request URL:
Type: { token?: string; "branch-prefix"?: string; draft?: "true" | "false" }
Default: undefined for token, "update-dependencies" for branch-prefix, "false" for draft
Configures pull-request creation. token must be a fine-grained PAT; branch-prefix controls the stable update branch; draft creates the pull request as a draft.
Multi-language, multi-package manager support (experimental)
Declare each ecosystem through a manifest entry in .codependencerc. The
--language flag remains available for one-off runs:
codependence --language python
Use one supported language per run: nodejs, python, go, rust,
docker, github-actions, or helm.
Supported managers
Languages
Language manifest updates
Non-Node providers remain experimental, but all managers can share one config dictionary.
Python requirements updates preserve comments, markers, hashes, and include directives.
Unversioned and URL-based requirements are left unchanged. After updating manifests, regenerate and commit ecosystem lockfiles with their native package managers.
The Docker provider supports explicit pins, latest tag resolution, and
mode: "precise" for Docker Hub and GHCR images.
Tag resolution:
Selects the highest stable numeric tag that is at least as specific as the current tag and preserves its exact prefix and suffix. For example, 20-slim remains in the -slim family, and 3.19 does not switch to a date tag.
Resolves repeated images with different tag families independently.
Resolves FROM tags assembled from one Docker ARG without changing the composition.
Fails on mutable tags such as latest instead of guessing a version.
For authenticated registry access, set DOCKERHUB_USERNAME and
DOCKERHUB_TOKEN for Docker Hub, or GHCR_USERNAME and GHCR_TOKEN for GHCR.
Both GHCR values are required. Docker Hub PATs should be read-only; private
GHCR packages require read:packages access.
[!NOTE]
GitHub Actions support is experimental.
The GitHub Actions provider supports explicit pins, latest release resolution,
and mode: "precise".
Latest versions resolve to immutable commit SHAs, and existing version comments are refreshed with the release tag.
Local and Docker actions remain unchanged.
Authenticated lookups use GITHUB_TOKEN or GH_TOKEN when available.
For private GHCR packages, the action falls back to its workflow token and retries anonymously when GHCR rejects that token for a public package.
[!NOTE]
Helm support is experimental.
The Helm provider checks Chart.yaml dependency entries and updates explicit
object pins in mode: "verbose". It ignores appVersion, local file://
dependencies, templates, digest refs, and dependencies without a version.
[!NOTE]
Execution options such as update, dryRun, format, and noCache stay at the root.
Use --target pnpm or --target go to run only entries for those managers.
Policy Surface
Codependence currently focuses on package manifests and dependency sections.
The same policy model can expand to other version surfaces over time.
Surface
Status
Purpose
package.json dependencies
Supported
Enforce dependency policy in Node.js projects and monorepos
Python, Go, and Rust manifests
Experimental
Apply the same check/update workflow outside Node.js
Dockerfiles
Experimental
Check base image versions
GitHub Actions workflows
Experimental
Check action refs in workflow YAML
Helm charts
Experimental
Check chart dependency versions in Chart.yaml
Local repository scans
Roadmap
Report drift across a directory of projects, such as ~/code
Toolchain files
Roadmap
Keep .nvmrc, .node-version, .tool-versions, and .mise.toml aligned
Compose and other CI YAML
Roadmap
Check service images, actions, and runtime versions in pipeline files
[!NOTE]
Codependencies are project dependencies that must stay current or match a specified version.
When a manifest cannot use latest directly, Codependence writes the resolved version required by its policy. Exact versions and supported ranges remain explicit in .codependencerc.
Why use Codependence?
Codependence is focused on one job: enforcing dependency version policy where your code actually runs.
Traditional dependency PRs vs. Codependence
Traditional providers optimize for immediate update discovery. Codependence
optimizes for one intentional policy check.
If there is a .npmrc file, there is no issue with Codependence monitoring private packages. However, if a yarn config is used, Codependence must be instructed to run version checks differently.
Fixes
With the CLI, add the --yarnConfig option.
With Node.js, add yarnConfig: true to your options or your config.
The repository uses Node.js 26 and pnpm 11. mise installs the pinned development tools.
mise installpnpm installpnpm test
Release Strategy
Codependence publishes securely to npm with trusted publishing, provenance attestations, and immutable GitHub release assets.
Stable releases also provide standalone Homebrew binaries for macOS and Linux through reviewed tap updates.
0.3.1 compatibility
The v1 CLI keeps the final pre-1.0 contract from 0.3.1: the codependence
and cdp binaries, pre-1.0 CLI flags, flat and embedded package.json policy,
and listed-only codependencies behavior. The named script export retains
the pre-1.0 non-throwing API. Use checkFiles or codependence when callers
need v1 errors and version-diff results.