- Overview
- Getting started
- User guide
- Restore guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
User guide
Concepts
Configuration types ("families")
Config Undo works with eight types of Jira configuration. Each object has a stable key (for example PS:10000 for permission scheme 10000), shown on its page in Objects & Compare.
| Type | What a version contains | How changes are detected | Restore |
|---|---|---|---|
| Permission scheme | name, description, every grant (permission + holder) | audit log | yes |
| Notification scheme | name, description, recipients per event | audit log | yes |
| Workflow | statuses, transitions, conditions, validators, post functions, description | audit log; workflow history during onboarding | yes |
| Workflow scheme | default workflow and issue type → workflow mappings | audit log | yes, if no issue would need a status migration |
| Screen | tabs, fields per tab, field order, name, description | audit log | yes |
| Field options | options of one custom field context: value, enabled/disabled, order (select, multi-select, radio, checkboxes, cascading select) | audit log (Jira sends no event for option edits) | yes |
| Project settings | name, description, lead, default assignee, category, scheme associations, role actors, components, versions | audit log and Jira project/version/component events | yes, with exceptions |
| Field scheme | field scheme parameters (experimental Jira API) | reconcile only | no, history and compare only |
Coverage & Health shows the detection mode per type.
Versions
A version is a complete, normalised copy of one object at one point in time. Config Undo stores a new version only when the content changed (the content is hashed; identical content is stored once). Each version has a source:
| Source | Meaning |
|---|---|
| Baseline | first capture during onboarding |
| Audit log | captured after the hourly audit-log poll saw a change |
| Jira event | captured after a Jira product event (projects, versions, components, fields, field contexts) |
| Reconcile | the rolling reconcile found a change that had no audit record or event; the author is unknown |
| Backfill (audit log) | history taken from the audit log during onboarding or by Import older history: shows what the audit log recorded, not a complete version, can't be restored |
| Backfill (workflow history) | a complete earlier workflow version from Jira's workflow history (up to 60 days) |
| Restore | the state after a restore by Config Undo |
| Before restore | the live state saved right before a restore wrote anything ("rollback of the rollback") |
| Restore point re-read | captured by "Re-read everything now" on a restore point |
| Manual re-read | captured by "Compare with live", a preview or the guided test |
The change journal and its sources
The journal is one timeline of changes: who changed which object, when, and what changed. Changes come from:
- the hourly audit-log poll: Config Undo reads new audit records, works out which objects they touch and re-reads exactly those objects;
- Jira product events for projects, versions, components, fields and field contexts, which arrive within minutes;
- the rolling reconcile, which re-reads a share of every type each day (all of it once a week on small and medium sites, once every four weeks on large sites) to catch changes Jira did not audit;
- onboarding backfill from the audit log and workflow history;
- Config Undo's own restores (marked as the app's own change).
Authors come from the audit log and are stored as Atlassian account ids; names are looked up when you view a page. When Jira's audit record names no author (for example automatic changes Jira makes itself), the author column shows Not recorded by Jira. Changes found by reconcile say "detected by reconcile, author unknown". Some entries carry a High impact marker: a grant removed from Browse projects or Administer projects, a status removed from a workflow, or any change to an object used by more than ten projects.
Restore points
A restore point is a named list of "the version of every object that was current at this moment", for all or some configuration types. When only a few changes are waiting since the last hourly poll (up to 15 objects), creating one captures them first; it then records the list and a freshness time per type. Restore points are created by hand or automatically once a week. Restore points older than the retention period are removed by the weekly maintenance run unless they are pinned; pinned restore points, and the versions they reference, are kept regardless of retention.
Restore requests
A restore request puts one object back to one version. It goes Preview → Request → Approve → Result, and every step is recorded. See the Restore guide.
The ledger
The ledger is an append-only record of every restore request, approval, rejection, expiry, execution, verification result, settings change, data deletion and uninstall. Each entry carries a hash over its core fields (sequence number, time, type, request, object, before and after hash, verification result and the person's token) and the hash of the previous entry. Changing or removing an entry's core fields, or removing an entry, breaks the chain, and the integrity check finds it. People are referenced in the hashed part by a random token, not by their account id, so erasing a closed account keeps the chain verifiable. The entry's short text summary and the plain account id are stored next to the hashed part, so the check does not cover them.
Pages
Journal
- Summary cards: changes in the last 7 days, unreviewed changes, protected objects.
- Filters: date range (24 hours, 7, 30 or 180 days, all time, custom), configuration type, author, project, source, review status, change type and a text search on object name. Filters are kept in the URL, so a filtered view can be bookmarked.
- Open an entry to see the diff, open the object, compare, or start a restore of the earlier version.
- Review: mark entries Reviewed or Flag with note (one at a time or several selected). The reviewer and time are recorded.
- Exports: Export CSV, Export JSON (the current filter) and Review report (CSV).
Objects & Compare
- One tab per configuration type; search with Name contains, filter with Changed (last 7, 30, 90 or 180 days) or Used by project. Only objects Config Undo has already captured are listed; during onboarding the list grows as types are captured.
- An object's page lists its versions (newest first) with source and time, the projects that use it, and a link to the object in Jira.
- Compare any two versions, or a version with Live Jira (reads it now). Diffs are specific to the type: grants as permission × holder, recipients per event, workflow statuses and transitions with their rules, screen tabs with ordered fields, options with order and enabled state, project details, role actors, components and versions.
- Restore this version starts a restore preview (only when restore is enabled for that type).
- Download any version as JSON, for example to re-create an object by hand.
Restore points
- Create restore point: label and configuration types.
- Open a restore point to see its objects, each marked Changed since, Created since, Deleted since or Unchanged, with Compare and Restore buttons. The toggle Only objects changed since the restore point hides the rest.
- Pin keeps a restore point beyond retention.
- Re-read everything now (restore points with up to 500 objects) re-reads every object in it from Jira.
- A weekly automatic restore point is created by the daily run on the chosen weekday (UTC), once onboarding has finished. The exact time can't be set, and a missed weekday is not made up the next day.
Restores
Tabs: Pending approval, In progress, History. A request shows its preview and write plan, reason, requester, approver, a timeline with ledger entry numbers and the verification result. Actions depend on the state: approve, reject (with an optional note), cancel, retry remaining steps, preview again.
Ledger
Entries newest first, with sequence number, time, type, request, object, before and after hash, verification result, actor, entry hash and previous hash. Verify integrity recomputes the chain and reports the first entry that doesn't verify, if any. A long ledger can't be checked within one request: the page then says how many entries verified so far, and the whole chain is then checked again in a background job, with the result shown in Coverage & Health. The chain head (latest entry number and hash) is shown so you can record it outside Jira. Export as CSV or JSON.
Coverage & Health
- Per configuration type: detection mode, objects and versions captured, last capture and last reconcile, last error. A type with an object Jira refused to show is marked Partly recorded.
- Onboarding progress with Pause onboarding / Resume onboarding.
- Import older history (after onboarding): imports audit-log records from before the current history start, as its own background job. Recording, the reconcile and weekly restore points keep running meanwhile.
- A note when Jira doesn't let the app read the audit log (for example on Jira Free).
- Audit-log poll status.
- Rate-limit budget: estimated points per hour for the last 24 hours.
- Ledger integrity status.
- Download diagnostics (JSON, no account ids, names or configuration content) for support.
Settings
| Setting | Default | Range / notes |
|---|---|---|
| Disable all restores (kill switch) | off | Blocks every write to Jira: no restore can be submitted, approved or retried, and the guided safe test can't start, restore or clean up. A running restore stops before its next write step; what it already wrote is verified and the request ends as Restored with differences (it is not rolled back). Recording and compare keep working. |
| Allow restores of … (one switch per restorable type) | all off | Turning one on shows what may change and is recorded in the ledger |
| Approval mode | Four-eyes | Single admin: the requester approves by typing the object name |
| Approval expires after (hours) | 24 hours | 1–72 hours; unapproved requests expire and change nothing |
| Keep versions and journal entries for (months) | 13 months | 3–36 months; reducing it needs a confirmation and shows an approximate count of the stored versions older than the new period (some of them are kept anyway; see Privacy and data) |
| Create an automatic restore point every week | on, Monday (UTC) | any weekday (Weekday (UTC)); created once onboarding has finished |
| Exclusions | none | objects (by key) or projects that are not recorded; existing history ages out with retention like any other, and each object's latest version is kept |
| Reconcile cadence | Automatic, based on site size | Weekly or Monthly |
| Record field schemes | on | experimental Jira API; history and compare only |
| Delete all app data | — | type DELETE ALL CONFIG UNDO DATA |
Every settings change is recorded in the ledger. While the licence is inactive, settings are read-only (exports and Delete all app data still work).
Exports
| Export | Where | Format | Contents |
|---|---|---|---|
| Journal | Journal → Export CSV / Export JSON | CSV, JSON | the current filter: time (UTC), type, object, change, author, source, summary, review status, reviewer, note |
| Review report | Journal → Review report (CSV) | CSV | the journal rows of the current filter with review status, reviewer and note, as change evidence |
| Ledger | Ledger | CSV, JSON | every entry with sequence, type, request, object, actor token and account id, before/after hash, verification result, previous and entry hash; the export also records the chain head |
| One version | object page | JSON | the normalised object, for manual re-entry or an offline archive |
CSV files are UTF-8 with a byte-order mark. Every cell that starts with =, +, -, @, a tab or a carriage return is prefixed with ', so spreadsheet programs don't run it as a formula. Display names are added to journal and review exports when you export; the ledger is exported exactly as stored.
Licensing
Trial and active licences: everything is available; during a trial a banner shows when it ends. Inactive licence: read-only. The journal, versions, compare (without recording new versions), existing restore points, the ledger, exports and Delete all app data stay available. Restores, previews, creating or re-reading restore points, journal reviews, settings changes, Import older history and the guided safe test are blocked, and background recording pauses. After the licence is active again, recording resumes by itself and the next hourly poll catches up on the audit log since the last poll.