ci-runner

简体中文

ci-runner

Trigger your CI and get it fixed — a dsh plugin bundle that runs GitHub
Actions workflows and local test pipelines, streams their logs back, tracks
their status, and when something fails hands the tail of the log to DeepSeek
for a Markdown root-cause report with fix steps.

• Two sources, one interface: GitHub Actions via workflow_dispatch
  (+ check-run APIs) and local command pipelines (npm test, pytest, …)
  through the platform shell.
• Bounded log reading: GitHub job logs streamed back per job and
  tail-truncated; local output captured with a per-stream cap so a runaway
  process can't blow up the agent context.
• DeepSeek diagnosis: on failure, the tail log plus a heuristic error
  classification is sent to the harness ctx.llm (or any configured
  OpenAI-compatible endpoint) to produce a report covering failure stage,
  error classification, most likely root cause, suggested fix steps and
  related files.
• Status tracking: poll runs to completion (queued / in_progress /
  completed) with configurable interval and a hard timeout.
• Credentials by environment only: the GitHub token is read from an
  environment variable at call time, never logged and never persisted; every
  returned log and report is masked against known secrets.
• Zero runtime dependencies: fetch + node:child_process, plain
  Node.js ESM, ships with five tools (ci_trigger, ci_status, ci_logs,
  ci_watch, ci_diagnose) and a matching CLI.

How it works

your repo / your machine
   │   workflow_dispatch + check-run APIs      shell (npm test, pytest, …)
   ▼                                          ▼
GitHubApi (fetch)                    LocalRunner (child_process)
   │                                          │
   └──────────────► CiService ◄────────────────┘
        │    trigger · status · logs · watch · diagnose
        ├─► dsh adapter: five ci_* tools on ctx.tools (ctx.llm for analysis)
        ├─► CLI:        ci-runner trigger|status|logs|watch|diagnose
        └─► report:     Markdown with the five canonical sections

All state (stored local runs, config, secret-masking) lives in one
CiService instance, so tools and CLI behave identically. The dsh adapter
and the CLI are two thin entry points over it.

Requirements

• Node.js >= 18.17 (global fetch)
• For the dsh integration: a working DeepSeek Harness install providing the
  tools service (and, for model-powered diagnosis, the llm service).
• A GitHub token in the environment (GITHUB_TOKEN by default) with
  actions:write scope for dispatch and actions:read for status/logs.

Installation into dsh

As a dsh bundle (recommended)

A bundle is an npm package that contributes a configuration layer. From the
profile you want to use:

dsh plugin --profile demo add ./path/to/ci-runner

This links the checkout and appends dsh-ci-runner to the profile's bundle
list because package.json declares dsh.bundle. Verify and boot:

dsh --profile demo --dump-config   # shows the "# == dsh-ci-runner" layer
dsh --profile demo

The contributed patch layer (cordis.patch.yml) inserts one plugin row
mounting the adapter entry (a package subpath resolved through the package's
exports map):

- insert:
    - id: ci-runner
      name: dsh-ci-runner/adapter

As a patch overlay (no packaging)

Point the plugin row directly at the adapter source. Create an overlay file
ci-runner-patch.yml:

- insert:
    - id: ci-runner
      name: '<abs-path>/src/adapter.js'

and pass it to the harness:

dsh --patch ./ci-runner-patch.yml

Applying plugin config

When installed as a bundle, plugin configuration is set through the profile
config (the layer contributed by the bundle) — every field is optional and
defaulted:

# profile/config.yml
ci-runner:
  github:
    defaultRepo: acme/app
    defaultBranch: main
  diagnosis:
    llm:
      baseUrl: https://api.deepseek.com/v1
      apiKey: sk-...
      model: deepseek-chat

Without diagnosis.llm, analysis routes through the harness ctx.llm
service (preferred — matches the harness's configured provider). If neither
exists, diagnosis still produces a deterministic report (stage +
classification + log tail) with a note about the missing model.

Configuration

Field	Default	Meaning
github.tokenEnv	GITHUB_TOKEN	Env var holding the GitHub token (read at call time, never logged)
github.defaultRepo	''	Default owner/repo for GitHub calls
github.defaultBranch	main	Ref used when a trigger doesn't specify one
github.apiBase	https://api.github.com	REST base (GitHub Enterprise override)
github.pollIntervalMs	5000	Poll interval for status tracking
github.pollTimeoutMs	600000	Hard cap for waiting on a run
github.dispatchWindowMs	20000	How long a dispatch may take to surface a run id
github.requestTimeoutMs	30000	Per-request HTTP timeout
github.readLogChars	30000	Default tail cap for ci_logs
local.cwd	.	Working directory for command runs
local.timeoutMs	120000	Hard timeout per command
local.maxOutputChars	40000	Per-stream output cap
local.templates	[{name: 'npm test', command: 'npm test'}, {name: 'pytest', command: 'pytest'}]	Named command templates
diagnosis.llm	null	OpenAI-compatible endpoint override {baseUrl, apiKey, model}
diagnosis.provider	''	ctx.llm provider route ('' = auto)
diagnosis.model	''	ctx.llm model ('' = auto)
diagnosis.maxTailChars	12000	Chars of the log tail sent to the model
diagnosis.timeoutMs	120000	Hard budget for the analysis call
diagnosis.temperature	0.2	Sampling temperature
diagnosis.providerLabel	OpenAI-compatible	Label recorded in reports when the endpoint override is used

Templates let the model and the CLI reference pipelines by name
(ci_trigger {source: local, command: 'npm test'}). Any value that doesn't
match a template name is treated as a raw shell command line.

Tools

Tool	Purpose
ci_trigger	Dispatch a GitHub workflow_dispatch (returns the run id) or run a local pipeline to completion
ci_status	Single poll: status, conclusion, failed stage, jobs and steps
ci_logs	Read logs, masked and tail-truncated; job selects one job
ci_watch	(Optionally trigger and) wait until a run finishes; failed runs include the log tail
ci_diagnose	End-to-end: run/wait, then send the failure tail to the analysis provider and return the Markdown report

Report structure

ci_diagnose (and the CLI diagnose command) always emit the canonical
sections:

# CI Failure Report
## Failure Stage          ← first failing job/step (or "Unknown")
## Error Classification   ← heuristic rule-based pre-analysis
## Most Likely Root Cause ← model analysis (or a note when no model is available)
## Suggested Fix Steps    ← model analysis
## Related Files          ← model analysis (or "None identifiable from the log")
## Timeline               ← start/end/duration when known
## Failure Log Tail       ← masked, tail-truncated

When a model is available, its free-form Markdown is parsed back into these
sections before rendering, so the structure is stable even as the model's
wording varies.

CLI

ci-runner trigger  [--source github|local] [--repo owner/repo] [--workflow F]
                   [--ref R] [--inputs k=v ...] [--command CMD] [--template T]
                   [--cwd DIR]
ci-runner status   [--source s] --run ID [--repo r]
ci-runner logs     [--source s] --run ID [--job J] [--tail N] [--repo r]
ci-runner watch    [--source s] [--run ID | trigger flags] [--timeout-ms N]
                   [--interval-ms N] [--no-logs] [--json]
ci-runner diagnose [--source s] [--run ID | trigger flags] [--save PATH]
                   [--llm-base-url URL] [--llm-model M] [--llm-api-key K]

Global: --config PATH (JSON config file), --json, --help, --version.

For diagnose without a config file, pass --llm-base-url (+ --llm-model
and optionally --llm-api-key; keys can also come from CI_RUNNER_LLM_API_KEY
or OPENAI_API_KEY).

Local run ids are process-local: status/logs on a local run work with a
run id captured inside the same invocation. Across CLI invocations, drive
local pipelines with watch/diagnose + --command (or use GitHub runs,
whose state lives server-side). Inside dsh, all five tools share one
process, so captured run ids stay valid for the plugin's lifetime.

Examples

# GitHub: dispatch ci.yml on main with inputs and print the run id
ci-runner trigger --workflow ci.yml --repo acme/app --ref main --inputs env=prod

# Local: run the "pytest" template (or any raw command)
ci-runner trigger --source local --template pytest --cwd ./api

# Wait for run 123456789, show the tail if it failed
ci-runner watch --run 123456789 --repo acme/app --timeout-ms 600000

# Local failure → DeepSeek diagnosis (markdown report, also saved to disk)
ci-runner diagnose --source local --command "npm test" \
  --llm-base-url https://api.deepseek.com/v1 --llm-model deepseek-chat \
  --save report.md

Security notes

• The GitHub token is read from process.env[github.tokenEnv] on every call
  and exists only in memory; it is never written to logs, reports or disk.
• All returned log text is masked against the GitHub token and any configured
  analysis API key (*** substitution).
• Local commands run in the configured cwd only and are killed as a process
  tree on timeout — no orphaned grandchildren keep running.
• Diagnosis payloads contain the log tail only; the token never reaches the
  model.

Project layout

bin/ci-runner.mjs        CLI launcher
cordis.patch.yml         bundle patch layer (mounts the adapter row)
src/
  adapter.js             Cordis plugin entry: name / inject / Config / apply
  index.js               public package surface (harness-free)
  config.js              canonical config, defaults, validation
  github.js              GitHub REST client (dispatch, runs, jobs, logs, checks)
  local.js               child_process runner (timeout, tree-kill, capped capture)
  logs.js                bounded buffers, tailing, ANSI cleanup, secret masking
  classify.js            rule-based failure classification
  llm.js                 prompt building + OpenAI-compatible client (harness-free)
  dsh-llm.js             ctx.llm stream adapter (harness-side)
  diagnose.js            run metadata + Markdown report assembly
  service.js             cross-source orchestration (tools and CLI share it)
  tools.js               the five ci_* tool definitions
  cli.js                 CLI implementation
test/                    node:test suites (mock GitHub API, temp scripts, diagnosis flow)
examples/                config + profile overlay examples

Test

npm install   # peer deps (schemastery, dsh-llm) for the adapter tests
npm test      # node --test

License

MIT