Integrate Verging Memory CI with GitHub Actions

This guide shows you how to add Verging Memory CI to a GitHub repository with the Verging Memory CI GitHub Action. This is the default integration for teams that use GitHub. If your repository is hosted elsewhere or your CI system cannot use GitHub Actions, use the API integration guide.

To interpret a delivered report, see Read a regression report.

Get your onboarding details

Open the private setup link in your onboarding email before you begin. You cannot complete the integration without the account-specific values on that page:

• Agent setups: the exact names to copy into environments.
• Test suites: the exact request values to copy into suites, or an instruction to omit suites and select all suites chosen during onboarding that every named agent setup supports and has set up.
• Test endpoint: the non-production API endpoint you provided for Verging Labs to test your product. Never use a production deployment for Memory CI testing.

Your Verging Memory CI API key is also issued at the end of onboarding and shown once. If you no longer have the setup link or key, contact Verging Labs before continuing.

What gets tested

Verging Labs tests whatever your product serves at your test endpoint when a release starts. Deploy the version you want tested before this job starts. A typical CI pipeline builds the release, deploys it to the test endpoint, and then starts the Verging Memory CI job.

vendor_version is the label shown in the report; it does not deploy or verify the version at your endpoint. Make sure the label matches the deployed version. If the job starts before the new version is live, the report will describe the old version under the new label.

A standard release returns a report when testing finishes. A final report follows if grading corrections are needed. Storage-only releases are delivered once. The same applies to a wiring check.

The GitHub Action

Add this workflow file at .github/workflows/verging-memory-ci.yml. Replace the example agent setup names, product name and suite values with the values in your onboarding setup page.

name: Verging Memory CI
on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      fetch_only_release_id:
        description: "Fetch an existing release's report instead of submitting"
        required: false
        default: ""
permissions:
  contents: write
  checks: write
  pull-requests: write
concurrency:
  group: verging-memory-ci-${{ github.ref }}
  cancel-in-progress: false
jobs:
  memory-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: "Verging Memory CI"
          sparse-checkout-cone-mode: true
      - uses: verginglabs/memory-ci-action@v1
        with:
          api_key: ${{ secrets.VERGING_API_KEY }}
          environments: "Claude Code Opus 5,Hermes GPT-5.6 Luna"
          product_name: "Acme Recall"
          suites: core-recall,preference-adherence,truth-maintenance
          fetch_only_release_id: ${{ inputs.fetch_only_release_id }}

Set the repository secret VERGING_API_KEY to the API key issued during onboarding. Never paste the key directly into the workflow or commit it to the repository. Nothing else needs the key: your coding agent adds the workflow file and pushes, and the first push performs the free wiring check on its own.

Set environments to one or more agent setup names from your onboarding page, separated by commas. One name is valid. One Action invocation submits one release and produces one combined report with a section for each agent setup.

Set suites to the comma-separated request values from your onboarding page. Scoping a release to selected suites is a normal way to test different sub-repositories or kinds of pushes. If your onboarding page says to omit suites, remove the line to select all suites chosen for your account and set up on every agent setup in environments. Onboarding is available on Claude Code and Hermes agent setups alike. When several setups are named, a suite set up on some but not all of them is left out, and the receipt names the setup that has it and the release that covers it. See API setup for every suite value.

The workflow_dispatch block supplies GitHub's Run workflow button and the fetch_only_release_id field used for recovery.

What the Action does

For each push or manual start, the Action:

1. Submits one release, or performs the free wiring check until the named test suites are set up, and polls until its page is ready.
2. Commits the report folder into your repository.
3. Posts a GitHub status check named "Verging Memory CI" on the tested commit.
4. On pull requests, maintains one comment with the verdict and report link.

The GitHub status check is success when the Release verdict is Ready and neutral otherwise. It does not block your pipeline. To create a blocking gate, read latest/diff.json: gate on release_verdict == "not_ready" for the report's call, or on verdict and cost_verdict separately.

If a protected branch or a competing push prevents the report commit from landing, the Action pushes it to verging-memory-ci/reports and opens or updates a pull request titled "Verging Memory CI reports".

The sparse checkout gives the Action the report folder and files at the repository root, but not your source directories. The permissions allow it to commit the report, post the status check and comment, and open the recovery pull request.

Recovery after a failed job

Each accepted submission creates a new release. If a job fails after submission, do not submit the same version again. Copy the release_id from the receipt in the job log, select Run workflow, and enter it under fetch_only_release_id. The Action fetches and commits that release's report without submitting another release.

If the job reaches poll_timeout_minutes, nothing failed and no recovery is needed: the job ends green with the release recorded as pending, and the next job on any push, or a mode: sync job, commits the report once it is ready.

After editing a workflow, use Run workflow for the next attempt. GitHub's Re-run all jobs command uses the workflow file from the original attempt.

Collect final reports

At the start of a later release, the Action collects any final reports that are ready for releases already in the report folder. To collect them on demand or on a schedule without submitting a release, add this second workflow.

Add this second workflow file next to the first. It uses the same VERGING_API_KEY secret:

name: Verging Memory CI sync
on:
  workflow_dispatch: {}
  # Optional: also collect final reports between releases, every 3 hours.
  schedule:
    - cron: "17 */3 * * *"
permissions:
  contents: write
  checks: write
  pull-requests: write
concurrency:
  group: verging-memory-ci-${{ github.ref }}
  cancel-in-progress: false
jobs:
  sync-finals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: "Verging Memory CI"
          sparse-checkout-cone-mode: true
      - uses: verginglabs/memory-ci-action@v1
        with:
          api_key: ${{ secrets.VERGING_API_KEY }}
          mode: sync

A sync job submits nothing. It replaces preliminary reports with available final reports and leaves reports that are already final unchanged.

Inputs

api_key (required) : Your API key, supplied through the VERGING_API_KEY repository secret.

environments : One or more agent setup names from your onboarding page, separated by commas or new lines. One release produces one combined report.

mode : release by default. sync submits nothing and collects available final reports already represented in the report folder.

suites : Comma-separated suite values from your onboarding page. Omit this input to select all suites chosen for your account and set up on every agent setup in environments. A suite not yet set up on every named setup is left out; the receipt says which setup has it and how to cover it.

wiring_check : "false" by default. Set it to "true" for one job to perform the free wiring check instead of submitting a release.

vendor_version : The release identifier (e.g. 2.4.1). Defaults to the root VERSION file, or otherwise the short commit SHA.

product_name : The product name used in the report title (e.g. Acme Recall). Free-text inputs — this, vendor_version and agent-setup names — accept letters, digits, spaces, dots, underscores, plus signs and hyphens only; no parentheses, quotes or other punctuation.

fetch_only_release_id : An existing release to fetch without submitting another release. Do not combine it with mode: sync.

poll_timeout_minutes : Minutes to wait for a report. Defaults to 45.

api_base : API base URL. Defaults to https://ci.verginglabs.com.

folder : Report folder at the repository root. Defaults to Verging Memory CI.

Outputs

release_id : The release whose report the job fetched.

verdict : The Release verdict: Ready, or Not ready with the reason. When the job performs a wiring check, this output is Wiring check.

report_path : The repository-relative path to the committed REPORT.md.

The wiring check

With the GitHub Action, the first push performs the wiring check on its own: the job commits its page under Verging Memory CI/releases/<date>-<version>-wiring-check/, ends green, and its outputs say Wiring check in place of a verdict. Until Verging Labs has activated the test suites on your agent setups, every push does the same instead of a release; Verging Labs tells you when your suites are set up, after which pushes submit real releases. To repeat it at any time, set the input wiring_check: "true" for one job. With any other CI system, submit one wiring check through the API yourself, then commit its files through the same path your integration uses for regression reports.

A wiring check does not test your product and does not require an activated environment. Its report uses "format": "wiring-check/v1" and contains no release verdict. Do not gate CI on a wiring report.

Report folder

The Action commits each release under:

Verging Memory CI/
  latest/
    REPORT.md
    diff.json
    release.json
    evidence/
  releases/
    <release_id>/
      REPORT.md
      diff.json
      release.json
      evidence/

latest/ is the stable path for humans and CI. The matching directory under releases/ preserves the same files for that release. Git history preserves a preliminary report after the final report replaces it.

For field definitions and report stages, see Read a regression report. For raw requests, status polling, errors and retry behavior, see API setup. Account setup names and activation are covered in Agent setups. Plan arithmetic is in Billing.

Help, legal and privacy

For integration help, write to contact@verginglabs.com and include the release_id, the request without credentials, the HTTP status, and the response body.

Use of Verging Memory CI is governed by the Terms of Service. Privacy questions can be sent to Matthew Overing at legal@verginglabs.com.