- Overview
- Getting started
- User guide
- Restore guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
Getting started
This page takes you from installation to your first verified restore. Allow about 15 minutes, most of it reading.
1. Install
Install Config Undo for Jira from the Atlassian Marketplace (a Jira site administrator approves the app's permissions; see Permissions and security). Then open Jira settings → Apps → Config Undo.
Only people with the Administer Jira global permission can open the app. The app checks this on the server for every request, not only in the menu.
2. The first hour: recording starts by itself
You don't have to start anything. About two minutes after installation Config Undo begins its onboarding (Jira needs a short while before the app's access works). The status chip at the top of every page shows Onboarding N %; Coverage & Health shows the details per configuration type.
Onboarding runs in this order:
- Access and size check of the site (small, medium or large; see Large sites).
- Your audit log of the last 30 days, turned into journal entries, newest first. The journal starts filling within minutes with the most recent changes; on busy sites with thousands of audit records the rest of the 30 days follows in the next hours.
- A first version of every permission scheme, workflow and workflow scheme.
- Workflow history of up to 60 days, which gives full previous versions of workflows.
- A first version of everything else: notification schemes, screens, field options, project settings and field schemes.
- The rest of the audit log, from 30 up to 180 days back (as far as your site's audit log retention goes).
The progress shown is a rough stage marker: 2 % after the size check, 5 % while the 30-day history is imported, 20 % for the first versions of the priority types, 45 % for workflow history, 60 % for everything else and 90 % for the older audit history.
Onboarding spends only a fixed hourly budget of Jira's rate limit for apps; approved restores are never held back by these budgets. Our planning estimates for the full history are a few hours for a small site, about half a day to a day for a medium site and several days for a large site. You can use the app the whole time; see Large sites.
On busy sites the first hour doesn't cover everything. In the first hour after installation all background work shares a budget of 6,000 estimated points. On a site with thousands of audit records this may not be enough for the whole 30 days of audit history, and not for the first versions of permission schemes, workflows and workflow schemes; these follow in the next hours under the hourly onboarding budget. Until Config Undo has captured an object, a change to it shows up in the journal from the audit log, but it can't be undone: an audit-log entry holds no complete earlier version. Once an object is listed in Objects & Compare, Compare with live stores its current state at once. Compare with live is not held back by the onboarding budget; it counts toward the hourly cap for comparisons and previews (Large sites).
Onboarding looks after itself:
- If Jira refuses to show the app one object (for example a project behind a data security policy), that object is skipped and its type is marked Partly recorded in Coverage & Health; the rest continues.
- If Jira doesn't let the app read the audit log at all (for example on Jira Free), steps 2 and 6 bring no history and Coverage & Health says so. Changes are then recorded without their author.
- If onboarding stops making progress, the hourly poll notices and restarts it.
After onboarding you can import audit history older than 180 days with Coverage & Health → Import older history, as far as your audit log still has it. The import runs as its own background job.
A welcome panel explains three things: what is recorded, that restore is off until you turn it on, and that your data stays in Atlassian. Got it only hides the panel.
3. Work through "Get set up"
The Journal shows a Get set up card with five steps.
Review the last 30 days of changes
Show them filters the journal to the last 30 days. Each row shows time, configuration type, object, change and author. Open a row to see the diff (when both versions are captured) and to mark it Reviewed or Flag it with a note.
Entries labelled Backfill (audit log) come from Jira's audit log. They show the values the audit log recorded, but they hold no complete earlier version, so they can't be restored. Entries from Backfill (workflow history) are complete workflow versions.
Run the guided safe test restore
In the Get set up card choose Start the test next to "Run the guided safe test restore". It shows the whole cycle on an object nobody uses:
- Create test scheme: Config Undo creates a permission scheme named "Config Undo test" with today's date and time (UTC). No project uses it. If a test scheme from an earlier, finished or failed test is still there, Config Undo deletes it first.
- Change it in Jira: open the scheme in Jira (the test page has an Open "Config Undo test …" in Jira button), change something (for example remove a grant), save, come back and click I changed it. Config Undo re-reads the scheme right away and shows the diff.
- Restore and verify: choose Restore the test scheme. Because this is the app's own test object, you approve the restore yourself, even in four-eyes mode and with restore turned off for permission schemes. Config Undo writes the original back, re-reads it and shows Restored and verified.
- Clean up: choose Delete the test scheme. Config Undo deletes the test scheme from Jira. The test stays in the journal and in the ledger (type
TEST_RESTORE) as evidence.
The self-approval in step 3 works only for the test scheme the current test created, and the server checks this on every step. Everything else still applies: the kill switch blocks the test (starting, restoring and cleaning up), the licence must be active, and if someone added the test scheme to a project in the meantime, the test refuses to restore it.
In our own test on a Jira Cloud site the four steps took 20 seconds of app time.
Create your first restore point
Restore points → Create restore point, give it a label ("Before Q4 cleanup") and choose the configuration types (default: all). If only a few changes are waiting since the last hourly poll (up to 15 objects), Config Undo captures them first; otherwise the restore point records how fresh each type is. It then stores which version of every object was current. Later, the restore point shows what changed since, with links to compare or restore each object. Restore points older than the retention period (13 months by default) are removed unless you pin them. See User guide.
Enable restore for at least one family
A family is a configuration type. Settings → Restore → Allow restores of permission schemes (a good first choice). A dialog lists exactly what Config Undo may change for that type; confirm with Allow restores. The change is recorded in the ledger. Turning restore on changes nothing in Jira by itself.
Invite a second admin as approver
Four-eyes approval is the default: the admin who requests a restore can't approve it. Ask another Jira admin to open Config Undo → Restores and approve a request. If your site has only one Jira admin, switch Settings → Approval → Single admin: the requester then approves by typing the object's exact name.
4. Your first real restore
- Find the object: Objects & Compare, or a journal entry.
- Pick the version you want back and choose Restore this version.
- Read the preview: what will change, which projects use the object, warnings, and the write plan. If something blocks the restore, the preview says why. Otherwise choose Continue.
- Enter a reason and Submit request.
- The approver opens the request in Restores → Pending approval, reviews it and chooses Approve and restore '<object name>'. Config Undo re-reads the live object first; if it changed since the preview, the request becomes stale and must be previewed again. Each request takes exactly one decision: if another admin rejects it (or the requester cancels it) while the approval is running, the rejection wins and nothing is written.
- Config Undo writes the change, re-reads Jira and shows the result: Restored and verified, Restored and verified, with notes, Restored with differences or The restore failed.
Everything about this flow, including how to undo a restore, is in the Restore guide.
5. A weekly routine that takes five minutes
- Journal → filter Last 7 days and Review status: Unreviewed → mark reviewed or flag with a note.
- Before a planned change (cleanup, migration, workflow consolidation) create a restore point, and pin it if you need it longer than the retention period. A weekly automatic restore point is on by default (Monday, UTC, once onboarding has finished).
- For audits: Review report (CSV) from the journal and the ledger export (CSV or JSON).