What it needs

Minimal on purpose. A Python runtime (or the image), a read-scoped token, and — optionally — an LLM endpoint.

Runtime

Python 3.11+, or the self-contained Docker image (dependencies baked in — no pip install at job time).
On GitHub Actions, the action handles this for you: nothing to install, no Python setup step.
Runs in your pipeline's post stage, only on failure. It is read-only and always exits 0.

Access to your CI provider

A read-scoped API token, from an environment variable or a file:

# Env var (name is configurable via gitlab.token_env / github.token_env):
export CI_DOCTOR_GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export CI_DOCTOR_GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# ...or a file (k8s/Vault secret mount), which takes precedence:
#   gitlab:
#     token_file: /run/secrets/gitlab_token

base_url defaults to the public host (gitlab.com / api.github.com); override it for self-hosted GitLab or GitHub Enterprise. Custom CA bundles, self-signed certs, and the standard HTTPS_PROXY / NO_PROXY / REQUESTS_CA_BUNDLE env vars are honoured.

Token scopes

Provider	Needs
GitLab	`read_api`. Add `api` only if you turn on MR notes.
GitHub	`actions: read`. Add `pull-requests: write` only for PR comments.

Predefined CI variables it reads

Provider	Variables
GitLab	`CI_PIPELINE_ID`, `CI_PROJECT_ID`, `CI_MERGE_REQUEST_IID` (for MR notes)
GitHub	`GITHUB_REPOSITORY`, `GITHUB_REF`, `GITHUB_SHA`

None of these are required off a runner. When the repository variable is unset, ci-doctor resolves it from your git origin and logs a warning naming what it picked — so the same command works unchanged on your laptop.

An LLM endpoint — optional

ci-doctor produces a useful deterministic report with no model at all(llm.enabled: false, or simply leaving llm.model/llm.api_base unset). To enable the explanation step, point it at any OpenAI-compatible endpoint: Ollama, vLLM, llama.cpp server, LocalAI, or an internal gateway. An API key is optional. Other backends — litellm, Anthropic, the local claude CLI — are onConfiguration .

Network & air-gap

At runtime it only ever contacts the GitLab/GitHub and LLM endpoints you configure.
No telemetry, no update checks, no runtime downloads of models, rules, or schemas.
Distribute via an internal container registry or an offline wheel bundle — see Examples.