Applies deterministic rules to changed-file metadata and added lines.
Discovers test, typecheck, and build commands for JavaScript, Python, Go, Rust, Java, and .NET projects.
Produces a human-readable report or a versioned JSON report.
Registers the release_guardian_check tool when installed as a DeepSeek Harness bundle.
Release Guardian is a risk signal, not a proof that a release is safe. A ready verdict means that this scan found no release-blocking condition within its configured scope.
Safety model
The default check operation is read-only with respect to the target repository. It runs local Git commands and reads configuration and manifest files, but it does not execute project code. Release Guardian itself has zero telemetry and does not install project dependencies, publish packages, or deploy software.
Project checks are a separate, explicitly authorized operation:
The CLI runs them only with --run-checks; it displays the exact plan and asks for confirmation. Non-interactive use also requires --yes.
The host tool runs them only with action: "run" and exact command IDs from a prior discovery response.
Approved commands are not sandboxed. They run with the invoking user's permissions in the repository.
Discovery adds offline/no-restore/read-only flags where supported and execution uses a reduced environment, but these controls are best effort. They are not a network or filesystem security boundary.
Execution is allowed only for a complete worktree scan with untracked files included. Approval IDs are bound to the canonical repository, effective baseline policy, and exact diff fingerprint; any source or configuration change invalidates prior approval.
Configured commands may contain arbitrary argv. Merely placing a command in .release-guardian.yml discovers it; configuration is never an execution grant.
Review every displayed command before authorizing it.
Report security-boundary bypasses through the private process in SECURITY.md; never paste a real credential into a public issue.
Development setup and pull-request expectations are documented in CONTRIBUTING.md. Release notes are in CHANGELOG.md.
Requirements
Node.js ^22.19.0 or >=24.0.0
Git
The relevant language toolchains only if checks will be executed
For the DeepSeek Harness route: pnpm plus either dsh on PATH or the official npx @deepseek-ai/dsh launcher
The host bundle is tested against @deepseek-ai/dsh0.1.0-rc.6. DeepSeek Harness is still a developer preview, so re-run the packed-profile smoke test when upgrading RC versions.
Install
Prebuilt GitHub release (recommended)
Download the prebuilt tarball from the latest GitHub release, then install it into a DSH profile:
Git installs run this TypeScript package's prepare build. pnpm 10 and newer require the profile to explicitly allow that build. Review the pinned source, add dsh-release-guardian: true under allowBuilds in the profile's pnpm-workspace.yaml, and repeat the command. Prefer the prebuilt release tarball when you do not want to grant install-time build permission.
Build from a checkout
From this checkout, install Release Guardian's own dependencies and build a package tarball:
npm ci
npm pack
npm pack runs the package prepare script, so the resulting dsh-release-guardian-0.1.0.tgz contains built JavaScript.
For development without a global install, build and invoke node lib/cli.js from this checkout.
DeepSeek Harness bundle
Add the same built tarball to the desired DSH profile:
dsh plugin --profile headless add ./dsh-release-guardian-0.1.0.tgz
# No global dsh installation is required:
npx @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile headless add \
./dsh-release-guardian-0.1.0.tgz
Replace headless with the profile you use. dsh plugin initializes a missing profile, forwards add to pnpm in that profile, and activates this package's cordis.patch.yml bundle. Boot the profile normally; it exposes the release_guardian_check host tool. This package does not provide a Web UI.
# Unstaged, staged, and optionally untracked work against HEAD
dsh-release-guardian check --repo /absolute/path/to/repo
# Index changes against HEAD
dsh-release-guardian check --repo /absolute/path/to/repo --mode staged
# Changes from the merge base of origin/main and HEAD through HEAD
dsh-release-guardian check --repo /absolute/path/to/repo --base origin/main --head HEAD
# Stable machine-readable report
dsh-release-guardian check --repo /absolute/path/to/repo --format json
# Discover and then explicitly approve the displayed test/typecheck plan
dsh-release-guardian check --repo /absolute/path/to/repo \
--checks test,typecheck --run-checks
# After a static JSON scan, execute only one previously displayed check ID
dsh-release-guardian check --repo /absolute/path/to/repo \
--checks test --check-id sha256:... --run-checks
# Rule inventory and remediation details
dsh-release-guardian rules
dsh-release-guardian explain RG103
Check options
Option
Meaning
--repo PATH
Repository path; defaults to the current directory.
--mode worktree|staged|range
Select the diff mode. Supplying --base implies range.
--base REF
Base ref for range mode. The scanner uses its merge base with --head.
--head REF
Head ref; defaults to HEAD.
--include-untracked true|false
Include untracked regular files in worktree mode; defaults to true.
--config PATH
Repository-contained config path; defaults to .release-guardian.yml.
--format text|json
Report format; defaults to text.
--output PATH
Create a report file with mode 0600; an existing file is never overwritten.
--checks LIST
Comma-separated subset of test,typecheck,build.
--check-id ID
Execute only this exact discovered check ID; repeat to select more than one. Requires --run-checks.
--run-checks
Execute the displayed check plan after authorization.
--yes
Confirm non-interactively; valid only with --run-checks.
--fail-on review|block
Exit threshold; defaults to block.
--max-diff-bytes N
Override the diff byte limit.
--timeout SECONDS
Set the per-check execution timeout for this invocation.
--help
Show help.
range mode requires --base. --base conflicts with an explicitly selected non-range mode.
Verdicts and exit codes
Verdict or condition
Exit code
ready
0
review with the default --fail-on block
0
review with --fail-on review
1
block
2
inconclusive, incomplete scan, or fatal audit failure
3
CLI usage error
64
The rules and successful explain commands exit 0.
Diff modes
worktree compares the working tree with HEAD; untracked files are included by default.
staged scans index changes against HEAD; untracked files are not part of this mode.
range computes merge-base(BASE, HEAD_REF) and scans through HEAD_REF. Range and staged scans are read-only review scopes; project checks execute only in full worktree mode.
Diffs are collected with external diff drivers and text conversion disabled. Limits fail closed: truncation produces RG405 and an inconclusive verdict.
Rules
Rules inspect only the selected change: changed-file metadata plus added lines, except where a rule explicitly concerns deletion, binary content, or truncation. Evidence for recognized secrets is redacted in reports.
ID
Detection
Severity / disposition
RG001
High-confidence credential token
critical / block
RG002
Private key material
critical / block
RG003
Probable secret assignment
high / review
RG004
Embedded URL or bearer credential
critical / block
RG005
Sensitive file added
high / review
RG101
Dependency manifest or lockfile changed
medium / review
RG102
Package lifecycle script changed
high / review
RG103
Downloaded or encoded content executed
critical / block
RG201
Broad CI write permissions
high / review
RG202
Untrusted pull-request workflow risk
critical / block
RG203
Workflow action uses a floating reference
medium / review
RG204
Release or deployment configuration changed
high / review
RG301
TLS verification disabled
critical / block
RG302
Shell execution entry point added
high / review
RG303
Dynamic code evaluation added
high / review
RG304
Privilege or host-boundary weakening
critical / block
RG305
Destructive operation added
high / review
RG306
Authentication or access policy weakened
high / review
RG401
Tests removed or substantial test lines deleted
medium / review
RG402
Test skipped or disabled
medium / review
RG403
Schema, migration, or public API changed
medium / review
RG404
Binary content could not be scanned
medium / review
RG405
Scan input or finding output was truncated
high / review
Run dsh-release-guardian explain RULE_ID for the remediation attached to a rule.
Check discovery
Discovery reads manifests without running them. In Git repositories it considers only tracked files and untracked files not ignored by Git, then applies intrinsic exclusions for virtual environments, dependency trees, build output, and nested agent worktrees. It looks to the configured manifest depth (default 4), prefers configured commands, de-duplicates equivalent plans, and returns at most 256 checks by default. The report includes candidate, returned, limit, truncation, and completeness counts.
Ecosystem
Inputs
Discovered commands
JavaScript
package.json scripts and nearest lockfile or packageManager field
test, typecheck, and build scripts via npm, pnpm, yarn, or bun; offline flags where available
Python
pyproject.toml, pytest.ini, tox.ini, mypy.ini
pytest, tox --no-provision, mypy, and build --no-isolation; uses an executable project-local .venv/venv interpreter when present
Go
go.mod
go test, go vet, and go build with -mod=readonly
Rust
Cargo.toml
workspace test, check, and build with --offline --all-targets
Java
pom.xml, build.gradle*
Maven or Gradle test/build with offline flags; repository wrappers are preferred
.NET
.sln, .csproj
dotnet test and dotnet build with --no-restore
Discovery does not verify that a tool or dependency is installed. Availability is determined only if the user authorizes execution.
.release-guardian.yml
The configuration is strict: version must be 1, and unknown fields are rejected. The implemented top-level keys are only version, diff, checks, and limits.
argv: non-empty array of non-empty strings; it is never interpreted as a shell command
required: optional boolean, default true
timeoutSeconds: optional positive integer
timeoutSeconds overrides the invocation/host-wide timeout for that configured command.
Configured commands are only added to the displayed plan. They still require the same explicit execution authorization as discovered commands.
Project policy is loaded from the trusted baseline commit (HEAD for worktree/staged scans and the merge base for range scans). A policy file introduced or modified by the audited change does not take effect for that same scan and makes the result incomplete. diff.exclude and diff.generated reduce non-blocking noise, but they never suppress credential rules or a rule whose adjudicated disposition is block.
JSON report contract
--format json and the host tool emit the same snake_case report with schema_version: "1". It includes the verdict, repository and diff metadata, summary counts, changed files, contextual findings, check plans/results, diagnostics, warnings, and duration. Additive coverage fields include:
diff.files_changed, files_seen, files_excluded, and files_unseen, which reconcile the selected Git scope;
diff.exclusions, which lists the effective pattern, count, and bounded path samples;
diff.fingerprint and candidate_lines_scanned, which make authorization and scan scope auditable;
check_discovery, which reports completeness, candidates, returned checks, limit, truncation, its current_worktree source, and whether that source matches the selected diff scope;
each file's separate change_status and content_kind, so binary or uninspected content does not hide whether a path was added, modified, deleted, renamed, or untracked;
each finding's context, rationale, and occurrences.
Consumers should require the expected schema_version, tolerate additive fields, and use names rather than field order. Fields documented for schema version 1 are the v0.1 machine-readable contract; an incompatible report-format change requires a new schema_version.
Host tool flow
Call release_guardian_check with an absolute repo_path. The request schema version is also "1".
Call with action: "discover" (or omit action) to scan and receive the JSON report and check plan.
Show the verdict, findings, and each check's exact id, cwd, and argv to the user.
Only after explicit authorization, call with action: "run" and the exact approved_command_ids from that discovery response. Use the same repository in worktree mode with untracked files included and without intervening source/configuration changes.
Supported host inputs are schema_version, repo_path, config_path, mode, base, head, include_untracked, max_diff_bytes, categories, action, and approved_command_ids.
Development
npm ci
npm run typecheck
npm test
npm run build
npm run check
npm run guardian:self
npm run check runs typechecking, tests, and a build. npm run guardian:self expects built output and scans this checkout without executing its discovered checks.
