Overview of Attachment Housekeeper
What does the Attachment Housekeeper do?
Large or long-running Jira instances tend to have many attachments which are left unused, as they belong to older projects and/or issues. It is hard to navigate through all these issues, and no one is willing to delete them either.
The Attachment Housekeeper allows Jira and project admins to perform housekeeping of attachments without deletion of issues. This is done by defining and associating attachment housekeeping policies to your projects, which will mark attachments for deletion after a certain period of time. This helps Jira and project admins manage attachments within Jira / projects with a customisable set of criteria based on your company’s data policies.
Accessing the Attachment Housekeeper
If you are a project admin looking to use Attachment Housekeeper, refer to Attachment Housekeeper for Project Admins
Login as a Jira administrator
Go to Administrator > Issue Archiver
You will see the menu on the left sidebar
The Attachment Housekeeper has the following pages:
Housekeeping Policies - Get an overview of all policies available in the Jira instance
Policy Runs - View the status and history of policy executions in the Jira instance
Marked Attachments - View all currently marked attachments in the Jira instance
Projects & Policies - View which policies are currently used by which projects
Housekeeper Settings - Modify any settings for Attachment Housekeeper
Attachment Housekeeper Policies
A housekeeping policy:
is a set of rules for determining if a Jira attachment can be deleted from the Jira issue.
Each rule is made up of multiple criteria which an attachment is checked against.
Each rule also defines a retention period to keep attachments in Jira before they are permanently deleted.
is associated with Jira projects to run on.
Rule Criteria
You can use the following different criteria to decide whether an attachment should be marked:
The issue it belongs to (via JQL)
Its file size
Its file extension
Whether the file was mentioned in the description or any comment in the issue
When a policy is run, it goes through each of its rules.
For each rule, it gets a list of issues based on the rule’s JQL (if any).
For each issue found, it looks at the list of attachments in each issue.
For each attachment, it is checked against ALL criteria in the rule. If the attachment matches all criteria in the rule, it is marked for deletion.
To learn how to create a policy, see our page on Managing Attachment Housekeeper Policies
Marked Attachments
The attachments marked for deletion by Attachment Housekeeper can be viewed in the Marked Attachments page. These attachments are soft deleted, so users will be unable to download or access them, but will be permanently deleted after the retention period. This means you can still recover these attachments if they have been mistakenly marked for deletion as long as they are recovered within the retention period.
If an issue contains attachments that have been marked, a Marked Attachments panel will appear in the issue to provide an audit trail of the attachments processed by the Attachment Housekeeper. It includes metadata such as:
File name
File size
The user who uploaded the file
Date uploaded
When it is retained until, or whether it is already deleted
the policy that marked the attachment for deletion
