dsh-github

Bring GitHub into DeepSeek Harness.
Create pull requests · review PRs with inline or summary comments · manage issues · search — every write gated by human approval, token never logged.

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

dsh-github is a bundle plugin for DeepSeek Harness (dsh) — the "everything is a plugin" agent harness. It fills the GitHub gap between dsh and tools like Claude Code (gh claude / claude-code-action) and Codex (@codex review / Autofix CI): your agent can read a PR, review a PR, open a PR, merge and update PRs, read repo 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 either 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, and reports CI status and comment counts alongside the findings
• 🤖 Model review option — reviewMode: "model" delegates the capped diff to a one-shot subagent through the host's subagents seam; the default static mode stays deterministic and token-free
• 🚦 429 backoff + quota surfacing — the model sees the remaining rate limit on every result, including failures; per-section fetch errors are surfaced instead of swallowed
• 🌐 5-language docs — English · 中文 · Español · Português · हिन्दी

📚 Table of contents

• Quick start
• Features
• Installation
• Configuration
• Tools
• Commands
• Architecture
• Security boundaries
• Known limitations
• Development
• Repository layout
• Topics
• Contributors
• License
• PerryLink DSH Plugin Family

🚀 Quick start

# 1. install (npm registry — simplest; or use the tarball channel below)
dsh plugin --profile <name> add @perrylink/dsh-github
#    tarball channel (no registry needed):
#    pnpm pack → dsh-github-<version>.tgz
#    dsh plugin --profile <name> add ./dsh-github-<version>.tgz

# 2. configure a GitHub token (recommended: the credentials seam)
#    $DSH_HOME/.credentials.yaml
#    GITHUB_TOKEN: <your token>

# 3. use it — in the dsh web UI or headless
#    /pr create "add dark mode"      → agent drafts & opens the PR (approval required)
#    /review 42                      → background review job, read it with job_output
#    /review post github-review-1    → publish the review comment (approval required)
#    /issue open "crash on startup"  → agent opens the issue (approval required)

Verify: dsh --profile <name> --dump-config must show the # == dsh-github section with no FAILED lines.

✨ Features

📦 Installation

Four documented channels — pick one.

The npm package is published under the @perrylink scope because the unscoped dsh-github name is owned by an unrelated project on the registry. The plugin's module name stays dsh-github.

Git installs: pnpm ≥10 refuses a git dependency's prepare until allowlisted — dsh prints the exact key; copy it into the profile's pnpm-workspace.yaml:

allowBuilds:
  '@perrylink/dsh-github': true

The prepare script (scripts/prepare.mjs) is self-contained: it builds with TypeScript when a compiler is resolvable, otherwise falls back to the committed lib/ artifacts, and fails loud with neither.

Uninstall: dsh plugin --profile <name> remove @perrylink/dsh-github.

⚙️ Configuration

Schemastery-validated at load time (fail loud). Override any key in the profile's cordis.patch.yml (the whole row config is replaced, never deep-merged).

🛠 Tools

execute returns only the canonical JSON declared by output.schema. Missing-token and GitHub-API failures are structured error variants carrying rate-limit facts; infrastructure failures throw (→ isError). exec.signal is honored everywhere.

⌨️ Commands

🏗 Architecture

                    ┌───────────────────────────────────────────────┐
                    │                   dsh-github                  │
                    │                                               │
 humans ─── /pr ────┼──► git reader (read-only) ──► agent.followup  │
         /review ───┼──► ctx.jobs.start("github-review") ──► job    │
         /issue ────┼──► agent.followup                              │
                    │                                               │
 model ─── pr_create / pr_merge / pr_update / gh_review /           │
           review_post / gh_issue / issue_open / issue_comment /    │
           issue_close / gh_search / gh_repo / gh_file              │
           (defineTool, canonical JSON only)                        │
                    │                                               │
                    └───────┬───────────────┬───────────────┬───────┘
                            │               │               │
                  tools/pre-execute     credential        GitHub REST
                  approval gate        resolution        client (fetch,
                  (ask | deny)      (seam → env →       429 retry,
                                    gh CLI, per-op)     rate-limit)

• 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. All writes flow through model tools. A tools/pre-execute waterfall listener returns ask for the seven 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. Approval reasons preview what would be published (titles, body sizes, merge methods, and the first line of an overridden review body). Commands never write directly: command handlers run with no open turn, so the approval seam is structurally closed to them — a write command gathers read-only context, then wakes the agent (followup when idle, inject when busy) so the model runs the gated tool inside a turn.
• Background review. /review <pr> starts a github-review job on ctx.jobs (label, owner, timeout, cancelable). The job resolves the token per operation, fetches the PR metadata (capturing the head-commit SHA for inline posting), the capped diff, and — unless disabled — CI check runs and existing review comments, then runs a deterministic multi-file analyzer (src/review.ts: hardcoded secrets, Google API keys, credential assignments, debug artifacts, eval, TODO markers, long lines, oversized changes) — zero tokens spent, fully testable. With reviewMode: "model", the job instead hands the capped diff to a one-shot subagent through the host's subagents seam (the owning agent is the parent) and stores the child's Markdown output as the postable report; a missing seam or provider fails loud. Supplementary fetch failures are noted in the output without failing the job. Completion notices reach the initiating session through the host's dsh-tool-jobs consumer; the model reads the report via the existing job_output tool and publishes it with review_post — approval required.
• Model-visible ⇔ logged. The plugin appends no custom session event types. Out-of-repo event types are not in the host's KNOWN_SESSION_EVENT_TYPES, so an unknown required event would make the session log unreadable after plugin removal (the host deliberately defers a registration surface for external plugins). All model-visible content therefore flows through host-logged surfaces: tool/result canonical values, user/message notices via agent.inject/agent.followup, the command/run + command/done lifecycle pair, and the approval/asked + approval/decided audit pair.
• Pure presenters. presentCall/presentResult are pure functions of args (+ the persisted result.meta), identical on live streaming and log replay. PR creation shows a generic card with the PR URL.

🔒 Security boundaries

• The token is read per operation from the configured source (credentials seam, environment, or gh CLI) and sent only in the REST client's Authorization header. It is never logged, never rendered, never injected, never appended to the session log, and never appears in error messages.
• Every GitHub write requires allowed-once from ctx.approval (default policy ask); rejected, cancelled, and unavailable all fail closed.
• /pr create never commits or pushes by itself; with autoCommit: true the model performs those writes through the bash tool's own approval gate. dsh-github does not manage git identity (dsh-git-identity's job) or worktrees (dsh-worktree's job).
• The review job performs no writes: it reads a diff and stores a report in process memory; only review_post publishes, after approval.
• Posted comments interpolate diff-derived file names, which are untrusted repository content: formatPostBody backtick-escapes and HTML-escapes file names so a hostile PR cannot inject Markdown into the review comment.
• File contents read by gh_file and issue/PR bodies, comments, and search results read from GitHub are external untrusted content that enters model context — the same inherent tradeoff as web fetching; the plugin marks them as external content in its renders.
• Rate limits: 429s are retried with backoff and the remaining quota is surfaced to the model 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" delegates the capped diff to a one-shot subagent through the host's subagents seam for an LLM review (costs tokens; requires the seam and a registered provider).
• Jobs and records are process-local — the review report lives in plugin memory keyed by job id, matching the host job registry's lifetime; the record map is capped by maxReviewRecords (oldest settled records evict first).
• npm latest dist-tags are stale — the plugin declares ^0.1.0-rc.5 peer ranges so it resolves against the profile closure that dsh-base provides, and pins 0.1.0-rc.6 for development. Never install by bare npm i @deepseek-ai/dsh-tools.
• CI / GitHub Action — ships in this repository (v0.6.0): a composite action (action.yml) that reviews PRs, fixes CI, and writes the report; a polling review bot with idempotent inline comments; and a status-check gate. Every write stays approval-gated.

🧪 Development

pnpm install
pnpm test          # vitest: config, credentials, 429/retry, tools, commands, jobs, approval gate, token non-leakage
pnpm typecheck
pnpm build         # tsc → lib/ (noEmitOnError)
pnpm pack          # installable tarball
pnpm run check:readmes   # cross-checks TOC anchors, tools, and config keys in all 5 READMEs

Tests mock the GitHub API, the gh CLI, and git through injected runners — no network, no real credentials. test/security.test.ts asserts the token string never appears in any model- or human-visible output. test/e2e.test.ts contains opt-in real-API smoke tests that self-skip unless DSH_GITHUB_E2E_TOKEN is set (read-only endpoints only; the dedicated variable keeps the unit suite hermetic).

To exercise the composite action locally, run node scripts/local-test.mjs --owner-repo you/repo --pr 42 (see --help for all options). The simulator hardcodes DSH_HOME, DSH_PROFILE_DIR, RUNNER_TEMP, and the output directory under a fresh system-temp sandbox for every spawned step — your real dsh home is never read or written, even when a machine-scope DSH_HOME exists — and replays the install → prepare → headless run → post steps of action.yml. action-patch.mjs and action-post.mjs refuse to run outside a GitHub Actions runner, so the action cannot write profile overlays or reports into unknown local locations.

🗂 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

Recommended GitHub repository topics (set them in the repo settings — they power the dsh-plugin topic page and the DSH plugin marketplaces):

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

Contributors

Thanks to everyone who reported issues, reviewed, or contributed code. The first community review cycle for this repository is tracked in its merged PRs (#1–#3, 2026-08-16).

License

Apache License 2.0

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: