Jira

Connect Jira from Settings > Integrations to let SubImage create and close remediation tickets in Jira.

What SubImage Does

SubImage creates Jira issues from issue routes and stores the created issue link on the SubImage issue. When the SubImage issue closes because the underlying evidence is no longer active, SubImage transitions the linked Jira issue to the route's done transition. The default done transition is Done.

SubImage searches Jira users only by an issue owner's email to set a best-effort assignee on tickets it creates. On close it may post a best-effort note on the linked issue. It does not search Jira issues, read arbitrary Jira tickets, upload attachments, or act on Jira issues it did not create and link.

Recommended Jira Setup

Use a dedicated Jira project for SubImage remediation tickets when possible. Authorize SubImage with a dedicated Jira user or group instead of an individual engineer's personal account.

Grant that user only the project permissions needed to create and close tickets:

• Browse Projects
• Create Issues
• Transition Issues
• Assign Issues (optional, only for automatic assignee)

Assign Issues is optional. SubImage sets a best-effort assignee after creating a ticket; without this permission the ticket is still created and closed, just left unassigned. Do not grant project administration, delete, edit, comment, or attachment permissions unless you intentionally want that account to have those abilities outside SubImage.

If you need a stricter write-only posture, configure a Jira issue security scheme with a default security level that does not include the integration user. Jira still requires Browse Projects to create an issue by project key, but issue security can hide created issues from that user after creation. This is not compatible with automatic closure, because Jira requires the integration user to be able to view and transition the linked issue.

Because Atlassian requires read:issue:jira for issue creation, the OAuth app has issue-read scope. Jira project permissions and issue security determine which issues the authorizing user can actually read, so keep that user scoped to the remediation project.

Consent Scopes

When you install Jira, SubImage requests these Jira API scopes:

• read:issue:jira
• read:issue.transition:jira
• read:status:jira
• read:field-configuration:jira
• read:user:jira
• write:issue:jira
• write:issue.property:jira
• write:comment:jira
• write:comment.property:jira
• write:attachment:jira
• offline_access

Atlassian requires the comment and attachment write scopes for the create issue REST endpoint's granular scope contract. On close, SubImage may post a best-effort note via the comment endpoint, but the Add Comments permission is not required because the comment failure is ignored. SubImage does not call the attachment endpoints. SubImage uses the transition scopes to list available transitions on the linked issue and apply the configured done transition.

SubImage uses read:user:jira only to look up the Atlassian account that matches a SubImage issue owner's email, so the created ticket can be assigned. It is optional: if you do not grant it, tickets are still created and closed, just unassigned. If you connected Jira before this scope existed, reinstall the integration to enable automatic assignee.

SubImage requests offline access so it can refresh the Jira connection without asking you to reinstall the integration.

SubImage Setup

1. Create or choose the Jira project that should receive remediation tickets.
2. Confirm the issue type you want SubImage to create. Task is the safest default.
3. Make sure that issue type does not require custom fields beyond project, issue type, summary, and description.
4. Install Jira from Settings > Integrations.
5. Create or update an issue route with destination jira, the Jira project key, issue type, and done transition name. Use Done unless your Jira workflow uses a different transition or destination status name.

Troubleshooting

If Jira says the token is unauthorized or the scope does not match, reinstall the Jira integration so Atlassian issues a fresh grant.

If Jira rejects the project key, confirm the authorizing Jira user has Browse Projects and Create Issues permissions on that project.

If Jira cannot close the linked issue, confirm the authorizing Jira user has Transition Issues permission and that the route's done transition name matches an available Jira transition or destination status from the issue's current workflow state.

If Jira rejects required fields, use an issue type with no required custom fields or relax the project's field configuration for the issue type SubImage creates.