Everything Credda does today

Credda reads your repository on a push and reports the defects nobody filed. Label a bug report instead and it runs in your own CI, makes the failure happen, finds what caused it, writes the patch, and proves it with a test that fails before it and passes after. Credda proposes; it never merges.

Credda makes no claim it did not execute. A report it cannot turn into a runnable check stops there. A check that captures no failure says so.

One workflow file and one label. No App, no webhook, no credential beyond the token the job already has.

Step one

# .github/workflows/credda.yml
name: Credda on labeled issues

on:
  issues:
    types: [labeled]

permissions:
  contents: read   # checkout of the repository under test
  issues: write    # the one report comment
  id-token: write  # mint the OIDC token that fetches the engine

jobs:
  investigate:
    if: github.event.label.name == 'credda'
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: Credda-io/action@v1
        with:
          # @v1 defaults this to `credda,codereef`, so the run works without
          # the line. Pin it anyway: the second name is there to carry old
          # installs through the rename and is documented as temporary.
          label: credda
          # REQUIRED on a private repository: uncomment it. POST /v1/engine
          # answers one with no licence 402 Payment Required, and the fetch
          # fails before `Run Credda`. Public repos are never asked for a key.
          # license: ${{ secrets.CREDDA_LICENSE }}
        # Optional. Without it the heuristic provider reproduces, diagnoses and
        # reports but writes no patch: the fix stage needs a model-backed one.
        # with:
        #   anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

At .github/workflows/credda.yml. It runs on a labelled issue, nothing else.

Step two

gh label create credda --description 'Credda reproduces this bug in a sandbox and comments what it established.'

Once, from a clone, or anywhere with --repo owner/name. The workflow runs because a label was applied, so it cannot create it.

The three permissions

contents: read

Check out the repository under test. Credda cannot run code it cannot see.

issues: write

Post one comment on the issue that triggered the run. How a run reports back, and the only write Credda performs against a repository today.

id-token: write

Mint a short-lived OIDC token that identifies the workflow to Credda. How the engine is fetched: the repository is private, so the download is exchanged for a token GitHub signs about your job. It grants nothing over yours.

Not granted, so not spendable: contents: write, pull-requests, actions, packages, deployments.

What the first run does

• You label an issueThe credda label on any open issue is the whole trigger. Removing and re-adding it runs again after a push.
• The runner builds a sandboxThe first run builds the workspace image: minutes of package installation. Later runs on the same runner image reuse it, rebuilding only when the sandbox Dockerfile changes.
• Your repository executes with no networkRepository code runs in a Docker container with every network interface removed. A runner that cannot provide that plane gets a refusal, not a fallback to the host.
• One comment arrives, or the job summary doesA run that established something comments on the issue. One that established nothing writes to the job summary instead, and that document is about Credda, not about your bug.

Optional: a note on every issue opened

# MERGE this into the workflow above; do not append it.
# Replace that file's `on:` block with this one (`opened` arms triage) and add
# this job beside `investigate`. Appending gives the file two `on:` keys and two
# `jobs:` keys, which GitHub rejects as invalid YAML.
on:
  issues:
    types: [labeled, opened]

jobs:
  triage:
    if: github.event.action == 'opened'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: credda-issue-${{ github.event.issue.number }}
      cancel-in-progress: false
    steps:
      # Optional. With it a refusal can say "this repository holds no
      # `repro.js`" instead of staying quiet.
      - uses: actions/checkout@v4
      - uses: Credda-io/action@v1
        with:
          mode: triage
          # The same name, OPPOSITE reason: in triage mode this is what Credda
          # stays QUIET for, because an issue opened carrying it is about to get
          # a full investigation. @v1 defaults to `credda,codereef`, so this
          # name is already covered; pin it so the quiet set matches the label
          # the workflow above triggers on and does not drift from it.
          label: credda
          # Uncomment on a private repository. Same 402 as above.
          # license: ${{ secrets.CREDDA_LICENSE }}

A second job on the same trigger, reading issues as they open. No container, no install, no model call, no key. It asks for what a report is missing, or says nothing.

One terminal state per investigation, four of them successes. NO_RUNNABLE_CHECK is not among them: nothing ran.

• Ready for reviewREADY_FOR_REVIEW

  A reviewable change backed by executable evidence. Credda proposes it; a human merges it.

• Patch rejectedPATCH_REJECTED

  Credda discarded its own patch rather than hand it over unverified.

• Reproduced and diagnosedREPRODUCED_AND_DIAGNOSED

  Reproduced, and a cause established from cited evidence. No code was changed.

• Reproduced, cause not establishedREPRODUCED_NOT_DIAGNOSED

  Reproduced and its signature captured. No cause is offered, because none was confirmed against evidence. No code was changed.

• Reproduced; the tests assert itCONTRADICTS_SPECIFICATION

  The reported behavior happened, and this repository owns passing tests asserting exactly that. Proved by running the one named test. Naming a cause would make this a defect claim, so none is named. No code was changed.

• No change requiredNO_CHANGE_REQUIRED

  A reproduction ran and the reported failure was not there. A success, reachable only through a reproduction that actually executed.

• No runnable checkNO_RUNNABLE_CHECK

  Nothing ran: no runnable check could be derived from the report, so nothing was established about this repository. Not an all-clear, and not a defect alleged.

• Insufficient evidenceINSUFFICIENT_EVIDENCE

  Not enough was observed to justify a conclusion.

• CanceledCANCELLED

  Stopped before completion.

• Run blockedFAILED

  Credda's own run errored before reaching a verdict. An environment failure, not a defect in your code. Nothing was observed about the repository.

Every material claim cites a recorded artifact: a type, a phase, an ordinal strength.

Every answer the before/after comparison can give

Six, and two decline to answer.

• Failure resolvedFAILURE_RESOLVED

  The same command, re-run against the patched workspace, exited cleanly.

• Failure unchangedFAILURE_UNCHANGED

  The failure signature is identical after the patch. Nothing was fixed.

• Failure changed shapeFAILURE_MUTATED

  The command still fails, but differently. This is the dangerous case: the original defect may be masked, or a new one introduced.

• New failureNEW_FAILURE

  No failure signature was recorded before the patch, and one was recorded after it.

• Not re-runAFTER_NOT_RUN

  A failure was demonstrated, but the failing command has not been re-run since. No claim is made about whether it still fails.

• Not comparableINCOMPARABLE

  There is no before/after pair of observations of the same command, so no comparison is claimed.

git clone https://github.com/Credda-io/core.git
cd core
corepack enable
pnpm install

# Every command below is 'pnpm credda': apps/cli, from source.
pnpm credda --help

The first credda investigate against a path records the repository. The checkout is copied into a disposable workspace and never modified.

# Point Credda at a checkout and describe the failure.
pnpm credda investigate ./my-service "Checkout 500s when the billing address is missing"

# Shells mangle long reports; Windows truncates at the first newline.
pnpm credda investigate ./my-service @report.md
gh issue view 184 --json body -q .body | pnpm credda investigate ./my-service -

# Read what it found.
pnpm credda status
pnpm credda report <investigation-id>
pnpm credda events <investigation-id> --follow

A read-only view over the Credda API, except that it can queue an investigation. An unreachable API is reported with the URL it tried.

npm install
npm run dev   # http://localhost:3000

# API base URL (defaults to http://localhost:4317)
NEXT_PUBLIC_CREDDA_API_URL=http://localhost:4317

The API allows http://localhost:3000 by default. CREDDA_CORS_ORIGIN takes a comma-separated list.

Eighteen spellings, fifteen commands. Any unambiguous prefix of an investigation id works.

• credda investigate <repo-path> <description | @file | -> [options]

  Reproduce a reported failure, find its cause, and on a model-backed provider write the patch and prove it.

  The description is inline, from a file with @path, or piped in as -. The patch is written in Credda’s disposable checkout, never your working tree. It opens no pull request; the Action’s `open-pull-request` input does, on your own GITHUB_TOKEN with `contents: write` and `pull-requests: write`.

• credda discover <repo-path> [--out <dir>] [--max-files <n>] [--json]

  Read a checkout and write the bug reports nobody filed. Executes nothing.

  With --out each report becomes a file `credda investigate @<file>` reads. STATED rows are settled by reading the repository; every other row is an unrun candidate, and pattern-growth candidates are counted rather than listed.

• credda sweep <repo-path> [--max-candidates <n>] [--cost-ceiling <usd>] [--open-pull-request] [options]

  Discover, investigate each candidate, and open a PR for verified fixes (opt-in).

  The whole loop end to end. Model-backed per candidate; --max-candidates caps how many runs start (default 3) and --cost-ceiling stops before starting a run once that much spend is recorded. Without --open-pull-request it reports what it would propose and pushes nothing; with it, a pull request opens for each run that carries a verified change, on the same gate the Action’s `open-pull-request` input enforces. Credda never merges.

• credda docscan <repo-path> [--confirmed-only] [--json]

  Check a checkout against its own documented examples. Opens nothing.

  Reads README fenced blocks and JSDoc @example blocks, admits the examples that are a self-contained call of the documented package with a literal expected value, executes each, and lists the ones whose output contradicts the documented value. No model call, no API key, no install, no network. Execution is a short-lived `node -e` child in the checkout — process-level isolation, not the engine sandbox — so it is safe for a checkout you trust and not production-safe for an untrusted one.

• credda resolve | credda fix <repo-path> <description | @file | -> [options]

  Aliases for 'credda investigate', kept because scripts and docs use them.

  investigate is the current name. Permanent aliases, not deprecated.

• credda doctor [<repo-path>] [--deep]

  Check that this environment can reproduce a bug.

  With a <repo-path> it reports the install, test, build and typecheck commands a run would use, read off the repository rather than executed.

• credda init [--global] [--force]

  Write an credda.config.json with documented defaults.

  --global writes to $CREDDA_HOME instead of the working directory.

• credda status [--repository <path-or-id>] [--state <state>] [--outcome <outcome>] [--ref <ref>] [--limit <n>] [--offset <n>] [--json]

  List recent investigations.

  Defaults to the most recent 20.

• credda report <investigation-id-or-prefix> [--json] [--markdown] [--patch]

  Show what an investigation established, and what it did not.

  Bug, Evidence, Reproduction, Root Cause and Confidence. Change always prints, and says so when a run stopped at the diagnosis. Verification prints when recorded.

• credda resolution <investigation-id-or-prefix> [--json] [--markdown] [--patch]

  Alias for 'credda report', kept because scripts and docs use it.

  report is the current name. A permanent alias, not deprecated.

• credda inspect <investigation-id-or-prefix>

  Show everything one run recorded, in full.

  The reproduction, every hypothesis including refuted ones, and the evidence records.

• credda events <investigation-id-or-prefix> [--since <n>] [--follow] [--json]

  Show the event timeline for an investigation.

  --follow (-f) tails a run until it reaches a terminal state.

• credda triage <issue-file> [--repo <path>]

  Say what Credda could not use in a report, or say nothing.

  Runs no repository code, starts no container, installs nothing, makes no model call, establishes nothing. Silence is the most common outcome; the refusal harvest on /benchmark measures how often.

• credda validations [--repository <path-or-id>] [--state <state>] [--outcome <outcome>] [--limit <n>] [--offset <n>]

  List change-scoped validation runs.

• credda validation <validation-id-or-prefix> [--severity <s>] [--status <s>] [--limit <n>] [--offset <n>]

  Show one validation: its checks, and the findings they raised.

• credda cancel <investigation-id-or-prefix> [--reason <text>]

  Stop a running investigation, or say why it cannot be stopped.

• credda reap [--dry-run] [--max-age-hours <n>]

  Remove sandbox containers left behind by an interrupted run.

No exit code carries the confidence class. Read it with credda report <id> --json.

• Verification is not testingA test written after a patch, by the process that wrote the patch, proves the test agrees with the patch. It does not prove the defect existed, or that it is gone.Engineering note · 5 min read
• The false modification problemAn agent that edits working code is worse than an agent that fixes less. Abstention has to be a first-class outcome, with its own success criteria, and it has to be measured.Engineering note · 7 min read
• Failure signatures: comparing failures, not logsDiffing raw command output answers the wrong question. The question is whether this is the failure that was reported. The dangerous answer is a real failure that is the wrong one.Engineering note · 6 min read