📚 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

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.

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

Tools & surfaces

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 fourteen 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.
• @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 one of the 15 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:

License

Apache License 2.0 © 2026 dsh-github contributors