dsh-github-toolkit

dsh-github-toolkit

English | 中文

GitHub for DeepSeek Harness: 18 agent-facing github_* tools, plus a GitHub page in Web Settings that stores your PAT in the DSH credential store and takes effect without a restart.

No build step, no runtime dependencies — the host half uses Node's built-in fetch, the browser half requires only react and the shell's static UI primitives.

• The token never lives in configuration. It is resolved from the DSH credential store by reference (default GITHUB_TOKEN) on every request, so rotating the PAT applies to the next call and cordis.patch.yml never contains a secret.
• Configured in the GUI, not the terminal. Paste the PAT, test it against api.github.com from the page before saving, bind a default repository, and switch the write tools on or off.
• Failures name the fix. 401 → rotate the token; 403 with zero quota → when it resets; 403 otherwise → scopes or SAML SSO; 404 → missing or unauthorized; 422 → GitHub's own field-level errors.

Requirements

• DeepSeek Harness 0.1.5-rc.1 or newer (@deepseek-ai/dsh-tools and @deepseek-ai/dsh-credentials are peers the harness provides).
• Node.js 22+ (the host half uses AbortSignal.any).
• A GitHub personal access token; fine-grained tokens are recommended.

Install

dsh plugin --profile web add dsh-github-toolkit

The package declares dsh.bundle, so the installer adds it to the profile's bundle list and the row in cordis.patch.yml mounts the host half. Then refresh the Web UI and open Settings → GitHub.

Without npm:

dsh plugin --profile web add github:<owner>/dsh-github-toolkit

No build scripts are involved, so this installs straight from the repository.

Set it up in the GUI

Open Settings from the bottom-left of the Web UI, then pick GitHub:

1. Refresh the Web UI and open Settings → GitHub.
2. Paste the PAT → Test connection (the page calls api.github.com directly, so you see the account, scopes, and remaining quota before anything is stored) → Save token.
3. Optionally set default owner / default repository and save the configuration.

Interaction decisions worth knowing:

• Testing happens in the browser. GitHub's REST API answers CORS preflights (Access-Control-Allow-Origin: *, and X-OAuth-Scopes / X-RateLimit-* are exposed), so a candidate token can be validated without handing it to the host first.
• Stored tokens are never read back. The credential store reports only whether a value is configured, its source, and whether it accepts writes; the page cannot display the secret. Re-paste to re-test, or ask the model to call github_auth_status.
• Saving applies immediately. Turning write access off unregisters the mutating tools and narrows github_api to GET; turning it on registers them again — no restart.
• Empty means default. Clearing a text field and saving removes your override, so the value falls back to the composition default.

Tools

Read and write tools are modelled separately so permission presets can keep the mutating ones on ask, and one switch turns the plugin read-only.

Returned payloads are curated before they reach the model: GitHub objects carry far more than a model needs, so bodies, patches, and diffs are clipped to configured budgets and marked as truncated.

Configuration

The settings page writes the tool-github namespace in settings.yaml; the composition row only carries defaults:

Credentials

The PAT lives in $DSH_HOME/.credentials.yaml:

refs:
  GITHUB_TOKEN: ghp_xxxxxxxx

Lookup precedence (owned by dsh-credentials-local): launch environment > credential file > project .env > $DSH_HOME/.env. A GITHUB_TOKEN exported before dsh starts therefore shadows the stored value, and the settings page reports that source.

Suggested fine-grained PAT permissions:

• Read-only use: Contents: read, Issues: read, Pull requests: read, Metadata: read
• Write tools as well: Contents: write, Issues: write, Pull requests: write
• CI status: Actions: read, Checks: read
• Organization repositories with SAML SSO need the token authorized for that organization, otherwise the API answers 403.

Troubleshooting

Security notes

• The token is resolved through ctx.credentials per request; the plugin never caches it, never logs it, and has no code path that writes it into configuration.
• Test connection sends the typed value straight to api.github.com (not to the host); it stays in page memory and the field is cleared after a successful save.
• github_api bypasses the purpose-built tools' field validation; with write access off it is restricted to GET.
• The credential file is protected by file permissions, but the agent's tool processes run as the same OS user and can read it — keeping the location unadvertised is discretion, not isolation. A deployment that must keep keys away from its own agent needs a different store.

Development

npm install          # brings the @deepseek-ai peers the tests import
npm test             # host contracts + the browser bundle, offline (plus one live 401 check)
npm run test:installed

• test/smoke.mjs needs no PAT: it drives the plugin the way the loader does, renders the settings section against a minimal React runtime, and asserts the error mapping against stubbed responses. With a network it also checks that a deliberately invalid token comes back as a mapped 401, and skips that part offline.
• test/installed.mjs checks what the harness actually loads: node test/installed.mjs [profile] [pluginDir].

For a local checkout you can point a profile at this folder instead of publishing:

./install.ps1 -DryRun     # show what would be copied and written
./install.ps1             # copy into the web profile and add a manual row
./install.ps1 -Uninstall  # remove the copy and that row

Do not combine that with a dsh plugin add install: both resolve to the same package, and two active loader sources for one package are a composition error.

Layout

Known limitations

• The tools cover the REST surface this plugin models; anything else goes through github_api, which returns bounded JSON rather than a typed result.
• GitHub Search's total_count is approximate for large result sets, and the plugin reports it as-is.
• The browser half is a plain client bundle, so it renders its own controls rather than a schema-driven form; new options are added in lib/client.js and lib/index.js together.
• A profile that has already loaded a client bundle needs a page refresh to pick up a new version of it.

License

MIT