Documentation

Witness for Jira

What it does

Witness records changes to your Jira configuration — workflows, permission and notification schemes, fields, screens, issue types, projects and the rest — and keeps them for as long as you choose. Jira's own audit log stops at 180 days and truncates its CSV at 10,000 rows, which does not cover an annual audit cycle. Every record Witness keeps is sealed into a hash chain, so a later alteration is detectable rather than invisible.

Where to find it

Settings → Apps → Configuration audit log. It is an admin page, not a project one: the log of who changed the permission scheme belongs with the things it audits, and not on a screen every user can open.

How changes are captured

Three channels run in parallel and cover for each other. Each knows something the others do not, and the timeline says which of them saw what:

• Jira product events — arrive within seconds. They are the fastest signal that something changed. Atlassian documents the author field on these events as optional, and in our own measurements Jira omits it for field and project changes, so this channel reliably answers what changed rather than who changed it.
• Jira's own audit log — polled every five minutes. This is the channel that names the person. It requires a paid Jira plan: on a Free plan Jira does not keep an audit log at all, and the app says so on the Health tab, in Jira's own words, instead of pretending the channel is working.
• An hourly configuration snapshot — compared with the previous one, showing exactly what changed, line by line. It never knows the author, and it catches things that have neither a product event nor an audit record.

One change seen by several channels is one row in the timeline: the author from one, the detail from another, and the source of each half named next to it. A row is never more confident than the channel it came from.

The tabs

• Log — the timeline, with filters by period, category, object type and actor, and a free-text search. Open a row to see the before/after table, which channels observed it, the record's hash and its place in the chain.
• Integrity — recomputes the whole chain in batches and either confirms that nothing has been altered or names the first record that does not match.
• Export — CSV for spreadsheets, JSON Lines for tooling. Downloaded in batches and saved as one file, with no row limit. Times are UTC in ISO 8601.
• Settings — how long to keep records, when to compact, and the optional digest.
• Health — how much storage the log uses, how long the quota is likely to last, and the state of the three capture channels.

What the hash chain proves

Each record carries the hash of the one before it:

payload_hash = sha256(canonical_json(payload))
hash         = sha256(prev_hash + "
" + payload_hash)

Change a character or remove a record, and every hash after it stops matching. The formula is printed in the auditor report so the chain can be recomputed by someone who does not trust the app. It proves one thing precisely: a record has not been altered or removed since it was written. It does not prove the order in which the changes happened — the audit-log channel brings records in after the fact, and the timeline sorts by event time, not by the order records were sealed.

The auditor report

One button produces a single self-contained HTML file: the period, a summary by category, the result of the integrity check over the whole chain, and the full log. It has no external links or resources of any kind, so it opens in a meeting room with no internet and looks exactly the same.

Keeping records for years

By default nothing is ever removed. When storage runs short, records older than a horizon you choose are compacted into monthly summaries: the counts by category and the boundaries of the period survive, the compaction itself is recorded in the log, and the integrity check still passes across the compacted stretch.

The digest

Off by default. When you turn it on and pick a project, the app creates one issue a day summarising the changes, and Jira's own notifications deliver it. Sending email ourselves would mean sending your data outside Atlassian, which is exactly what this app is built not to do.

What is not audited

• Automation rules. Atlassian's automation REST API is documented as unavailable to Forge apps.
• Organisation-level events (admin.atlassian.com, Atlassian Guard). Reading them would require sending data outside Atlassian and would cost the Runs on Atlassian badge. Witness is a Jira-product-level log.
• Issue history — fields, comments and attachments are not what this app does.
• Anything before installation. Capture starts when you install; earlier changes are visible only as far back as Jira's own audit log reaches.

Without an active subscription

Capture keeps running, the log stays readable, the integrity check still works and the export is still yours to take — a hole in an audit log cannot be repaired later, and your own data is never held hostage. The auditor report and the digest pause until the subscription is renewed.

Something missing here?

Write to support@avakode.com. Questions that arrive twice get added to this page.