1
Open Changes
From the project sidebar, click Detect, then the Changes & drift tab. Without the agent-first interface it is under Fix → Changes in the 21-row sidebar (see Navigation), or under Monitor in the older classic sidebar.
2
Pick a time range
Use the range selector (Last 24 Hours, Last 7 Days, Last 30 Days) to set the window. The feed is sorted newest-first.
3
Filter by kind
Click any kind chip to narrow the feed to just that kind — click again to remove it. Chips are additive: select two kinds to see both.
4
Report your own deploys (optional)
Wire your CI pipeline to
POST /v1/projects/:id/changes so pipeline deploys show up on the same timeline as everything else. See Reporting changes from CI below.The eight change kinds
Every event on the timeline has one of eight kinds:
Each row also carries a severity (
info, notable, or high), shown as a colored left border, and — where the underlying source captured one — a View diff popover showing the before/after values.
Columns and type filter
Changes reported with the typed fields (see below) show their Service, Environment and Version (with the short commit id under it) next to the kind, and the kind cell shows the type (Deploy, Prompt change, Model change, Config change, Feature flag, Dependency, Other). Rows without them, such as prompt deploys and older reports, show a dash. The Type filter next to the agent filter narrows the list to one type, for example only deploys, and the search box also finds a service, environment or version. Below the timeline, Report changes from your pipeline has copy-ready steps for GitHub Actions, GitLab CI, curl and your own app. Report a change takes the same optional type, service, environment and version, and refuses an email address before sending.Hypothesis
In the agent-first frame, a Hypothesis panel appears above the timeline when an open issue was linked to a change and the link is not confirmed. It has three parts:- The claim, for example “Errors rose right after prompt v7”.
- Not ruled out, the reason the link is not confirmed, in the words Zespan stored with the issue. For example, no unchanged group of calls was available to compare against, so other causes in the same minutes are not ruled out.
- Deciding test, the check that would settle that reason, for example “Compare calls the change did not touch over the same minutes.” A reason with no written test shows no test line.
In the agent-first frame
The rest of the page is restyled but keeps every control: Report a change, the range switch, Refresh, Export CSV, the search, agent, type and category filters, Clear filters, the changes-per-day chart, the table with its View diff popover and pager, and the pipeline setup panel. A screen reader still hears the result count (for example “12 of 40 changes shown”) when the list changes; a load failure is announced as an alert.Filters
If any underlying source doesn’t respond in time, a banner marks the result as partial rather than silently showing an incomplete list as complete. The banner names which source(s) were slow.
ChangeEvent fields
Changes around an incident
The incident detail page has its own “Changes around this incident” panel — the same feed, pivoted on an incident’s start time instead of a date range, split into Before and After columns. See Changes around this incident on the Incidents page for details.Gate runs on the timeline
When your deployment has the CI gate switched on, a gate run that carries a commit adds one row to this timeline, titled for the result and the first 7 characters of the commit, for example Gate passed on abc1234. A failed run is marked notable; a passed run and an error run are info. Running the gate again on the same commit updates that row, so it always reads the latest result. A run with no commit adds no row. The GitHub Action can also report the deploy itself. By default it does this on a push when the gate passed, and it shows as a deploy row for the same commit. The Action reports the commit, the environment and the service name; it sends no trace, finding or rule text. Save an API key as the repository secretZESPAN_API_KEY. A change key is enough to report a change on its own, but running a gate needs a project key. See API keys.
Reporting changes from CI
Anything your own deploy pipeline does — a Kubernetes rollout, a feature-flag flip, an infra change — is invisible to Zespan unless you tell it. Report it withPOST /v1/projects/:id/changes and it shows up on the timeline (and in the incident panel’s before/after split) as an external event, right alongside prompt deploys and policy edits.
$ZESPAN_API_URL defaults to https://api.zespan.com — only set it if you’re self-hosting. $ZESPAN_API_KEY is a project-scoped API key (see API Keys). An API key has no role attached — it’s already scoped to exactly one project — so any valid key for the target project works; there’s no separate permission check for API-key callers on this route.
Request body
A successful call returns
201 with { id, title, occurredAt, source, replayed }, where source is the value that was stored. The feed’s actor.displayName for an external change is that source. A change posted from the dashboard keeps the ID of the person who posted it, never their name or email; the feed shows their current name, or Deleted user after the account is erased.
Typed fields (optional)
The same route also accepts the typed fields below, which let the timeline say what kind of change it was and where. Rows without them are stored and shown exactly as before.
Zespan stores metadata only. It rejects an email address in any text field, and the attribute names
author, author_email, author_name, committer, email, user, username, message, commit_message, files, file, diff, patch and branch, with 422. There is no field for a commit message, a person or a file name.
Report from your pipeline with a change key
For a CI job, use a change key instead of your project key: a change key can only report changes, so a leaked pipeline secret cannot read your data or run anything that costs money. Create one in Settings → API keys → Change keys, then post toPOST /v1/changes. The project comes from the key, so the job does not need the project ID.
ref or version gets a default idempotency key, so reporting the same release twice (a retried job, or fifty pods starting together) stores one change: the repeat answers 200 with replayed: true. Limits: 60 requests a minute and 2,000 a day per project (429 with Retry-After), and a 16 KB body (413). The full walk-through, with GitHub Actions and GitLab CI snippets, is in Reporting changes from CI.
Next steps
- Report changes from your CI — change keys, GitHub Actions and GitLab CI snippets, and what you can send
- Incidents — the before/after change panel on incident detail
- Evaluations — the gate rules and runs behind the gate rows
- Alerts — notification rules that share the
alerts:managepermission with reporting changes - Audit Log — the full, unfiltered event history that most change kinds are drawn from

