PerryLink/dsh-github

dsh-github

Release stamp: 0.7.16 (2026-10-04).

Package name. This project publishes to npm as `@perrylink/dsh-github`. The bare npm name dsh-github belongs to a different, unrelated project — installing it does not install this plugin.

GitHub PRs, reviews, issues, and CI for DeepSeek Harness — every write gated by human approval, token never logged.

*Create, review, merge, and search GitHub from the agent, with a CI composite action, polling review bot, and status-check gate.*

Official repository. This is the only official repository of dsh-github, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add @perrylink/dsh-github (counts toward the deepseek1024.com install ranking).

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add @perrylink/dsh-github

Install & uninstall

• git channel (latest main): dsh plugin --profile web add github:PerryLink/dsh-github — the prepare script builds with production dependencies only.
• npm channel (published releases): dsh plugin --profile web add @perrylink/dsh-github.
• tarball channel: pnpm pack in this repo, then dsh plugin --profile web add ./perrylink-dsh-github-.tgz.
• uninstall: dsh plugin --profile web remove @perrylink/dsh-github (or remove the row from the profile patch).

What is dsh-github?

GitHub PRs, reviews, issues, and CI for DeepSeek Harness — every write gated by human approval, token never logged.

Create, review, merge, and search GitHub from the agent, with a CI composite action, polling review bot, and status-check gate.

*Workflow overview: request → policy / review → verdict. The examples below use the real command surface.*

📚 Table of contents

• What is dsh-github?
• Compatibility
• What you get
• Quick start
• Install & uninstall
• Configuration
• Tools & surfaces
• Architecture
• Permissions & data
• Security boundaries
• Known limitations
• Development
• Repository layout
• Interoperability with other DSH plugins
• Topics
• Contributors
• PerryLink DSH Plugin Family
• License

Compatibility

Surface · Status Harness · DeepSeek Harness dsh-v0.2.1-rc.2 (verified 2026-10-18): engines.dsh >=0.2.1-0 =24.0.0 Platforms · All (host plugin; outbound network to GitHub) Model · Any (static review is deterministic; reviewMode: "model" is optional)

What you get

dsh-github fills the GitHub gap between dsh and tools like Claude Code and Codex: your agent can read, review, open, update, and merge pull requests, read repository metadata and files, comment on and close issues, and search — while a human approves every write and the token stays secret.

• 15 tools — pr_create, pr_merge, pr_update, gh_review, review_post, gh_issue, issue_open, issue_comment, issue_close, gh_search, gh_repo, gh_file, gh_repo_search, gh_checks, all canonical JSON via defineTool, plus the one-shot ci_run when ci.enabled is on.
• 4 command families — /pr create, /review (start/stop/post), /issue open, and /ci (scan/status/start/stop/run , registered under ci.enabled).
• Full PR lifecycle — create → review → update (title/body/state/base) → merge (merge/squash/rebase, optional head-branch delete).
• Inline reviews — review_post posts one summary comment or line-anchored review comments against the PR head commit.
• Approval-gated writes — every GitHub write goes through ctx.approval (default ask, fail-closed); approval reasons preview titles, body sizes, and comment overrides.
• Token secrecy — credentials seam → environment → gh CLI, resolved per operation, never in logs, events, renders, or errors.
• Background review jobs — /review runs on ctx.jobs with the host's own job_list / job_output / job_kill surface.
• Resilience — 429 retry with Retry-After/x-ratelimit-reset backoff; read tools are concurrency-safe; all calls honor cancellation.
• CI surface — the one-shot ci_run tool, a polling review bot, and a status-check gate (composite action action.yml).

Quick start

dsh plugin --profile web add github:PerryLink/dsh-github

# 1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-github

# or from npm (published releases)
dsh plugin --profile web add @perrylink/dsh-github

# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: dsh-github'

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

~~~sh pr_create ~~~

Input

~~~json { "title": "feat: shiny", "body": "desc" } ~~~

Output

~~~text created pull request #7: https://github.com/o/r/pull/7 (main ← feat/shiny) ~~~

*Observed from plugins/dsh-github/test/tools.test.ts:69-74 (fixture + assertions); renderer at plugins/dsh-github/src/tools.ts:189*

Failure branch

Input

~~~text {"title":"x"} (credentials seam empty; GITHUB_TOKEN unset; gh not logged in) ~~~

Output

~~~text { "status": "error", "code": "no-token", "message": "no GitHub token found (source: credentials/env/gh)", "guidance": "Configure one of: 1) a dsh credential for this reference (recommended; $DSH_HOME/.credentials.yaml), 2) the same-named environment variable, or 3) gh auth login for the gh CLI. Set tokenSource in cordis.yml to pin one source." } ~~~

*Observed from plugins/dsh-github/src/credential.ts:96-104; plugins/dsh-github/test/tools.test.ts:88-93*

Brief examples

• pr_merge
• gh_review

Configuration

All tunables are Schemastery Config fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. cordis.patch.yml documents each key inline. In the GUI, the Plugins page settings card (Official group) reads tokenRef from the entry's own configuration form — the 0.1.7-alpha.1 host removed the ctx.settingsScope binding and the namespace-registration seam behind it, so the card no longer owns a settings namespace. The GitHub token is not a configuration field at all: the card reports whether the referenced credential is set and writes it through the credentials file, which is where the host half resolves it.

Key · Default · Meaning tokenSource · auto · auto (credentials → env → gh) or one of credentials / env / gh tokenRef · GITHUB_TOKEN · Credential-seam reference / environment-variable name defaultOwnerRepo · — · Fallback owner/repo when a call names none and git has no origin autoCommit · false · Whether /pr create may instruct the model to commit+push first maxDiffChars · 8000 · Character cap for PR diffs read into reviews renderExcerptChars · 2000 · Character cap for the diff excerpt rendered into tool output maxComments · 20 · Cap for PR comments listed by gh_review reviewJobTimeoutMs · 600000 · Deadline for one background review job (fails with timeout) maxReviewRecords · 50 · Cap for in-memory review-job records; oldest settled records evict first maxFileChars · 12000 · Character cap for file contents read by gh_file maxFindings · 50 · Cap for analyzer findings per review maxLineLength · 300 · Line length beyond which the analyzer flags a long-line finding reviewMode · static · Review engine: static (deterministic analyzer) or model (one-shot subagent through the host's subagents seam; fails loud when the seam is absent) modelReviewProvider · — · Subagent provider name for reviewMode: "model"; defaults to the first registered provider maxRetries · 3 · 429 retry attempts per request retryBaseMs · 500 · Retry backoff base (doubles per attempt) retryMaxWaitMs · 60000 · Retry backoff ceiling requestTimeoutMs · 30000 · Hard per-request timeout; aborts the fetch when exceeded apiBaseUrl · https://api.github.com · GitHub REST base URL (GitHub Enterprise) allowedActions · ['pr.create','pr.merge','pr.update','review.post','issue.create','issue.comment','issue.close','ci.run'] · Write-action whitelist; anything else is denied before approval workspaceDir · process cwd · Working directory for read-only git inspection ci · { enabled: false, … } · CI integration section: polling review bot, status-check gate, and the one-shot ci_run tool (all ci.* keys live inside it)

Tools & surfaces

Surface · Kind · Notes pr_create · tool · Create a pull request (write; approval-gated) pr_merge · tool · Merge a PR (merge/squash/rebase, optional head-branch delete) pr_update · tool · Update a PR (title/body/state/base) gh_review · tool · Read a PR: metadata, capped diff, comments, CI, static findings review_post · tool · Publish a review comment (summary or line-anchored inline) gh_issue · tool · List / get / comment on issues (PRs marked kind: "pr") issue_open · tool · Create an issue issue_comment · tool · Comment on an issue or PR issue_close · tool · Close an issue (optional state reason) gh_search · tool · Search issues and PRs (separate search quota) gh_repo · tool · Read repository metadata gh_file · tool · Read one file at a branch/tag/commit gh_repo_search · tool · GraphQL repository search (separate search quota) gh_checks · tool · GraphQL PR status checks (check runs + commit statuses) /pr create · command · Read git state and queue a pr_create instruction /review · command · Start / stop / post a background review job /issue open · command · Queue an issue_open instruction ci_run · tool · One-shot CI review run by the composite action / CI driver review bot · surface · Polling review bot with idempotent inline comments (ci.*) status-check gate · surface · Publishes the success / needs-changes verdict per PR head commit (action.yml)

Architecture

• Credential seam. tokenSource: auto resolves per operation in the order credentials seam (GITHUB_TOKEN reference) → environment variable → gh CLI token. The value is a local variable handed to the REST client; it never enters canonical values, renders, cards, command outputs, injected notices, job output, approval reasons, or error messages.
• Approval gate. All writes flow through model tools. A tools/pre-execute waterfall listener returns ask for the write tools, so the registry asks the human through ctx.approval (the host logs the approval/asked + approval/decided audit pair) and fails closed without an answerer. Commands never write directly: a write command gathers read-only context, then wakes the agent so the model runs the gated tool inside a turn.
• Background review job. /review starts a github-review job on ctx.jobs; the job fetches metadata (capturing the head-commit SHA for inline posting), the capped diff, CI checks, and existing comments, then runs the deterministic multi-file analyzer (src/review.ts). The job is owned by the calling agent's bare SessionId — 0.1.7-alpha.1 fences the registry on SessionId with no Agent union — so dsh-tool-jobs must be composed or start refuses. With reviewMode: "model", the job hands the capped diff to a one-shot subagent through the host's subagents seam. Completion reaches the session through the host's dsh-tool-jobs consumer; the model reads it with job_output and publishes it with review_post.
• CI composite action / review bot / status-check gate. The repo ships a composite action (action.yml) that reviews PRs, fixes CI, and writes the report; a polling review bot posts idempotent inline comments; and a status-check gate publishes the verdict per PR head commit. The one-shot ci_run tool drives the headless run. Every write stays approval-gated.

Permissions & data

• Permissions: writes ride the official approval seam; nothing is re-implemented or bypassed. The plugin declares network:outbound and filesystem:write in its workshop manifest.
• Data: the review report lives in process memory keyed by job id; nothing durable is written to disk.
• Session log: the plugin adds no custom session event types; all model-visible content flows through host-logged surfaces (tool/result, user/message, command/run, approval/asked…). The notices commands queue carry the plugin's own merge-extensible source kind, { kind: 'dsh-github', form: 'notice', summary } — the host has no catch-all plugin kind, and its session-format admission path refuses one outright.

Security boundaries

• Approval, not enforcement. Writes only produce ask/deny decisions on the official seam; the sandbox and approval systems remain the enforcement authorities.
• Fail closed. Missing approval answerer degrades to the strictest decision — never to silent pass-through.
• The token never leaves the process. It is read per operation and sent only in the Authorization header; never logged, rendered, injected, or surfaced in errors.
• No writes outside approval. /pr create never commits or pushes by itself; with autoCommit: true, the model performs those writes through the bash tool's own approval gate. The review job performs no writes; only review_post publishes, after approval.
• Untrusted content is escaped and marked. formatPostBody backtick- and HTML-escapes diff-derived file names, and external GitHub content (files, bodies, comments, search results) is marked as external in renders.
• Bounded work and rate limits. 429s are retried with backoff; the remaining quota is surfaced on every result, including failures.

Known limitations

• No custom session events — deliberate (see Architecture); audit trails rely on the host's own event vocabulary.
• Static analyzer by default — deterministic rules (src/review.ts), zero tokens, reproducible. reviewMode: "model" costs tokens and requires the subagents seam and a registered provider.
• Jobs and records are process-local — the review report lives in plugin memory keyed by job id; the record map is capped by maxReviewRecords (oldest settled records evict first).
• npm `latest` dist-tags are stale — install through the profile closure dsh-base provides; never bare npm i @deepseek-ai/dsh-tools.

Development

pnpm install             # node ^22.19 || >=24
pnpm run build           # tsc --noEmitOnError → lib/
pnpm run prepare         # self-contained git-install build (scripts/prepare.mjs)
pnpm run prepublishOnly  # build + test before publishing
pnpm test                # vitest run
pnpm run typecheck       # tsc --noEmit
pnpm run check:readmes   # cross-checks TOC anchors, tools, and config keys in all 5 READMEs

Repository layout

src/index.ts          plugin entry (name/inject/apply, applyWithDeps for tests)
src/config.ts         Schemastery Config
src/types.ts          local structural views of host services + Context merging
src/credential.ts     token resolution (seam → env → gh), per operation
src/github.ts         REST client: 429 retry, rate limits, diff media type
src/git.ts            read-only git inspection + origin parsing for any API host
src/review.ts         deterministic diff analyzer + sanitized comment drafting
src/jobs.ts           github-review background job producer (metadata + diff + CI + comments)
src/approval-gate.ts  tools/pre-execute ask/deny gate with write previews
src/tools.ts          the fourteen model-facing tools (plus `ci_run` under src/ci/)
src/commands.ts       /pr, /review, /issue
src/present.ts        pure UI-card presenters
test/                 vitest suite + mock host scaffolding + opt-in e2e smoke
cordis.patch.yml      bundle patch (one insert row)
scripts/prepare.mjs   self-contained git-install build

Interoperability with other DSH plugins

Verified against DSH `0.2.0-rc.2` (the runtime this README ships for) and the high-star plugin set surveyed on 2026-10-05.

This plugin does not interfere with other plugins, including the widely installed high-star ones:

• No tool-name collision. Every tool is namespaced; no bare name owned by a shipped tool or another plugin is registered.
• No service-key collision. It provides no service key at all, so it cannot collide on one.
• No slot collision. It registers no client slot key, so it cannot contend for a shadows-shipped-ui seat.
• No HTTP route collision. It registers no webServer prefix.
• No patch-layer collision. The bundle patch only inserts its own row; it never overrides a built-in row's config.
• No global mutation. It does not patch prototypes, rewrite process.env, or replace the global fetch dispatcher.

Shared event listeners are non-interfering by construction. It observes the ordering-sensitive event tools/pre-execute with ctx.on() — Cordis's broadcast registration, where every listener runs and none can starve another. Every listener here delegates through `next()`, so the chain is never short-circuited, and a mutation is applied to the value next() produced rather than returned in its place:

• tools/pre-execute — also used by cc-safety-net (1576★).

Static evidence: dsh-plugin-doctor K10–K13 report pass for every check on this repository.

Topics

dsh · dsh-plugin · deepseek-harness · github · pull-request · code-review · issue-tracker

Contributors

• @JosephTian876 — the unbundled lib/client.js report (#11).
• @womeimingzi11 — the browser-half module-loader registration report (#14); the factory-wrapped bundle shipped in later releases.
• @PerryLink — creator and maintainer: the GitHub tool surface, approval gate, background review jobs, CI composite action, review bot, status-check gate, and the five-language docs.
• @AraragiEro — the GitHub token settings card in the Plugins settings page (#6).
• @alexchenzl — invited the plugin onto the DSH Directory (#5).

PerryLink DSH Plugin Family

This project is part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.

Expand all plugins

Plugin · Status dsh-aqua-input-check · dsh-archive-check · dsh-auto-review · dsh-autotier · dsh-bid-ca-precheck · dsh-bid-qual-check · dsh-cert-mcp · dsh-checkpoint-rewind · dsh-click · dsh-composer-history · dsh-contract-stance · dsh-customs-doc-check · dsh-data-quality · dsh-demurrage-ledger · dsh-doublecheck · dsh-drill-script-check · dsh-eia-guide-check · dsh-emergency-plan · dsh-essay-rubric-check · dsh-evidence-check · dsh-export-ctl-check · dsh-fast · dsh-fmea-table-check · dsh-forecast-penalty · dsh-fund-research · dsh-github · dsh-gongwen-flow-check · dsh-gongwen-word-check · dsh-guard-plan-qc · dsh-hazchem-check · dsh-hazplan-check · dsh-hidden-risk-map · dsh-hs-classify · dsh-icd-rule-check · dsh-industry-research · dsh-lawcite-adapter · | **[dsh-laya](https://github.com/PerryL