Skip to main content
Onyx treats git as the canonical code record.

​
Campaigns Are Logical

Campaigns do not map to a shared mutable git branch. They are logical research tracks in Onyx. Each measured attempt writes its own immutable result ref:
When you start with /onyx ..., the orchestrator chooses a slug from the goal and creates or resumes the matching campaign. You can also use onyx campaign setup manually when debugging or scripting.

​
Result Refs

Local workers push result commits with:
Hosted workers can push directly or use GitHub’s Git Database APIs. Optional promotion refs such as refs/heads/onyx/<campaign>/best may move, but those are curated outputs, not the research history.

​
Immutable Rule

Each experiment should be a new commit with its own result ref. Avoid:
  • force-pushing experiment refs;
  • deleting experiment commits;
  • using git reset --hard to rewrite measured history;
  • reusing one commit for unrelated attempts.
This keeps every reported experiment reachable and reviewable.

​
Deleting Campaigns and Experiments

Mistakes are fixed by deleting records, never by rewriting git history. Delete an experiment from the campaign view in the web app. The campaign’s best result is recomputed from what remains. Deletions are tombstoned server-side by each experiment’s runRef. Immutable git refs are left untouched automatically, and deleted app records are not resurrected by later duplicate report attempts.

​
Git Status

Campaign state does not track a mutable branch head. Each experiment tracks its own git state:
  • pending - the result ref has not been validated yet.
  • verified - the result ref points at the reported result commit.
  • missing - the result ref is gone.
  • mismatch - the ref points at a different commit.
  • unreachable - the commit cannot be read from GitHub.
Metrics are preserved even when code reads fail. Re-pushing or validating the correct ref can heal the marker.

​
Comparisons

The app stores each experiment’s explicit base commit and result commit. Diff views compare those commits, or compare one campaign experiment against another when a base experiment is supplied.

​
GitHub Code Reads

Onyx reads exact trees, blobs, and diffs from GitHub at the requested commit using the linked GitHub App installation. Repository sync records metadata and the default branch head, but the app does not clone repositories in the web/API runtime.