Configuring file attachments

Here you can learn about the available attachment and avatar storage methods in Jira and how to configure each of those, depending on what’s suitable for you.

For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.

Attachment storage methods

Storing attachments in the local file system

Jira stores user avatars and attachments, such as files and images, in the home directory in the data sub-directory. Learn more about Jira’s directories and files

When file attachments are enabled, users can attach files and screenshots to Jira issues. This requires space on the server, so you can modify how Jira handles attachments or disable this feature if needed.

Because attachments aren’t stored in Jira's database, you need to back up them separately. Learn more about backing up data

Storing attachments in Amazon S3

You can also store your attachment data in Amazon S3. We recommend this method if your team has large or increasing data needs and requires the ability to scale efficiently.

To use Amazon S3 object storage, you should plan to provision Jira to AWS or already run Jira in AWS. This feature isn't supported for on-premise deployments or for any customers not running Jira in AWS.

Learn how to configure Amazon S3

Configuring attachment permissions

To let users attach files to issues, you need to set up the following permissions:

  • All appropriate users, groups, or project roles must have the Create attachments permission for the relevant projects. Learn more about attachment permissions

  • To delete their own attached files from issues, users, groups, or project roles must have the Delete own attachments permission in the relevant projects.

  • To allow users to attach files when creating a new issue, ensure that the Attachment field is not hidden within the field configurations associated with the specific issue types. Learn more about field configurations

 Configure the create and delete attachment permissions

You can modify Jira attachment permissions in the Jira Administration menu:

  1. In the upper-right corner of the screen, select Administration  > Issues

  2. In the sidebar, select Permission schemes to view a list of all permission schemes in your Jira system and the projects that use each scheme. Learn more about permissions schemes

  3. For each relevant permission scheme:

    1. Select the Permissions link associated with the relevant permission scheme to edit that scheme's permissions.

    2. On the Edit permissions page, in the Permission section, select Create attachments.

    3. In the Grant permission dialog that opens:

      1. In the Granted to section, select the relevant users, groups, or roles.

      2. Select Grant.

To allow these users, groups of users, or project role members to delete their own attachments, don’t forget to assign them the Delete own attachments permission too.

Configuring attachment settings

  1. In the upper-right corner of the screen, select Administration System

  2. In the sidebar, select Advanced > Attachments to check whether attachments are on or off. You'll find the global attachment configurations under General settings.
    Attachments settings

  3. Select the Edit settings button, which opens the Edit attachment settings dialog box:

  4. Enable attachments: select ON to enable attachments. Consider that if you haven’t logged in as a user with the Jira system administrator global permission, this option won’t be available to you.

    If you see the Use custom directory option in attachment settings, it means that you store attachments in a custom path. This is an outdated functionality that’s no longer configurable in Jira. Select OFF to disable the custom path and use the Jira home directory for storing attachments.

    Edit attachment settings

  5. Attachment size: specify the maximum attachment size. The default size per file is 10485760 bytes (10 MB). The maximum attachment size per file is 2147483647 bytes (2 GB).
  6. Enable thumbnails (optional): ensure that ON is selected if you wish to display image file attachments as thumbnails (or miniature previews) when viewing an issue. When this setting is enabled, Jira automatically creates thumbnails of the following types of image attachments:
    - GIF
    - JPEG
    - PNG
    Check out the following sections for more detail: How to generate thumbnail images on Linux, Learn how to display image thumbnails
  7. Enable ZIP Support (optional): ensure that ON is selected if you wish to view the contents of zip files attached to an issue and allow all files attached to an issue to be downloaded as a single ZIP file.
  8. Select Save to save Jira's attachment settings. Make sure that the appropriate users, groups, or project roles have all the needed permissions to attach and delete attached files.

If the permission schemes used by your projects already have the Create attachments and Delete own attachments permission or your projects use Jira's built-in Default permission scheme, no further steps are needed.

However, if you need to configure these permissions, check out this section: Configure create and delete attachment permissions.

Restrict unwanted file extensions for better security

Starting from Jira 9.15, you can create an allowlist or a blocklist of file formats that users can upload through issues. This will help you protect your instance from potential malware that might get into the system through issue attachments.

You’ll find the configuration for restricting unwanted file extensions under Security settings on the Attachments page. To configure file formats that you’d like to allow or block in your instance:

  1. Select Edit settings to open the Edit attachment settings dialog.

  2. For Restrict file extensions, select Blocklist or Allowlist. If you’d like to allow all file extensions for uploading, select Off.

    1. The blocklist will contain file extensions blocked from uploading. All other file extensions will be allowed.

    2. The allowlist will contain file extensions allowed for uploading. All other file formats will be blocked.

  3. In the Specify file extensions field, enter file formats that you’d like to block or allow, based on the previous setting. Separate your file formats with a comma. For example: exe, dll, pdf.

  4. If needed, select Include files without extensions. Files without any extension will be either blocked or allowed, based on the previous setting.

  5. Select Save.

Your configuration will apply only to new files uploaded after you’ve set it. The files attached before you’ve set the configuration won’t be checked for their extensions.

If a user tries to attach a blocked file extension to an issue, the error message will display under this attachment, notifying that the file extension isn’t allowed. Check how this will lool like on the following screenshot.

Blocked file extensions in issue

How to display image thumbnails

You can configure the issue navigator column layout to display the thumbnails in the Images column. Learn more about configuring the default issue navigator

All thumbnail images are stored in PNG format in the attachments directory, together with the original attachments. The thumbnail images are denoted by '_thumb_' in their file names.

To generate thumbnail images on Linux:

  • Your system must support Linux X11 libraries. Check out the minimum set of libraries needed to use JDK 1.4.2 under RedHat Linux 9.0: Linux X11 Libraries for Headless Mode

  • The following Java system property must be set: -Djava.awt.headless=true

Advanced attachment configurations

If you’d like to change how Jira handles attachments, you can set up these advanced configurations:

  • Thumbnail size

  • ZIP-format file accessibility

  • The number of files shown in the content of ZIP-format files on issues

While the first one can be modified as an advanced setting in the Jira administration menu, the remaining two are implemented by defining properties in your file. Learn more about Jira advanced settings

Configuring thumbnail size

By default, thumbnails are 200 pixels wide and 200 pixels high. To change the dimensions of thumbnail images:

  1. Stop Jira.
  2. Edit the file in your Jira home directoryCheck how to make changes to the file 
  3. Edit the values of the following properties:
    • jira.thumbnail.maxwidth — thumbnail width in pixels
    • jira.thumbnail.maxheight — thumbnail height in pixels

      If neither of these properties exists in your file, add them to the file. For example, specify the following for a thumbnails that are 100 pixels wide:

      jira.thumbnail.maxwidth = 100
  4. Delete all existing thumbnail images within the attachments directory. These images contain '_thumb_' in the filename.
  5. Restart Jira.

After restarting Jira, all thumbnails will be recreated automatically using the new dimensions.

Configuring ZIP-format file accessibility

By default, Jira allows you to access common ZIP-format files, with file extensions like '.zip' and '.jar' (Java archive files).

However, there are numerous other ZIP-format files that Jira doesn’t allow to access by default. You can grant access to these files by doing the following:

  1. Stop Jira.
  2. Edit the file in your Jira home directory. Check how to make changes to the file 
  3. Remove the extensions from the property of the file types whose contents you wish to access in Jira.

    tip/resting Created with Sketch.

    If this property doesn't exist in your file, add the name of this property, followed '=', followed by the content of the <default-value/> element copied from your Jira installation's jpm.xml file. Then, begin removing the extensions of file types whose contents you wish to access in Jira.

  4. Restart Jira.

Configuring the number of files shown in the content of ZIP-format files on issues

By default, Jira shows a maximum of 30 files in the content of ZIP-format files attached to an issue. To change this maximum value:

  1. Open the Advanced settings page. Learn more about Advanced Jira application configuration
  2. Edit the value of the property by clicking the existing value and specifying the maximum number of attachments you want to show on an issue.
  3. Select Update to save the new value in the Jira database.

Last modified on Mar 21, 2024

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.