MarginCI

Repository setup

Commit a shared test workload before comparing application changes. Both revisions need the operation’s entry point and the same declared wrapper, inputs and success helpers.

Prepare the shared workload

  1. Install the private alpha outside the application repository and run marginci init inside it.
  2. Define the operation, test cases and success check. Configure providers, rates, credentials, threshold and request bounds.
  3. List the wrapper, success-check helpers and separately stored test inputs in comparison_files. Include imported helpers that define inputs or success. Keep application implementation files out of this list so their changes can be measured. Inputs in marginci.yml are shared automatically.
  4. Commit marginci.yml, .gitignore, the wrapper and its declared helper/input files. The application also needs its committed package.json and supported lockfile. Do not put required inputs under the ignored .marginci/ directory.

For an npm application, stage the setup below and review it before committing. For pnpm, stage pnpm-lock.yaml instead of package-lock.json:

git add package.json package-lock.json .gitignore marginci.yml marginci/
git diff --cached
git commit -m "Set up MarginCI research workload"

Check setup, then compare

Run the nonpaid prerequisite check from the setup commit:

marginci doctor research --against HEAD

The next command calls your providers. Review the cases, success checks, rates, credentials and spending limits before running it.

marginci test research --against HEAD

doctor checks setup without paid calls. test runs both revisions and reports the cost comparison. Even the same commit can produce different costs when provider responses vary.

Land setup before requiring the check

Merge the setup through your normal review process before enabling the required cost check. A baseline that lacks the wrapper or declared comparison files returns ERROR. MarginCI does not copy them from the candidate into the baseline.

On the next application-change branch, compare against a commit that includes setup:

marginci test research --against <base-commit> --json

Replace <base-commit> with the baseline commit. In CI, use the PR event’s immutable base SHA. Locally, the fallback is origin/HEAD unless compare.against is set. The quickstart configuration sets it to HEAD for the initial check; remove that setting or change it before comparing later changes. MarginCI does not fetch history or guess a branch name. Fetch the needed history through your normal Git workflow.

Change test inputs deliberately

Declared comparison_files must be committed, nonignored and identical on both revisions. Missing, dirty, untracked or changed files return ERROR. Land changes to these files as a shared setup change before measuring subsequent application changes.

The candidate configuration, including inline test cases and rates, is applied to both revisions. It need not exist historically in the baseline, but committing it makes comparisons repeatable. Review changes to cases, rates and success checks: they change what the result means. Application code, dependencies and TypeScript configuration remain specific to each revision.

See Cost calculation and results for the recorded comparison inputs.