> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/verifying-commits-in-ci.md).

# Verifying commits in CI

Capture on the developer's machine is only half the guarantee. It answers *what did the agent do*, not *did anything reach the branch without being recorded at all*. `tracevault verify` closes that gap: it checks that the given commits are registered and **sealed** on the server, and fails when they are not.

```bash
tracevault verify --range abc1234..def5678
tracevault verify --commits abc1234,def5678
```

## The GitHub Action

The CLI repository ships a composite action that does the whole thing: installs the CLI, works out the commit range from the event, runs `tracevault verify --range`, and writes a pass/fail summary to the Actions step summary with the full output in a collapsed block.

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # the action verifies a commit range, so it needs full history
- uses: VirtusLab/visdom-ai-tracing-cli/action@main
  with:
    server-url: https://your-tracevault-server.example.com
    api-key: ${{ secrets.TRACEVAULT_API_KEY }}
    # version: v0.20.1   # optional; defaults to the latest release
```

{% hint style="danger" %}
`fetch-depth: 0` **is not optional.** The action verifies a range, and on a new-branch push it verifies `HEAD~1..HEAD`, so the parent commit has to exist locally. A shallow checkout fails the step for a reason that has nothing to do with governance.
{% endhint %}

The same evidence backs the compliance view, which is where an auditor looks rather than at a CI log.

![The compliance view: signed, chained records per repository](https://2686717926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2dUajTQaSdFnN24ip7Qo%2Fuploads%2FtqRqPZCLcZISvphSVgWW%2Fcompliance.png?alt=media)

## Which range gets verified

* `pull_request` / `pull_request_target`: the PR's base SHA to its head SHA
* `push`: the event's before-SHA to its after-SHA; for a brand-new branch, where there is no before-SHA, only the head commit is verified

Any other event type is rejected with an error rather than silently passing. The CLI binary is downloaded from the repository's releases, checked against its published `.sha256` sidecar, and installed to `/usr/local/bin`; pin `version` to a release tag when you want a reproducible pipeline instead of the latest release.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-tracing/user-guide/verifying-commits-in-ci.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.