#################################################################################################
#                                                                                               #
#              ____       _  __   _   _            _ _                ____ ___                  #
#             / ___|  ___| |/ _| | | | | ___  __ _| (_)_ __   __ _   / ___|_ _|                 #
#             \___ \ / _ \ | |_  | |_| |/ _ \/ _` | | | '_ \ / _` | | |    | |                  #
#              ___) |  __/ |  _| |  _  |  __/ (_| | | | | | | (_| | | |___ | |                  #
#             |____/ \___|_|_|   |_| |_|\___|\__,_|_|_|_| |_|\__, |  \____|___|                 #
#                                                             |___/                             #
#                                                                                               #
#################################################################################################

React to broken CI with context, diagnosis, and an automated fix path — a GitHub App plus Temporal worker that collects failure data, asks Claude for a root cause and patch, applies changes via GitHub or Morph, runs tests and optional proof checks, then updates status or merges when your policy allows.

---

At a glance

Trigger	Failed GitHub Actions workflow runs (with allowlists, deduplication, and budgets)
Orchestration	Temporal — durable workflows and retries
AI	Anthropic Claude for structured diagnosis (optional cheap triage first-pass)
Patching	Unified diffs on a branch / PR, or Morph (MorphClient) when configured
Verification	Tests on healing tip · optional Lean proofs · optional static / fuzz / attestation
State	Redis required for production budget/dedup (fail-closed unless degraded opt-in)

---

How it flows

flowchart LR
  GH[Failed workflow run]
  APP[GitHub App]
  TMP[(Temporal)]
  WF[SelfHealingWorkflow]
  D[Diagnose]
  P[Patch]
  T[Test]
  X[Merge / status]

  GH --> APP
  APP --> TMP
  TMP --> WF
  WF --> D --> P --> T --> X

Loading

From here you can go deeper: full architecture, docs index, security overview.

---

Prerequisites

Requirement	Notes
Node.js	20+
pnpm	8+ (see package.json packageManager)
Temporal	Server reachable from the worker (CLI dev server or hosted)
Redis	Required in production for budget/dedup (fail-closed). Local may set SELF_HEALING_ALLOW_DEGRADED=true
Docker	Optional — for SELF_HEALING_TEST_EXECUTION_MODE=docker and Freestyle bind mounts

Redis in one command

docker compose up -d redis

Listens on 127.0.0.1:6379 by default — matches REDIS_URL in .env.example. Temporal is not included in Compose; run it separately.

---

Quick start

1. Install and configure

pnpm install
cp .env.example .env
# Edit .env — see tables below

2. Build and validate

pnpm build
pnpm validate

3. Run the app (with Temporal and Redis already up)

pnpm --filter @self-healing-ci/github-app dev
pnpm --filter @self-healing-ci/temporal-worker dev

---

Configuration

Copy .env.example to .env and fill values. Grouped for scanning:

GitHub, AI, Temporal

Variable	Role
GITHUB_APP_ID, GITHUB_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET	GitHub App authentication and webhooks
ANTHROPIC_API_KEY	Claude (skip real calls with SELF_HEALING_DRY_RUN)
TEMPORAL_SERVER_URL, TEMPORAL_NAMESPACE, TEMPORAL_TASK_QUEUE	Worker and client
REDIS_URL	Dedup and workflow state

Self-healing and patching

Variable	Role
SELF_HEALING_ENABLED, SELF_HEALING_DRY_RUN, SELF_HEALING_AUTO_MERGE	Feature gates
SELF_HEALING_WORKFLOW_ALLOWLIST	Comma-separated substrings matched against workflow name (default tokens: ci, test, build, lint)
PATCH_BACKEND	github (default) or morph
MORPH_API_URL, MORPH_API_KEY	Morph HTTP when PATCH_BACKEND=morph

Tests, proofs, and optional gates

Variable	Role
SELF_HEALING_TEST_EXECUTION_MODE	http · docker · local · auto · disabled
SELF_HEALING_TEST_COMMAND, SELF_HEALING_TEST_TIMEOUT_MS, SELF_HEALING_TEST_WORKDIR	Command, timeout, checkout path
FREESTYLE_USE_DOCKER, FREESTYLE_HOST_WORKSPACE, FREESTYLE_DOCKER_*	Docker test backend (@self-healing-ci/freestyle)
FREESTYLE_API_URL, FREESTYLE_API_KEY	Remote Freestyle API (POST /v1/test-runs)
LEAN_PROOFS_EXECUTION_MODE, LEAN_LOCAL_WORKSPACE, LEAN_LOCAL_TIMEOUT_MS	Lean: HTTP, local package, or auto
LEAN_API_URL, LEAN_API_KEY, LEAN_ALLOW_SORRY	Remote Lean API; sorry only if explicitly allowed
SELF_HEALING_REQUIRE_PROOFS	Block merge when proofs skipped (default: on if Lean enabled)
SELF_HEALING_STATIC_ANALYSIS	Optional gate (default off); block on high+ findings
SELF_HEALING_FUZZ	Optional time-boxed differential fuzz (default off)
SELF_HEALING_ATTESTATION	Optional SLSA/cosign attestation (default off)

Cost controls

Variable	Role
SELF_HEALING_MAX_LOG_CHARS, SELF_HEALING_MAX_FAILED_JOB_LOGS	Cap log collection
SELF_HEALING_MAX_CLAUDE_TOKENS, SELF_HEALING_MAX_COST_TOKENS_PER_RUN	Cap Claude spend (fail-closed)
SELF_HEALING_TRIAGE_FIRST, SELF_HEALING_TRIAGE_MODEL, SELF_HEALING_CLAUDE_MODEL	Optional cheaper triage / model override

Observability

Variable	Role
CLOUDEVENTS_INGEST_URL, CLOUDEVENTS_INGEST_TOKEN	Optional CloudEvents HTTP ingest (delivered vs logged-only)
METRICS_PORT, METRICS_AUTH_TOKEN, JAEGER_ENDPOINT, LOG_LEVEL	Metrics (auth required), tracing, logs

---

Repository layout

apps/
  github-app/           Webhooks, Probot, Temporal workflow starts
  temporal-worker/      Workflows, activities, metrics HTTP server
services/
  claude/               Claude client and failure types
  morph/                MorphClient (validate + apply)
  freestyle/            Docker / HTTP test execution
  lean/                 Proof validation (local or HTTP; no-sorry by default)
  static-analysis/      ESLint / Clippy / Ruff / Semgrep (optional workflow gate)
  fuzzing/              Differential cargo-fuzz / Fuzzilli (optional gate)
  attestation/          SLSA + cosign; store local|oci|opa (optional gate)
docs/                   Architecture and security write-ups
scripts/                e.g. security-audit.js
docker-compose.yml      Local Redis (auth + loopback)

---

Scripts

Command	What it does
pnpm build	Build all workspaces
pnpm test	Tests in every package
pnpm test:coverage	Tests with coverage
pnpm lint	ESLint across packages
pnpm type-check	tsc --noEmit everywhere
pnpm format	Prettier check
pnpm validate	lint + type-check + test
pnpm ci	Same pipeline as CI: install, build claude + freestyle + lean, typecheck, lint, test
pnpm security:audit	Repository security audit script
pnpm security:check	Audit script plus pnpm audit

---

Contributing

Branch from main, run pnpm validate before opening a PR. Commits follow Conventional Commits (enforced via Commitlint — commitlint.config.js).

---

License

MIT

---

Security

Report vulnerabilities using SECURITY.md.