dsh-github

---

📚 Table of contents

• Compatibility
• What you get
• Quick start
• Install & uninstall
• Configuration
• Tools & surfaces
• Architecture
• Permissions & data
• Security boundaries
• Known limitations
• Development
• Repository layout
• Topics
• Contributors
• PerryLink DSH Plugin Family
• License

Compatibility

Surface	Status
Harness	DeepSeek Harness 0.1.0-rc.6 (compat declared for 0.1.0-rc.5–0.1.0-rc.6)
Node	^22.19.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.

• 12 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, all canonical JSON via defineTool.
• 3 command families — /pr create, /review (start/stop/post), /issue open.
• 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

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

# 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'

Install & uninstall

• git channel (latest main): dsh plugin --profile web add "github:PerryLink/dsh-github#main" — 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 ./dsh-github-<version>.tgz.
• uninstall: dsh plugin --profile web remove dsh-github (or remove the row from the profile patch).

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.

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
/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 <pr> 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). 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…).

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 twelve model-facing tools
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

Topics

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

Contributors

• @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.

PerryLink DSH Plugin Family

This project is one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

Plugin	One-liner
dsh-mcp-panel	Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors
dsh-doublecheck	Engineering-discipline guard: requirements grill, test gates, adversary review
dsh-background-agents	Durable background child agents with a Web UI sidebar, messaging and interrupt
dsh-lsp-actions	LSP diagnostics, formatting, completion, code actions and rename over language servers
dsh-output-styles	Claude Code outputStyles-equivalent runtime style switching
dsh-checkpoint-rewind	Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore
dsh-permission-rules	Claude Code-style declarative allow/deny/ask permission rules with audit
dsh-auto-review	Second-model auto-review on the approval chain, fail-closed by default
dsh-memento	Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool
dsh-skill-pack-security	Security-audit skill pack: secret scan, dependency and supply-chain review
dsh-session-pin	Pin sessions in the Web sidebar with durable ordering
dsh-composer-history	Terminal-style input history for the web composer: arrows, Ctrl+R search
dsh-github	GitHub PR/issues integration for DSH, every write gated by approval
dsh-plugin-guide	Plugin-development knowledge base as an on-demand agent skill
dsh-claude-move	Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH

License

Apache License 2.0 © 2026 dsh-github contributors