Skip to main content

Attachment Reviewer for Jira - User Guide

Table of Contents​

  1. Introduction
  2. Getting Started
  3. Configuration Guide
  4. How Validation Works
  5. Understanding Validation Results
  6. Best Practices
  7. Troubleshooting
  8. FAQ

Introduction​

What is Attachment Reviewer?​

Attachment Reviewer for Jira is an automated security and compliance tool that validates every file uploaded to your Jira issues. It helps you:

  • Prevent security risks by blocking dangerous file types (executables, scripts, etc.)
  • Control storage costs by enforcing file size limits
  • Maintain compliance with corporate file policies
  • Keep projects organized by standardizing allowed file types

Key Benefits​

✅ Automatic Enforcement - No manual reviews needed ✅ Real-time Feedback - Users know immediately if files are blocked ✅ Project-Level Control - Each project can have different rules ✅ Secure by Default - Pre-configured to block risky file types ✅ User-Friendly - Clear explanations when files are blocked

Getting Started​

Installation​

  1. Visit the Atlassian Marketplace
  2. Search for "Attachment Reviewer for Jira"
  3. Click "Get it now"
  4. Select your Jira site
  5. Confirm installation
  6. Wait for installation to complete (usually 1-2 minutes)

First-Time Setup​

After installation, the app works immediately with secure default settings:

  • File Types: Whitelist mode with common business files allowed
  • File Size: 25MB maximum, 10MB warning threshold
  • Validation: Enabled for all projects

You can customize these settings per project (see Configuration Guide).

Accessing Settings​

For Project Administrators:

  1. Navigate to your Jira project
  2. Click Project Settings (gear icon in sidebar)
  3. Scroll down to find Attachment Reviewer in the sidebar
  4. Click to open the settings page

Required Permission: You must be a Project Administrator to access settings.

Configuration Guide​

Settings Overview​

The settings page has three main sections:

  1. File Type Rules - Control which file types are allowed
  2. File Size Rules - Set size limits for attachments
  3. Notification Settings - Configure validation feedback

File Type Rules​

Validation Mode​

Choose how file types are controlled:

Whitelist Mode (Recommended)

  • Only explicitly allowed file types can be uploaded
  • Most secure option
  • Default setting
  • Best for security-conscious organizations

Blacklist Mode

  • All file types allowed except explicitly blocked ones
  • More flexible but less secure
  • Use when you need to allow many different file types

Managing Allowed File Types​

  1. Click the Allowed Extensions dropdown
  2. Browse categories (Documents, Images, Archives, etc.)
  3. Select file types you want to allow
  4. Selected types appear as tags below the dropdown
  5. Click the X on any tag to remove it

Default Allowed Types:

  • Documents: pdf, doc, docx, txt, rtf, odt
  • Spreadsheets: xls, xlsx, csv, ods
  • Presentations: ppt, pptx, odp
  • Images: png, jpg, jpeg, gif, svg, webp, bmp
  • Archives: zip, rar, 7z, tar, gz
  • Data: json, xml, yaml, yml

Managing Blocked File Types​

  1. Click the Blocked Extensions dropdown
  2. Select file types you want to block
  3. Blocked types are always enforced, even in blacklist mode

Default Blocked Types (Security):

  • Executables: exe, msi, bat, cmd, com, scr, pif
  • Scripts: vbs, js, ps1, sh, bash, zsh
  • System Files: sys, dll, drv, ocx
  • Java: jar, war, ear
  • Mobile Apps: apk, ipa, app, deb, rpm, dmg
  • Macro Documents: docm, xlsm, pptm, dotm, xltm, potm
  • Risky Files: torrent, iso, img, vhd, vmdk
  • Databases: mdb, accdb, db, sqlite, sqlite3

Important: Blocked types always take precedence over allowed types.

File Size Rules​

Maximum File Size​

Set the absolute maximum file size allowed:

  • Range: 1 MB to 500 MB
  • Default: 25 MB
  • Recommendation: Set based on your storage capacity and typical file needs

Examples:

  • Small projects: 10-25 MB
  • Standard projects: 25-50 MB
  • Media-heavy projects: 50-100 MB
  • Special cases: Up to 500 MB

Warning Threshold​

Set a size that triggers a warning (but doesn't block):

  • Range: 1 MB to maximum size
  • Default: 10 MB
  • Purpose: Alert users about large files without blocking them

Use Case: Warn users when files are larger than typical, encouraging them to consider if the file size is necessary.

Notification Settings​

Comment on Success​

Default: Disabled

When enabled, posts a comment even when validation passes. Most users prefer to only see comments when there are issues.

Enable if:

  • You want audit trails of all uploads
  • You need proof of validation for compliance
  • Your team wants confirmation of successful uploads

Disable if:

  • You want to reduce comment noise
  • You only care about failures and warnings

Saving Settings​

  1. Review all your configuration changes
  2. Click Save Settings button at the bottom
  3. Wait for confirmation message
  4. Settings are now active for this project

Note: Settings are saved per project. Other projects are not affected.

Resetting to Defaults​

If you want to start over:

  1. Click Reset to Defaults button
  2. Confirm the action
  3. All settings return to secure defaults
  4. Click Save Settings to apply

How Validation Works​

Validation Process​

When a user uploads an attachment to an issue:

  1. Upload Initiated - User attaches file to issue
  2. Automatic Validation - App checks file against project rules
  3. Decision Made - File passes, warns, or fails validation
  4. Action Taken - File kept or removed based on result
  5. Feedback Posted - Comment added to issue with details

Validation Checks​

The app performs these checks in order:

1. File Type Check (if enabled)​

Blocked List Check:

  • Is the file extension in the blocked list?
  • If YES → FAIL (file removed)
  • If NO → Continue to next check

Whitelist Mode Check:

  • Is the file extension in the allowed list?
  • If NO → FAIL (file removed)
  • If YES → Continue to next check

Blacklist Mode:

  • If not blocked, file type passes

2. File Size Check (if enabled)​

Maximum Size Check:

  • Is file larger than maximum size?
  • If YES → FAIL (file removed)
  • If NO → Continue to next check

Warning Threshold Check:

  • Is file larger than warning threshold?
  • If YES → WARN (file kept, warning posted)
  • If NO → PASS

What Happens to Failed Files​

When a file fails validation:

  1. File is Removed - Attachment is automatically deleted
  2. Comment Posted - Validation report added to issue
  3. User Notified - User sees comment explaining why
  4. No Manual Action - Everything happens automatically

Validation Results​

Three possible outcomes:

✅ Passed

  • File meets all requirements
  • File is kept on the issue
  • Comment posted only if "Comment on Success" is enabled

⚠️ Passed with Warnings

  • File meets minimum requirements but has warnings
  • File is kept on the issue
  • Comment posted explaining warnings

❌ Failed

  • File violates one or more rules
  • File is automatically removed
  • Comment posted explaining why (with "been removed" notice)

Understanding Validation Results​

Validation Comment Format​

When validation occurs, a comment is posted with this information:

### Attachment Validation Report

File Name: example.exe
File Type: application/x-msdownload
File Size: 5.23 MB
Validation Result: ❌ Failed (been removed)

Status Indicators​

✅ Passed

  • All validation checks passed
  • No issues found
  • File is safe to use

⚠️ Passed with Warnings

  • File passed but has concerns
  • Example: File size exceeds warning threshold
  • File is kept but review recommended

❌ Failed

  • File violated one or more rules
  • File has been removed automatically
  • User must upload a compliant file

Common Failure Reasons​

"File type '.exe' is blocked for security reasons"

  • The file extension is in the blocked list
  • Solution: Don't upload executable files

"File type '.xyz' is not in the allowed list"

  • Project uses whitelist mode
  • File type not in allowed list
  • Solution: Ask admin to add the file type or use an allowed format

"File size 30.5MB exceeds maximum allowed size of 25MB"

  • File is too large
  • Solution: Compress the file or split into smaller files

Warning Messages​

"File size 15.2MB exceeds recommended size of 10MB"

  • File is larger than recommended but still allowed
  • Consider if file size is necessary
  • File is kept on the issue

Best Practices​

For Administrators​

Security Best Practices:

  1. Use Whitelist Mode - More secure than blacklist mode
  2. Keep Blocked List Updated - Add new risky file types as needed
  3. Review Defaults - The default blocked list is comprehensive
  4. Set Reasonable Size Limits - Balance security and usability
  5. Document Your Policies - Let users know what's allowed

Configuration Tips:

  1. Start with Defaults - They're secure and well-tested
  2. Customize Gradually - Add file types as needed
  3. Test Changes - Upload test files after changing settings
  4. Monitor Comments - Watch for validation failures
  5. Adjust Based on Usage - Refine rules based on team needs

Project-Specific Settings:

  • Development Projects: May need code files (js, py, java)
  • Design Projects: May need larger image files
  • Documentation Projects: Focus on documents and PDFs
  • General Projects: Use default settings

For Users​

Uploading Files:

  1. Check File Type - Ensure your file type is allowed
  2. Check File Size - Keep files under the limit
  3. Read Validation Comments - They explain what went wrong
  4. Ask Admin if Needed - Request new file types if necessary
  5. Use Appropriate Formats - Choose common, safe file types

If Your File is Blocked:

  1. Read the Comment - Understand why it was blocked
  2. Check File Type - Is it a risky type (exe, bat, etc.)?
  3. Check File Size - Is it too large?
  4. Convert if Possible - Use an allowed format
  5. Contact Admin - If you need an exception

Recommended File Formats:

  • Documents: PDF (best), DOCX, TXT
  • Spreadsheets: XLSX, CSV
  • Images: PNG, JPG (compressed)
  • Archives: ZIP (most compatible)
  • Data: JSON, CSV, XML

Troubleshooting​

Common Issues​

Issue: Settings page won't load​

Possible Causes:

  • Not a project administrator
  • App not installed properly
  • Browser cache issues

Solutions:

  1. Verify you have Project Admin permissions
  2. Refresh the page (Ctrl+F5 or Cmd+Shift+R)
  3. Clear browser cache
  4. Try a different browser
  5. Contact your Jira administrator

Issue: Settings won't save​

Possible Causes:

  • Invalid configuration
  • Network issues
  • Permission problems

Solutions:

  1. Check for error messages on the page
  2. Ensure file size values are valid (1-500 MB)
  3. Ensure warning size is less than maximum size
  4. Check your internet connection
  5. Try again in a few minutes

Issue: Files are being blocked unexpectedly​

Possible Causes:

  • File type not in allowed list (whitelist mode)
  • File type in blocked list
  • File size too large
  • Settings recently changed

Solutions:

  1. Check the validation comment for specific reason
  2. Review project settings
  3. Verify file extension is in allowed list
  4. Check file size against limits
  5. Contact project administrator

Issue: Validation comments not appearing​

Possible Causes:

  • Validation passed with no warnings
  • "Comment on Success" is disabled
  • App permissions issue

Solutions:

  1. Check if file actually failed validation
  2. Enable "Comment on Success" if you want all validations logged
  3. Verify app has permission to post comments
  4. Check Jira activity log

Issue: Wrong files are being allowed​

Possible Causes:

  • Blacklist mode is active
  • File type not in blocked list
  • Validation disabled

Solutions:

  1. Switch to whitelist mode for better security
  2. Add problematic file types to blocked list
  3. Verify validation is enabled
  4. Check settings were saved properly

Getting Help​

Before Contacting Support:

  1. Check this user guide
  2. Review the FAQ section
  3. Verify your permissions
  4. Try the troubleshooting steps above
  5. Check the validation comments for clues

When Contacting Support:

Include this information:

  • Your Jira site URL
  • Project key
  • File that was blocked (name and extension)
  • Validation comment text
  • Screenshots of settings page
  • What you expected to happen
  • What actually happened

Support Channels:

FAQ​

General Questions​

Q: Does this work with Jira Cloud? A: Yes, this app is built specifically for Jira Cloud using Atlassian Forge.

Q: Does this work with Jira Server/Data Center? A: No, this app is only for Jira Cloud. Forge apps don't support Server/Data Center.

Q: Is this app free? A: Check the Atlassian Marketplace listing for current pricing information.

Q: Can I try it before buying? A: Yes, most Forge apps offer a free trial period. Check the Marketplace listing.

Configuration Questions​

Q: Can different projects have different rules? A: Yes! Each project has completely independent settings.

Q: Can I have different rules for different issue types? A: Not currently. Rules apply to all issues in a project.

Q: What's the difference between whitelist and blacklist mode? A:

  • Whitelist: Only allowed types can be uploaded (more secure)
  • Blacklist: Everything allowed except blocked types (more flexible)

Q: Can I add custom file extensions? A: Yes, you can add any file extension to the allowed or blocked lists.

Q: How many file types can I allow? A: No limit. You can select as many as needed.

Q: Can I import/export settings between projects? A: Not currently. This feature is planned for a future release.

Validation Questions​

Q: What happens to files that fail validation? A: They are automatically removed from the issue and a comment explains why.

Q: Can users override the validation? A: No. Validation is enforced automatically to maintain security.

Q: Does this affect existing attachments? A: No. Only new uploads are validated. Use the Scan Report feature (coming soon) to audit existing files.

Q: How fast is validation? A: Very fast. Validation happens in milliseconds and doesn't slow down uploads.

Q: Can I see a history of blocked files? A: Yes, check the issue comments. Each validation creates a comment.

Q: What if I need to upload a blocked file type? A: Contact your project administrator to request the file type be added to the allowed list.

Security Questions​

Q: Is my data secure? A: Yes. The app runs on Atlassian's secure Forge platform. No data leaves Atlassian's infrastructure.

Q: Does the app read file contents? A: No. Only metadata (filename, size, MIME type) is checked. File contents are not accessed.

Q: What file types are blocked by default? A: Executables, scripts, system files, mobile apps, macro-enabled documents, and other risky types.

Q: Can malware get through? A: The app blocks known risky file types but doesn't scan for viruses. Use additional security tools for virus scanning.

Q: Is this GDPR compliant? A: Yes. No personal data is collected or stored by the app.

Technical Questions​

Q: What permissions does the app need? A:

  • read:jira-work - Read issue and attachment information
  • write:jira-work - Post comments and remove non-compliant files
  • manage:jira-project - Access project settings

Q: Does this work with the Jira mobile app? A: Yes. Validation works regardless of how files are uploaded.

Q: Can I use this with automation rules? A: Yes. The app works alongside Jira automation.

Q: Does this integrate with other apps? A: The app works independently but doesn't conflict with other apps.

Q: How do I uninstall the app? A: Go to Manage Apps in Jira settings and uninstall like any other app.

Future Features​

Q: Will there be a scan report feature? A: Yes! Attachment scanning and audit reports are planned for a future release.

Q: Can you add content-based validation? A: This is being considered for future releases.

Q: Will you support custom validation rules? A: Advanced validation rules are planned for future releases.

Q: Can I get email notifications? A: Not currently, but this may be added in the future.

Appendix​

Default File Extensions by Category​

Documents:

  • pdf, doc, docx, txt, rtf, odt, pages

Spreadsheets:

  • xls, xlsx, csv, ods, numbers

Presentations:

  • ppt, pptx, odp, key

Images:

  • png, jpg, jpeg, gif, bmp, svg, tiff, webp, ico

Audio:

  • mp3, wav, flac, aac, ogg, m4a

Video:

  • mp4, avi, mov, wmv, flv, webm, mkv

Archives:

  • zip, rar, 7z, tar, gz, bz2, xz

Code:

  • js, ts, py, java, cpp, c, cs, php, rb, go, rs, swift, kt, html, css, scss, json, xml, yaml, yml, sql

Blocked (Security):

  • exe, msi, bat, cmd, com, scr, pif, vbs, ps1, sh, bash, zsh, sys, dll, drv, ocx, jar, war, ear, apk, ipa, app, deb, rpm, dmg, docm, xlsm, pptm, dotm, xltm, potm, torrent, iso, img, vhd, vmdk, mdb, accdb, db, sqlite, sqlite3

File Size Reference​

  • 1 MB = 1,024 KB = 1,048,576 bytes
  • 10 MB = Typical high-resolution photo
  • 25 MB = Default maximum (about 10 high-res photos)
  • 50 MB = Short video clip
  • 100 MB = Longer video or large dataset
  • 500 MB = Maximum allowed (very large files)

Glossary​

Attachment - A file uploaded to a Jira issue

Validation - The process of checking if a file meets project rules

Whitelist - A list of explicitly allowed items (more secure)

Blacklist - A list of explicitly blocked items (more flexible)

File Extension - The suffix after the dot in a filename (e.g., .pdf, .jpg)

MIME Type - Technical identifier for file type (e.g., application/pdf)

Forge - Atlassian's cloud app development platform

Project Properties - Jira's native storage for project-specific data

Last Updated: February 2026 Version: 1.0.0

For the latest updates and information, visit the Atlassian Marketplace.