@perrylink/dsh-github — renamed to dsh-github-bot
This package is the old scoped name of dsh-github-bot. It stays installable for compatibility; new releases are published under the bare name.
dsh plugin --profile <profile> add dsh-github-bot
Source: https://github.com/PerryLink/dsh-github-bot · Docs: https://perrylink.github.io/dsh-plugins/packages/dsh-github-bot.html
dsh-github-bot
Renamed from @perrylink/dsh-github. The old scoped package is deprecated; install dsh-github-bot.
Release stamp: 0.8.0 (2026-11-02).
Package name. This project publishes to npm as dsh-github-bot. The bare npm name dsh-github belongs to a different, unrelated project — installing it does not install this plugin.
OpenSSF Scorecard
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-bot, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.
DSH Market
- 1024 store channel:
npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-github-bot (counts toward the deepseek1024.com install ranking).
English · 简体中文 · Español · Português · हिन्दी
dsh plugin --profile <name> add dsh-github-bot
Install & uninstall
- git channel (latest
main): dsh plugin --profile web add github:PerryLink/dsh-github-bot — the prepare script builds with production dependencies only.
- npm channel (published releases):
dsh plugin --profile web add dsh-github-bot.
- tarball channel:
pnpm pack in this repo, then dsh plugin --profile web add ./perrylink-dsh-github-bot-<version>.tgz.
- uninstall:
dsh plugin --profile web remove dsh-github-bot (or remove the row from the profile patch).
What is dsh-github-bot?
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 diagram for dsh-github-bot: request → policy / review → verdict.
Workflow overview: request → policy / review → verdict. The examples below use the real command surface.
📚 Table of contents
Compatibility
| Surface | Status |
|---|
| Harness | DeepSeek Harness dsh-v0.2.1-rc.2 (verified 2026-10-18): engines.dsh >=0.2.1-0 <0.3.0; the P0 compatibility paths have regression tests. |
| 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-bot 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 <pr>, 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-bot
# 1. install the bundle into your profile
dsh plugin --profile web add github:PerryLink/dsh-github-bot
# or from npm (published releases)
dsh plugin --profile web add dsh-github-bot
# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: dsh-github-bot'
Examples
These are the plugin's real entry points; install once, then call one.
Detailed example
Command
pr_create
Input
{
"title": "feat: shiny",
"body": "desc"
}
Output
created pull request #7: https://github.com/o/r/pull/7 (main ← feat/shiny)
Observed from plugins/dsh-github-bot/test/tools.test.ts:69-74 (fixture + assertions); renderer at plugins/dsh-github-bot/src/tools.ts:189
Failure branch
Input
{"title":"x"} (credentials seam empty; GITHUB_TOKEN unset; gh not logged in)
Output
{
"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-bot/src/credential.ts:96-104; plugins/dsh-github-bot/test/tools.test.ts:88-93
Brief examples
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 token itself is the entry's githubToken field: the card writes it there, and the host half resolves it ahead of the credentials file, the environment, and the gh CLI.
| Key | Default | Meaning |
|---|
tokenSource | auto | auto (page field → credentials → env → gh) or one of config / credentials / env / gh |
tokenRef | GITHUB_TOKEN | Credential-seam reference / environment-variable name |
githubToken | — | Token saved from the Plugins page; plain text in the profile configuration, tried first while non-empty |
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 seam; fails loud when the seam is absent) |
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 () |
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). 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-bot', 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
License
Apache License 2.0 © 2026 dsh-github-bot contributors
