GitHub CI Explainer

Explains failed GitHub Actions checks from the log.

What is GitHub CI Explainer?

GitHub CI Explainer is an Eve agent that Explains failed GitHub Actions checks from the log. It is for Eve developers building with code. Preview every file on this page, then install with npx shadcn@latest add @evex/github-ci-explainer. GitHub CI Explainer is an eve agent that watches failed GitHub Actions checks through a native GitHub App channel.

Explains failed GitHub Actions checks from the log.

Other package managers

Prefer pnpm, yarn, or bun? Copy the matching install command.

npx shadcn@latest add @evex/github-ci-explainer

Category: coding
Files: 14 files
Requires: 4 dependencies
Updated: Aug 28, 2026

What's included

14 files1 tool

Dependencies:@upstash/ratelimit@^2.0.8@upstash/redis@^1.38.0eve@^0.31.3zod@4.3.6

About GitHub CI Explainer

GitHub CI Explainer is an eve agent that watches failed GitHub Actions checks through a native GitHub App channel. When a check_run completes with conclusion failure, GitHub delivers the webhook to your deployed eve app at /eve/v1/github, and the agent comments what failed plus the first useful file and line from annotations or the job log.

It sits next to GitHub Issue Maintainer and Code Reviewer in the same GitHub App world, but its job stops at explaining the failed check. It posts a regular pull request timeline comment when a PR is associated, or a commit comment when there is no PR, and it never changes the branch.

Built-in Upstash-backed rate limiting and per-check idempotency keep public deployments from comment storms when GitHub retries webhooks or several jobs fail in one suite.

How it works

A completed GitHub Actions check_run with conclusion failure triggers the GitHub channel onCheckRun hook at /eve/v1/github.
The channel ignores successful and non Actions checks, then checks Upstash rate limits and claims the check run id so retries do not double-post.
It fetches check annotations and a short log excerpt, parses the first useful file:line, and for commit-only failures posts a commit comment without a model turn.
When a pull request is associated, the channel injects a github_ci_failure_context block and dispatches the zai/glm-5.2 model.
The agent calls explain_ci_failure exactly once with checkRunId, whatFailed, optional file and line, and a short excerpt. The tool has no Eve approval gate.
The channel publishes a structured comment built from those fields as a regular issue or pull request timeline comment. Evals cover a failed-check smoke path and a successful-check negative path.

Use cases

Surface typecheck failures on a pull request

When TypeScript CI fails on a PR, the agent comments the failing check name, the first src file and line from the log, and a short excerpt so reviewers jump to the error without opening the Actions UI.

Explain lint or unit test job failures

ESLint and Vitest jobs that emit annotations or file:line log lines get a concise PR comment naming the job and the primary location, keeping the conversation on the pull request timeline.

Comment on commit-only CI failures

Pushes to a branch without an open pull request still get a commit comment when Contents write is granted, so solo maintainers see what failed on the SHA itself.

Safe explanations on public repositories

Upstash-backed limits default to one explanation per check every fifteen minutes and twenty per public repository per day, so noisy CI cannot exhaust your model budget.

Requirements

GITHUB_APP_ID: The App ID of the GitHub App you create under GitHub Settings, Developer settings, GitHub Apps. The app needs Metadata read, Actions read, Checks read, Contents read, Pull requests read, and Issues read/write for PR timeline comments.
GITHUB_APP_PRIVATE_KEY: The PEM private key generated from the GitHub App settings page. When stored as a single-line variable, replace literal newlines with \n; eve normalizes that form at runtime.
GITHUB_WEBHOOK_SECRET: A long random value set both in the GitHub App webhook configuration and in your deployment. A mismatch produces HTTP 401 responses at /eve/v1/github.
GITHUB_APP_SLUG: The GitHub App slug, defaulting to github-ci-explainer. Used as the channel botName; this agent is check-driven and does not require mention triggers.
KV_REST_API_URL: Upstash Redis REST endpoint used by @upstash/ratelimit for check cooldowns, daily quotas, and duplicate-publication claims. Provision it via Upstash or the Vercel Redis Marketplace integration.
KV_REST_API_TOKEN: The matching Upstash REST token. Use a read-write token, not the read-only one, because the agent writes cooldown and publication keys.
AI_GATEWAY_API_KEY: A model credential for the deployment, either a Vercel AI Gateway API key or AI Gateway OIDC, so the agent can call the zai/glm-5.2 model.

FAQ

How do I install and trigger it?

Run npx shadcn@latest add @evex/github-ci-explainer inside an eve app, deploy it over HTTPS, create a GitHub App pointing its webhook at /eve/v1/github, subscribe to Check runs, install it on your repositories, then push a change that fails GitHub Actions.

Does it change the branch or push a fix?

No. The agent only comments on the check. It never runs git push, never applies a patch to the remote branch, and never publishes a GitHub pull request review with inline review comments.

Which checks does it explain?

Only completed GitHub Actions check runs with conclusion failure. Successful, skipped, cancelled, and third-party check apps are ignored so green builds stay quiet.

Where does the comment appear?

On the associated pull request timeline when the check lists a pull request. If there is no PR, it posts a commit comment on the head SHA when Contents write is available.

How do the rate limits work?

Defaults are one explanation per failed check every 15 minutes, 50 daily explanations per private repository, and 20 per public repository. Tune with CI_EXPLAINER_* variables, or disable with CI_EXPLAINER_RATE_LIMIT_ENABLED=false for local development.

Files this command writes

Core

Tools

npx shadcn@latest add @evex/github-ci-explainer

What is GitHub CI Explainer?

Other package managers

Prefer pnpm, yarn, or bun? Copy the matching install command.

npx shadcn@latest add @evex/github-ci-explainer

Surface typecheck failures on a pull request

Explain lint or unit test job failures

ESLint and Vitest jobs that emit annotations or file:line log lines get a concise PR comment naming the job and the primary location, keeping the conversation on the pull request timeline.

Comment on commit-only CI failures

Pushes to a branch without an open pull request still get a commit comment when Contents write is granted, so solo maintainers see what failed on the SHA itself.

Safe explanations on public repositories

Upstash-backed limits default to one explanation per check every fifteen minutes and twenty per public repository per day, so noisy CI cannot exhaust your model budget.

Requirements

GITHUB_APP_ID

The App ID of the GitHub App you create under GitHub Settings, Developer settings, GitHub Apps. The app needs Metadata read, Actions read, Checks read, Contents read, Pull requests read, and Issues read/write for PR timeline comments.

GITHUB_APP_PRIVATE_KEY

The PEM private key generated from the GitHub App settings page. When stored as a single-line variable, replace literal newlines with \n; eve normalizes that form at runtime.

GITHUB_WEBHOOK_SECRET

A long random value set both in the GitHub App webhook configuration and in your deployment. A mismatch produces HTTP 401 responses at /eve/v1/github.

GITHUB_APP_SLUG

The GitHub App slug, defaulting to github-ci-explainer. Used as the channel botName; this agent is check-driven and does not require mention triggers.

KV_REST_API_URL

Upstash Redis REST endpoint used by @upstash/ratelimit for check cooldowns, daily quotas, and duplicate-publication claims. Provision it via Upstash or the Vercel Redis Marketplace integration.

KV_REST_API_TOKEN

The matching Upstash REST token. Use a read-write token, not the read-only one, because the agent writes cooldown and publication keys.

AI_GATEWAY_API_KEY

A model credential for the deployment, either a Vercel AI Gateway API key or AI Gateway OIDC, so the agent can call the zai/glm-5.2 model.

FAQ

How do I install and trigger it?

Does it change the branch or push a fix?

No. The agent only comments on the check. It never runs git push, never applies a patch to the remote branch, and never publishes a GitHub pull request review with inline review comments.

Which checks does it explain?

Only completed GitHub Actions check runs with conclusion failure. Successful, skipped, cancelled, and third-party check apps are ignored so green builds stay quiet.

Where does the comment appear?

On the associated pull request timeline when the check lists a pull request. If there is no PR, it posts a commit comment on the head SHA when Contents write is available.

GitHub CI Explainer

What is GitHub CI Explainer?

Other package managers

What's included

About GitHub CI Explainer

How it works

Use cases

Surface typecheck failures on a pull request

Explain lint or unit test job failures

Comment on commit-only CI failures

Safe explanations on public repositories

Requirements

FAQ

How do I install and trigger it?

Does it change the branch or push a fix?

Which checks does it explain?

Where does the comment appear?

How do the rate limits work?

Files this command writes

Core

.env.example.env.example19 lines

agent.tsagent/agent.ts6 lines

github.tsagent/channels/github.ts281 lines

instructions.mdagent/instructions.md35 lines

ci-rate-limit.tsagent/lib/ci-rate-limit.ts503 lines

check-run-flow.tsagent/lib/check-run-flow.ts102 lines

fetch-check-failure.tsagent/lib/fetch-check-failure.ts373 lines

failure-context.tsagent/lib/failure-context.ts78 lines

parse-ci-log.tsagent/lib/parse-ci-log.ts129 lines

evals.config.tsevals/evals.config.ts6 lines

failed-check-explains.eval.tsevals/failed-check-explains.eval.ts50 lines

ignore-successful-check.eval.tsevals/ignore-successful-check.eval.ts37 lines

README.mdagent/README.md153 lines

Tools

explain_ci_failure.tsagent/tools/explain_ci_failure.ts88 lines

GitHub CI Explainer

What is GitHub CI Explainer?

Other package managers

What's included

About GitHub CI Explainer

How it works

Use cases

Surface typecheck failures on a pull request

Explain lint or unit test job failures

Comment on commit-only CI failures

Safe explanations on public repositories

Requirements

FAQ

How do I install and trigger it?

Does it change the branch or push a fix?

Which checks does it explain?

Where does the comment appear?

How do the rate limits work?

Files this command writes

Core

.env.example.env.example19 lines

agent.tsagent/agent.ts6 lines

github.tsagent/channels/github.ts281 lines

instructions.mdagent/instructions.md35 lines

ci-rate-limit.tsagent/lib/ci-rate-limit.ts503 lines

check-run-flow.tsagent/lib/check-run-flow.ts102 lines

fetch-check-failure.tsagent/lib/fetch-check-failure.ts373 lines

failure-context.tsagent/lib/failure-context.ts78 lines

parse-ci-log.tsagent/lib/parse-ci-log.ts129 lines

evals.config.tsevals/evals.config.ts6 lines

failed-check-explains.eval.tsevals/failed-check-explains.eval.ts50 lines

ignore-successful-check.eval.tsevals/ignore-successful-check.eval.ts37 lines

README.mdagent/README.md153 lines

Tools

explain_ci_failure.tsagent/tools/explain_ci_failure.ts88 lines

Related Agents

Code Reviewer

Eve Agent Builder

GitHub Issue Maintainer

Related Agents

Code Reviewer

Eve Agent Builder

GitHub Issue Maintainer