Documentation
This page explains what Vellum does, how to install it, how to read the audit trail, how to verify integrity, seal a checkpoint and export an auditor evidence pack — and gives step-by-step instructions to verify the app's functionality end to end on a test Jira Cloud site.
Runs on AtlassianPure ForgeZero external egressRead-only capture
Overview
Vellum records what changed in your Jira projects — issue field changes, comments, worklogs, issue links, attachments and moves — and stores that history inside Atlassian in a form that makes later alteration detectable.
Each recorded event is hashed and linked to the event before it, forming a per-issue hash chain. Because every link commits to the one before it, changing or removing a historical record breaks the chain in a way the app can detect and report. Vellum also seals periodic checkpoints and can export a self-contained evidence pack that an auditor can re-verify offline, without installing anything.
Concepts
Vellum subscribes to Jira product events (issue created/updated/deleted, comment created/deleted, worklog created/updated/deleted, link created/deleted, attachment created/deleted). Each event is normalised into one or more audit records describing the field, the old value, the new value, who made the change and when.
Every record is canonicalised deterministically and hashed together with the hash of the previous record for that issue (chain_hash = SHA-256(prev_hash + canonical(record))). The result is a per-issue chain. Privileged administrative actions — retention changes, legal holds, prunes, checkpoint seals — are written to a separate, global governance chain.
On a schedule, and on demand, Vellum seals a checkpoint: it folds the current head hash of every issue in a project into a single root hash and stores it, chained to the previous checkpoint. A checkpoint is a compact commitment to the state of the whole project at that moment.
Verification re-computes the hashes from the stored records and compares them to what was stored. It reports PASS, WARN or FAIL with the specific findings, and — where a checkpoint covers the records — whether they are anchored to that checkpoint.
The evidence pack packages the records, checkpoints, governance log, coverage statement and re-verification instructions into a bundle with a per-file digest manifest, so a third party can check it independently.
Getting started
Navigation
| Surface | Where to find it | What it shows |
|---|---|---|
| Audit Trail | Right-hand panel on any Jira issue | That issue's change history, plus a per-issue Verify integrity action |
| Audit Report | Project menu → Audit Report | A filterable, paginated report across the project |
| Admin console | Jira Settings → Apps → Vellum - Audit Trail & Change History | Site-wide report, integrity verification, checkpoint sealing, evidence pack export, legal holds, retention settings, storage meter and the governance log |
Daily use
The issue panel lists changes newest-first: what changed, from what to what, who changed it and when. The project-level Audit Report adds filters (date range, actor, field, category) and pagination, and an export.
Where Jira itself hides or removes information — for example a deleted comment — Vellum retains its own recorded entry and marks it, so the disappearance is visible rather than silent.
Integrity
Verification is available at two levels and is free to run at any time.
Findings are classified rather than collapsed into a single word. A hash that does not reconcile is a FAIL. Conditions that are explainable — for example concurrent capture producing multiple chain heads, or records whose actor name was removed to honour a data-erasure request — are reported as WARN, with the reason stated.
Integrity
Vellum seals checkpoints automatically on a daily schedule, and on demand from the admin console (Seal checkpoint now). Each checkpoint records the root hash over the project's per-issue head hashes, the number of records covered, the point in time it covers, the head of the governance chain, and a link to the previous checkpoint.
Because each checkpoint chains to the one before it, the sequence itself is checkable: a missing or altered checkpoint breaks the continuity, which the evidence pack reports.
Evidence
The admin console can export a self-contained evidence bundle for a chosen project and date window. It contains the records (in both a lossless JSON form and a human-readable CSV), the covering checkpoints including the complete inputs needed to recompute their root, the governance log, a coverage statement, an integrity statement, a time-source disclosure, a continuity statement, a control-model disclosure, a printable summary, and a manifest.
The manifest lists a SHA-256 digest for every file plus a single digest over the pack as a whole, and the pack ships with written re-verification instructions describing, layer by layer, how to check it:
All four layers can be performed offline with standard tools — no Atlassian access and no Vellum installation required.
Governance
Retention is indefinite by default — Vellum never deletes audit history unless an administrator deliberately sets a retention ceiling. Setting or shortening a ceiling is a destructive change, so the app computes how many records the change would destroy and requires that exact number to be confirmed before it applies.
A project can be placed under legal hold from the admin console. While a hold is active, that project's records are excluded from age-based deletion, enforced in the deletion query itself rather than by an app-side filter. Placing and releasing holds, retention changes and prune runs are all written to the governance chain, so the evidence pack can show what was retained, what was deleted and on whose authority.
For reviewers
The following sequence exercises every major feature on a fresh Jira Cloud site and takes about ten minutes. No external accounts, credentials or third-party services are required.
Install Vellum into a test Jira Cloud site as a Jira administrator and approve the read-only permissions.
Open any Jira issue (create one if needed) and make a few changes: edit the summary, change the status, add a comment, and log work. These are the events Vellum captures.
On that issue, open the Audit Trail panel. Each change you just made appears as its own entry, newest first, showing the field, the old and new values, the actor and the timestamp.
In the panel, click Verify integrity. A banner reports PASS / WARN / FAIL for that issue's chain, and states whether the issue is anchored to a sealed checkpoint. Newly captured records verify as PASS.
Open Audit Report from the project menu. Apply a filter (by actor, field or date) and page through the results to confirm filtering and pagination.
Go to Jira Settings → Apps → Vellum - Audit Trail & Change History. The console shows the site-wide report, the storage meter, settings, and the tools below.
Under Tools, choose Seal checkpoint now for the project. The app reports the checkpoint sequence number, how many records it covers, and its root hash.
Choose Verify integrity. The result shows an overall status, the anchored rollup against the checkpoint you just sealed, the row-chain counts, and any findings. It also states its own limitations rather than implying more than it checked.
Choose Auditor Evidence Pack and pick the project and window. The bundle downloads to your machine.
Open reverify-instructions.txt in the bundle and follow it. Recompute each file's SHA-256 and compare against manifest.json; recompute the pack digest; then recompute a checkpoint root from the inputs published in checkpoints.json and confirm it matches the stored root. This is the strongest check available and needs nothing but a hashing tool.
Place a legal hold on the project and release it; then open Settings and set a retention ceiling. Note that shortening retention requires you to confirm the exact number of records the change would destroy. Each of these actions appears afterwards in the governance log.
Review the app's requested permissions: read-only Jira scopes, app storage, and personal-data reporting — no write scopes. Vellum declares no external hosts and makes no calls outside Atlassian, which is why it qualifies for Runs on Atlassian. All data stays in Atlassian-hosted storage in your site's region.
Trust
| Permission | Why it is needed |
|---|---|
read:jira-work | Read issues, comments, worklogs, links and attachments so changes can be recorded, and read the issue a panel is rendered on. |
read:jira-user | Resolve the display name of the person who made a change, so the trail is readable. |
storage:app | Store the audit records, hash chains, checkpoints and governance log inside Atlassian. |
report:personal-data | Support Atlassian's Personal Data Reporting API so account deletions are honoured. |
Vellum requests no write permissions. It never modifies your Jira data; it only reads and records.
Data residency and egress. All data is held in Atlassian-hosted storage provisioned for your site. Vellum declares no external remotes and sends no data to any third party — there is no analytics, no telemetry and no external processor.
Personal data. The trail necessarily contains account identifiers and display names, because an audit record of "who changed what" is meaningless without them. When Atlassian reports that an account has been deleted, Vellum replaces that person's stored display name with a placeholder. Display names are deliberately excluded from the hashed content, so honouring an erasure does not break any existing hash chain or invalidate a previously exported evidence pack.
Help
Email support@worqflow.org. Support hours are Monday to Friday, 9:00 AM – 5:00 PM America/Chicago, with a target first response within one business day.
When reporting an issue, please include your site URL, the project key, the approximate time of the problem, and — if the question concerns verification — the status and findings text the app displayed.