Evergreen

Evergreen

Evergreen finds end-of-life and deprecated runtimes, packages, and GitHub Actions in your repository, shows the exact file and line, and backs every finding with an authoritative source, a replacement, and migration steps. It runs on your machine as a CLI, a local MCP server, a GitHub Action (with SARIF for code scanning), and an Agent Skill, so people and coding agents can find lifecycle risk before it breaks a build, and check a dependency before adding it. Scans are deterministic and offline, and need no account.

Read the public documentation, run the 90-second demo, or inspect the validation report. For AI tools, the docs are also published as llms.txt and llms-full.txt.

What it covers

Ecosystem	What Evergreen reads	What it reports
Container base images (experimental)	Dockerfile, *.Dockerfile, Containerfile, compose.yaml, docker-compose.yml: base images of official node, python, postgres, mysql, and ruby	Image release lines that are end of life. Variables, latest, and floating tags are listed as unclassified, never guessed. See Container base images
.NET (experimental)	global.json, *.csproj/*.fsproj/*.vbproj, Directory.Build.props, Directory.Packages.props, packages.lock.json: the pinned SDK, target frameworks, and direct NuGet packages	.NET release lines past end of support, and direct packages their publisher deprecated, with the C# files that use them. .NET Framework, netstandard, MSBuild properties, floating versions, and ranges are not judged. See .NET
Go (experimental)	go.mod and go.work: go and toolchain directives, and direct require entries	Go release lines that no longer receive fixes, and direct modules with a lifecycle rule. Versions Evergreen cannot read are listed as unclassified. See Go
GitHub Actions	.github/workflows/*.yml: uses: references to actions, including full-SHA pins resolved through a trailing version comment or a bundled release map	Actions on retired runtimes (such as Node.js 20) and retired or deprecated majors, at the exact line
Java and Kotlin (JVM) (experimental)	pom.xml, build.gradle, build.gradle.kts, .java-version, .sdkmanrc, .tool-versions: the JDK a project pins or targets, and direct Maven dependencies. See Java and Kotlin	JDK feature releases that are out of support, and dependencies whose POM says they moved. Property references and expressions are listed as unclassified
Kubernetes APIs (experimental)	*.yaml, *.yml manifests, Helm chart templates/, and kustomization.yaml: the literal apiVersion and kind, and kustomize patches. See Kubernetes APIs	API versions the Kubernetes project says are no longer served. Helm values, cluster-guarded templates, and anything it cannot read literally are skipped
Node.js	engines.node, volta, .nvmrc, .node-version	Runtime versions that are end of life or out of support
npm	package.json dependencies, package-lock.json, npm-shrinkwrap.json, yarn.lock, pnpm-lock.yaml, and the imports and calls that use each package	Deprecated or unmaintained packages, with the replacement and where the package is used
Python	pyproject.toml, requirements*.txt, .python-version, runtime.txt, .tool-versions, poetry.lock, uv.lock, Pipfile.lock	Python versions that are end of life, and deprecated or obsolete packages
Rust (experimental)	Cargo.toml, Cargo.lock, rust-toolchain(.toml): the pinned toolchain and direct crate dependencies	Toolchains older than the newest stable release, and direct dependencies on unmaintained crates with the files that use them. edition, rust-version, stable, and anything it cannot read literally are not judged. See Rust

Each finding carries its rule's sources, review date, and migration steps; see Lifecycle rules. Other ecosystems are not guessed at: Evergreen reports a package it has no rule for as no-data, never as safe, and new ecosystems start from a generated detector skeleton. The compatibility matrix lists supported environments and hosts.

Product principles

• Local-first: source code stays on the user's machine or CI runner.
• Deterministic core: findings do not require an LLM.
• Evidence-backed: every deprecation claim links to an authoritative source.
• Agent-ready: every human-readable report has a machine-readable equivalent.
• Extensible: ecosystems are added through detectors rather than core rewrites.

Quickstart

Requirements: Node.js 22 or newer.

npx evergreen-deprecation scan .

Verify that the CLI, local MCP server, Agent Skill, plugin foundations, and CI workspace are ready without changing configuration or uploading repository data:

npx evergreen-deprecation doctor .
npx evergreen-deprecation doctor . --json

See the public compatibility matrix for supported, experimental, and unsupported combinations.

Discover Evergreen's versioned capabilities and entry points programmatically:

npx evergreen-deprecation capabilities --json

The auto-discovery contract defines the shared identifiers used by the CLI, MCP server, Agent Skill, plugins, and CI integrations.

Create a baseline for accepted existing findings, then report only new lifecycle regressions:

npx evergreen-deprecation baseline .
npx evergreen-deprecation scan . --baseline .evergreen-baseline.json

Check a single dependency before adding it, without scanning a repository:

npx evergreen-deprecation check pkg:npm/request@2.88.2
npx evergreen-deprecation check pkg:github/actions/checkout@v4 --json

The command prints the lifecycle problem, replacement, and evidence, and exits 1 when a rule at or above --fail-on (default high) applies, 0 otherwise, and 2 for invalid input. A package Evergreen has no rule for reports no-data, which is not a claim that it is safe. Without a version, a package whose rules only cover some versions reports version-dependent; add a version to get a definite answer.

Lifecycle rules can be refreshed between releases from signed bundles, and scans stay offline unless you ask:

npx evergreen-deprecation data status
npx evergreen-deprecation data update

See Lifecycle data for the signing and trust model, pinning, and what happens when a download cannot be verified.

Inspect the evidence and migration direction for one result:

npx evergreen-deprecation explain '<finding-id>' .

Generate portable migration context for a human or coding agent:

npx evergreen-deprecation context '<finding-id>' . --json

Migration packets contain rule-specific constraints and steps, exact affected files and usages, authoritative sources, and suggested verification commands. Evergreen never executes those commands automatically. See the migration packet guide.

Tell the coding agents working in a repository to check dependencies before adding them. This adds (or refreshes) a clearly marked section in AGENTS.md, or CLAUDE.md if that is the file you have; running it again changes nothing, and nothing outside the markers is touched:

npx evergreen-deprecation init --agents --dry-run   # show the change
npx evergreen-deprecation init --agents

Connect a coding agent through the local MCP server:

npx --yes --package evergreen-deprecation evergreen-mcp

The stdio server exposes scan_repository, list_deprecations, explain_deprecation, create_migration_context, verify_migration, and check_dependency (check one package before adding it). See the local MCP guide for host configuration, the intended workflow, and privacy guarantees.

Agent Skill

Install the vendor-neutral Agent Skill from the monorepo:

npx skills add arminazimi/evergreen

Pull future revisions with:

npx skills update evergreen-deprecation

The evergreen-deprecation Skill teaches discovery, explanation, migration, and verification while leaving detection and migration logic inside Evergreen. It is discoverable on skills.sh and has been install-validated for Codex, Claude Code, Cursor, GitHub Copilot, and Gemini CLI. See the Agent Skill guide for evaluation, compatibility, limits, and security assumptions.

Codex and Claude plugin packages are generated from that same Skill and MCP workflow. Their packaging architecture keeps host manifests thin and fails CI when either package drifts from the canonical sources. The cross-host evaluation publishes shared-corpus results, context budgets, permission behavior, and security limitations; the same checks block release regressions in npm run check.

Evergreen runs locally and does not upload repository contents.

Development

npm install
npm run check

The initial detector reports unsupported major versions of five first-party actions with exact file and line locations:

• actions/checkout
• actions/setup-node
• actions/cache
• actions/upload-artifact
• actions/download-artifact

Pinned commit SHAs and dynamic expressions are intentionally left unclassified until Evergreen can resolve them without guessing.

The npm detector also reads package.json, npm/pnpm/Yarn lockfiles, Node.js runtime declarations, and a small evidence-backed registry of deprecated direct dependencies. Use evergreen explain <finding-id> to inspect a finding and its sources.

The Python detector reads PEP 621 and Poetry metadata from pyproject.toml, requirements*.txt, common runtime-version files, and uv/Poetry/PDM/Pipenv lockfiles. It reports unsupported Python declarations and lifecycle risks in direct dependencies while ignoring transitive-only lockfile entries.

Source usage analysis

Package lifecycle findings now include the concrete imports, calls, and configuration keys that make a migration necessary. Matching is language-aware and alias-aware for JavaScript, TypeScript, and Python, with configuration-key support for JSON, YAML, TOML, INI, and Python settings. Each match includes its exact file, line, column, and source excerpt, plus a migration-impact estimate based on affected usages and files.

The analyzer scans the repository once for a batch of detector contracts and ignores generated, dependency, build, and environment directories. Run the repeatable accuracy and scan-time benchmark with:

npm run benchmark:usage

See the benchmark notes for the corpus and interpretation.

GitHub Action

Evergreen can annotate pull requests, suppress accepted findings with a baseline, fail on a chosen severity, and upload the complete JSON report:

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
  - uses: arminazimi/evergreen@v0.2.0
    with:
      baseline: .evergreen-baseline.json
      fail-on-severity: high

Pin a full commit SHA instead of a version tag when your threat model requires immutable third-party action references. See the GitHub Action guide for setup, inputs, permissions, artifacts, and privacy boundaries.

Detector SDK

External detectors can use the versioned interface exported by evergreen-deprecation/sdk. The scan engine composes compatible detectors without importing any built-in implementation.

See the detector authoring guide and the minimal detector example.

Initial product shape

The CLI is the product. Detectors extend it, GitHub Actions automate it, and the local MCP server exposes it to agents. A hosted backend is intentionally outside the roadmap; lifecycle data updates through a signed, offline-verifiable data channel instead.

See the roadmap, architecture, brand guide, and contribution guide.

Community

Questions, ideas, and things you built with Evergreen belong in GitHub Discussions: use Q&A to ask, Ideas to propose, and Show and tell to share. Use issues for bugs, lifecycle rule requests, and ecosystem requests.

License and brand

Evergreen source code is licensed under the Apache License 2.0. The Evergreen name, logo, and files in brand/ are proprietary brand assets and are covered by separate brand asset terms.