Retention Policy for Jira — Documentation

Last updated: 14 August 2026.

Retention Policy lets Jira admins define JQL-based retention rules that archive stale issues automatically on a daily or weekly schedule, with a live preview before anything changes and a full audit log of every run.

Requirements

• Jira Cloud.
• For archiving itself, one of two paths must be available: Jira's native issue archiving (available on Premium and Enterprise plans), or an “Archived” workflow transition in the projects you target. The app tries native archiving first and falls back to the transition automatically.
• The permissions of whoever runs a rule manually apply to that run, so that account needs permission to edit or transition the issues in scope.

Installation

Install the app from the Atlassian Marketplace, or from inside Jira via Settings → Apps → Manage apps, then search for “Retention Policy” and choose Get app. Installation requires Jira site-admin rights and grants the app the scopes listed on its Marketplace page.

Where to find it

The app adds one full-page screen, reachable from the Apps menu in the Jira top navigation → Retention Policy. Everything — rules, preview, manual runs and the audit log — lives on that single screen.

Using Retention Policy

1. Create a rule. Give it a name, enter a JQL filter (for example resolutiondate <= -180d AND statusCategory = Done) and pick a schedule: Daily or Weekly.
2. Preview it. Press Preview to see how many issues currently match, plus a sample of up to 25 of them. Nothing is changed by a preview. An invalid JQL query surfaces Jira's own error message here.
3. Save. A new rule is scheduled one full interval into the future, so saving never triggers an immediate mass archive.
4. Run now (optional). Use Run now on a rule to archive its matches immediately. The run executes with your own Jira permissions.
5. Let the schedule work. A scheduled trigger fires once a day and processes every rule whose next-run time has passed; daily rules then advance by one day, weekly rules by seven. This is fully automatic — no cron setup on your side. If a rule fails, its next-run time is left untouched so it retries on the following daily fire.
6. Check the audit log. The table at the bottom of the screen shows each run: rule name, JQL, manual or scheduled, issues matched and archived, the method used (native archive or workflow transition), the timestamp and any per-issue errors.

Limitations

• A single run archives at most 100 issues as a safety cap; the rest are picked up on the next run, and the preview tells you when a backlog exceeds the cap.
• Only daily and weekly schedules are supported, and the exact time of day is decided by Forge's scheduled trigger — you cannot pin a run to a specific hour. Schedule maths is done in UTC.
• The audit log keeps the 100 most recent runs; older entries are dropped.
• The fallback path needs a transition whose name, or whose target status, contains “archive”. Issues in projects without one are reported as errors in the audit log rather than archived.
• The app has no un-archive or restore function; reversing an archive is done in Jira itself.
• Rules are stored per Jira site and are visible to everyone who opens the app screen, but only a Jira administrator can create, edit, delete or run them — that is checked against Jira before anything is written. Scheduled runs execute as the app; manual runs execute as the person clicking, so their own Jira permissions bound what is archived.

Support

Questions, bug reports or feature requests: info@kyc-checks.nl