Managing attachment growth in Jira and Confluence

Background

Jira provides a number of ways to store information about the work within a project, including custom fields, workflows, and issue types. Another capability that Jira provides is file attachments. This is often used to provide more context about a particular issue or to include files from different systems (Photoshop, application logs, etc.)

Negative effects of attachment overuse

Since Jira and Confluence allow the attachment of any file type by default, there is a risk of the overuse of attachments, which may have negative effects on instance health.

For example, if a Jira ticket contains multiple file uploads for different versions of the same file, you can’t take advantage of file versioning features that exist in tools like Google Drive. This causes the Jira issue to be difficult to manage. It can also, in some cases, lead to performance degradation of an instance, increasing the amount of time it takes to load issues with lots of attachments on them.

Some of these same issues affect Confluence as well, and it can make migrations more complex and more time consuming.

Best practice: use linking and integrations to manage files

The best way to approach attachments in Jira is to integrate systems that store files or to use links to those systems, rather than directly uploading attachments. For example, instead of attaching a PowerPoint document, put a link to where the file lives in Office 365 into the Jira ticket. Let Jira be the source of truth for the work item rather than a storage system for sharing files.

Here's another example of when you should link rather than upload a file directly to a Jira ticket. Let’s say you have an SRE team that uses Splunk to ingest logs. They receive an alert about an incident in production. It’s easier and more effective for the SRE to add a comment on the incident ticket in Jira with a link pointing to the Splunk dashboard that displays the log files, rather than downloading the logs from Splunk or taking a screenshot of the dashboard and uploading the files to the Jira ticket.

However, there are plenty of scenarios where it makes sense to directly upload a file to Jira. For example, you may need to upload logs to a ticket for an application that is behind a firewall. In this case, you need to download and export the files off that system anyway. You also won’t be making revisions to the log files so versioning isn’t a concern. Once they’re uploaded to the Jira ticket, the information won’t change and the developer looking at the ticket will have the necessary information to troubleshoot.

Another example is uploading a screenshot to a Jira ticket. You will likely use native screenshot tools or something like Skitch to grab a quick screenshot. Rather than uploading that file to a file storage system and then linking that to Jira, it’s much easier to upload the file directly to the Jira ticket.

With the recommended "linking" approach, the volume of attachments will naturally be more manageable as they will be uploaded more sparingly. Attachments would only be used when there’s not an easy way to link to the file or when the file is created specifically for the Jira issue.

If this is not already an accepted practice, there are various integrations and application settings you can use to make it easier for users to link files and to enforce the size of files that get uploaded. We’ll explore some of those options below.

What about Confluence?

So far we’ve walked through Jira considerations and use cases, but what about Confluence?

While Confluence does offer a few more capabilities around document storage and versioning, it was not built from the ground up as a document management system. There are many use cases for leveraging Confluence attachments, but a lot of considerations still apply — too many attachments can bog down your instance.

When applicable, you can easily link to documents managed on other document management tools, and there are many different integration options that can serve both Jira and Confluence alike. The next section covers how to manage attachment growth, which includes suggestions around monitoring growth trends, how to limit attachment size, and Marketplace apps that can enhance your integration with a dedicated document management system.