Preface¶

When a CI run turns red, the common workflow is to open GitHub Actions, navigate to the failed job, and sift through thousands of lines of logs to find the actual error. Timestamps, container IDs, and retry sequences will split the same type of failure into several seemingly completely different chunks of text, and after going through it all, you still might not be able to tell whether the tests failed, dependencies couldn’t be pulled, or the infrastructure timed out.

The architecture of DeepSeek Harness (dsh) is “everything is a plugin”: tools, sessions, and skills can be attached to the agent loop as extensions. The community site DeepSeek Harness Plugin Repository hosts a large collection of such plugins, and it is an independent directory with no official affiliation with DeepSeek or HyperGryph. Among them, dsh-ci-doctor does a very specific job: monitor newly failed GitHub Actions runs, aggregate the raw build logs into diagnostic cards in conversations, and generate normalized error signatures for the failures.

This article is collated after cross-verification against the plugin directory page, the GitHub repository README (including the Chinese version), the npm page, and the DeepSeek Harness official repository.

What is this¶

dsh-ci-doctor is a DeepSeek Harness plugin maintained by jkrandom-sudo, licensed under MIT, and primarily written in TypeScript. The community directory categorizes it under the “Sessions and Messages” section; as of 2026-08-18, it has 3 GitHub stars. The current version on npm is 0.1.2, released on 2026-08-14.

It solves the problem of “clarifying the failure before opening the logs”. The plugin registers two tools with the agent: ci_watch is responsible for monitoring new failures, and ci_diagnose is responsible for generating diagnostic cards. Under the hood, it only uses the locally logged-in GitHub CLI (gh) to call gh api to read status, eliminating the need to configure a separate GitHub Token.

Core Features¶

Monitor New Failures: ci_watch¶

ci_watch starts a background job that polls GitHub Actions at set intervals. On the first poll, it only establishes a baseline, and previously failed runs from history will not be treated as new alerts. You can explicitly pass a repo parameter, or omit it to monitor the repository in the current working directory.

The invocation parameters given in the README are as follows:

{ "repo": "owner/name", "branch": "main", "intervalSeconds": 30, "timeoutMinutes": 60 }

The directory page and README clearly define the behavioral boundaries:
- The job status is readable at any time, and the job can be canceled at any time.
- Transient errors use exponential backoff; give up after 5 consecutive failures; authentication errors fail immediately.
- When a new failure is detected, it will provide the next step: call ci_diagnose for the corresponding repo and runId.

Structured Diagnostics: ci_diagnose¶

ci_diagnose can target a specific run, or default to the most recent failed run. What it returns is a markdown diagnostic card displayed in the conversation, rather than asking you to browse the logs on the Actions page yourself.

An example parameter set:

{ "repo": "owner/name", "runId": 31782742089 }

The diagnostic card will include these verified contents:
- Normalized Error Signature: Masks timestamps, hexadecimal IDs, and numbers, so the same type of failure will get the same ID across different runs.
- Failure Category: test / build / lint / typecheck / dependency / network / permission / timeout / infra.
- Suspect Files: Extracts paths from the logs, and automatically excludes vendor paths.
- Log Excerpt: Cuts the log to a preset budget, marks the number of skipped lines with … (skipped N lines) …, and the documentation explicitly states that no content will be fabricated.

The example card from the repository README is as follows (the example repository is cli/cli, from the project documentation, not the author’s actual test):

## CI diagnosis: cli/cli run #31782742089

**Conclusion:** failure · [run](https://github.com/cli/cli/actions/runs/31782742089)

### Job: Issue Triage (skills-driven)

**Failed steps:** triage
**Signatures:**

- `81a0edf32878` (timeout, first time seen) — server:http_server Session timeout configured…
  **Suspect files:** `script/triage.ts`

Failure Signature Ledger¶

Each diagnosed signature will be remembered: how many times it has been seen, the first and last occurrence times, and the repository and run link for the most recent occurrence. When the failure recurs, it will be marked as seen 3× in the report, rather than treated as a brand new issue.

Persistence depends on whether the host provides a storage domain: if available, it will be written to the ci_doctor unit under the DSH storage directory; if not, it will only be stored in memory. The configuration item ledgerEnabled is enabled by default.

Read-Only Contract¶

Both tools follow the documented convention of only reading GitHub status, and will not push, merge, cancel, rerun, or modify repository contents. Each result comes with a repositoryWrites: false flag. The package also exports an optional companion plugin dsh-ci-doctor/invariant: on hosts that provide the invariants service, if this flag is missing, an error will be thrown directly. The repository’s cordis.patch.yml notes that the default web/base profile does not have this service, so invariant is not included in the default patch to avoid blocking startup.

Installation and Activation¶

The installation command given on the community directory page, to be run in the DeepSeek Harness terminal:

dsh plugin add github:jkrandom-sudo/dsh-ci-doctor

For reproducible installations, fix the commit hash as instructed on the directory page (replace commit with the actual hash):

dsh plugin add github:jkrandom-sudo/dsh-ci-doctor#commit

The repository README also provides an alternative installation method using the npm package name and specifying the web profile:

dsh plugin --profile web add dsh-ci-doctor

Both methods can be found in public materials. Use the directory page command as the primary reference; if you usually install npm plugins using the web profile, refer to the README.

Prerequisite: The GitHub CLI is installed and logged in locally:

gh auth login

The plugin reuses this login session, and the README explicitly states that there are no other required configurations.

Adjustable options (consistent between the README and the source code src/config.ts):

Typical Usage¶

After installation, you can use natural language prompts. The corresponding relationships given in the README are:
1. “Help me monitor the CI of this repository and let me know when it fails” → Start the ci_watch background job.
2. “Why did the nightly build fail?” → Run ci_diagnose on the most recent failed run.
3. “Diagnose the run 31782742089 of cli/cli” → Run targeted diagnostics for the specified run ID.

When the monitor detects a new failure, the job will conclude by calling ci_diagnose, and the agent can then post the diagnostic card into the conversation.

Applicable Scenarios and Notes¶

It is particularly suitable for these situations:
- You write code daily in dsh and want CI red alerts to first turn into structured summaries, rather than immediately opening the Actions page.
- The same type of failure recurs repeatedly, and you need normalized signatures and the ledger to determine whether it is an old issue.
- You only want to read logs, locate categories and suspect files, and do not want the plugin to modify remote repositories.

Before using, please note:
1. Permissions and Security. The directory page explicitly states: the plugin runs with the permissions of the current dsh process, and may execute code during installation. Before installing, you should check the GitHub source repository and license (this plugin is MIT licensed).
2. Only Covers GitHub Actions. The documentation describes reading GitHub status via gh api, do not treat it as a universal Jenkins / GitLab CI diagnostic tool.
3. It does not fix code. The tool is read-only, it will not rerun workflows or automatically submit fixes; subsequent code changes will still be handled by the agent or the developer.
4. Depends on Local gh Login. Authentication failures will exit the monitor immediately; without logging in, polling is impossible.
5. Ledger may not be persisted. Without a storage domain, it will only be stored in memory, and recurrence statistics will be lost after the process restarts.
6. Community Plugin, not an official app store shelf. The DeepSeek Harness official repository emphasizes that everything is a plugin; this plugin is released by a community maintainer, and the directory site is an independent platform.

Summary¶

dsh-ci-doctor packages “monitoring CI” and “reading logs” into two tools: ci_watch only reports new failures after the baseline is established, and ci_diagnose aggregates raw logs into diagnostic cards with signatures, categories, suspect files, and honest excerpts. For dsh users who frequently browse red CI alerts on GitHub Actions, it saves the step of searching through logs before opening them, rather than modifying the repository for you.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-ci-doctor/

GitHub: https://github.com/jkrandom-sudo/dsh-ci-doctor

npm: https://www.npmjs.com/package/dsh-ci-doctor