A change can't move to Done until the test evidence and the rollback plan are on it. A bug can't be raised without a screenshot. A request can't be closed until the signed approval is attached. Some version of this has been asked on this Community since 2017 and keeps coming back, usually under the title "attachment validator" — and the answers split between "you'll need an app" and a built-in rule that half the people who try it report as broken.
Both camps are partly right. This is the map as of October 2026: what the built-in validator really checks, the one setting that makes it look broken, where it is the complete answer, and how to get the rule most of these threads are actually after — enough files, of the right kinds, already on the work item. Written for Jira and JSM admins who set this up for other people.
Two different questions. The built-in rule asks whether a file was uploaded in this dialog; a field-based rule asks what the work item already holds — by count and by kind.
What the built-in validator actually checks
First, a correction to our own earlier article, How to make an attachment mandatory in Jira Cloud, which said the built-in validator can't target attachments. It can: Add rule → Validate details → Validate a field, set Validate that field to Isn't empty, and pick Attachment under For field(s). What follows is what that article should have said.
The validator passes only if the transition also has a screen carrying the Attachment field — a Request input rule on the same transition. Without the screen it fails every time, whatever the work item already holds. Atlassian tracked this as JRACLOUD-74046 and closed it with the resolution Timed out: never fixed, and not mentioned on the validator's own documentation page. If you have set this up and watched it refuse a work item with five attachments, this is why — the refusal reads Transition failed: Field Attachment is required.
The built-in rule: Validate a field, Isn't empty, Attachment. The help text under Error message already says what it checks — a value the user provides during the transition.
The same rule on a transition without a screen: one file already on the work item, and the transition still fails.
With its screen in place it works — and it asks a narrower question than most gates need:
- The moment, not the state. Only a file uploaded in that dialog counts. The approval someone attached last Tuesday doesn't, which is why teams end up re-uploading documents they already have.
- No count. One file and nine files satisfy it equally.
- No kind. A screenshot of the login page passes a rule that meant "rollback plan".
As of October 2026, native Jira Cloud can require that a file be uploaded during a transition. It cannot require that a file already be on the work item, how many files there are, or what kind they are.
Where the native answer is enough
Creating a work item. "Did you upload something just now?" is exactly the right question on the Create transition, because there is no earlier state to miss. The same Isn't empty rule on Create, Attachment on the create screen, and "no bug without a screenshot" is solved — no app needed. The JSM portal's required attachment on the request form, and the rest of the create-time map, are in the earlier article.
Catching it afterwards. An Automation rule can check {{issue.attachments.size}} on a transition and comment, reopen or reassign. Worth having as a safety net — but it is detection after the save went through, with somebody's inbox as the enforcement.
Scripted validators. Workflow-extension apps with expression or script validators can express "at least two attachments" or "a file whose name matches this pattern". They work; the trade is a rule that lives in code somebody maintains, and a file's name as a weak stand-in for what the document is.
The scorecard
What the rule has to check | Built-in option | What it actually enforces |
|---|
A file uploaded when the work item is created | Validate a field (Isn't empty) on Create, Attachment on the create screen | Exactly that — and it is sufficient |
A file uploaded during a transition | Validate a field (Isn't empty), plus a transition screen with Attachment | Exactly that — and it fails every time without the screen |
A file already on the work item | — | Nothing; the validator can't see it |
A number of files | — | Nothing |
A specific document, not just any file | — | Nothing |
Missing files, after the fact | Automation on {{issue.attachments.size}} | Detection, not prevention |
Four questions a gate can ask, and which mechanism can answer each of them.
Requiring the state, not the moment
Full disclosure: we build File Field for Jira & JSM at Terano Apps, and the steps below use it. The native section above is the part that matters, and it works without us.
Everything the built-in validator can't do follows from one fact: attachments aren't a field, so no rule can read them as a value. A File Field is a real custom field that holds files. Jira's own Required flag applies to it — on create, edit and transition screens and on the JSM portal — and checks what the field holds, not what was just uploaded; the earlier article walks through that setup. And because it is a field, a workflow rule can ask the second question: not is there anything, but is there enough, of the right kinds.
The example throughout: a change that cannot reach Done without test evidence, a rollback plan and an approval — three documents, three kinds, one field.
Step 1 — One field, three categories
Create a File Field named for the job — Release Evidence — on the screens the change uses. In its configuration, turn on Categories and define Test Evidence, Rollback Plan and Approval. A category is a label picked at upload; it lets one field carry three distinct documents while staying one field to configure, one column on a board and one thing to search.
Step 2 — Add the rule to the workflow
Open Jira Settings → Work items → Workflows, edit the workflow, and choose Add rule. Search for file and pick File Field has the required files, listed under Marketplace rules. No transition screen is involved at any point.
The rule sits under Marketplace rules, next to Jira's own rule types; its description states the two checks it makes.
Step 3 — Choose the transition, the count and the categories
Set Transition to Any status → Done, pick Release Evidence, set Minimum number of files to 3, and select all three categories under Required categories. The category list is read from the field you picked, so it always offers that field's own categories.
[IMAGE 6 — wstaw tutaj: image-6-validator-configure.png]
A field, a minimum count, and one required category — the test rule that produced the message below. The rule reads the field as it stands on the work item.
The two settings are independent, which is where people guess wrong: three files plus the category Approval means three files of which one is an Approval — not three Approvals, and not four files. Categories are checked by presence, not by count, so "two files in the same category" can't be asked for. And documents an admin publishes on the field as templates or guidance never count: the rule reads the work item, not the field's configuration.
Step 4 — Publish the workflow
Choose Update workflow. A rule in an unpublished draft guards nothing, and this is the step that quietly gets skipped. The rule works in company-managed and team-managed projects, and on the agent-side transitions of a JSM project. One rule checks one field; to guard two File Fields on the same transition, add it twice.
What the person sees when it blocks
Jira refuses the transition and names only what is missing — the count against the minimum, and each category still empty. On the test rule above, with enough files attached but none in the required category:
Field 'multiple file field' is not ready: a file in category 'cat 2' is required; Attach the file(s) on the work item, then run this transition again.
On Release Evidence the same message names Approval.
The refused transition on a test project: the field name and the empty category, nothing else. Requirements already met aren't listed, so the person reads only what they still have to attach.
That last detail is the difference between a gate people route around and one they use: nobody has to ask an admin what the rule wanted. Attach the file, run the transition again, and it goes through with no message at all.
Find what closed before the rule existed
Every gate arrives after a backlog: the rule guards transitions from the moment the workflow is published, and last quarter's changes are untouched by it. Native JQL gets you part of the way — further than the folklore says. The attachments field supports IS EMPTY and IS NOT EMPTY, and nothing else: no count, no type, no name.
project = OPS AND statusCategory = Done AND attachments IS EMPTY
That lists the closed changes with no file at all. The two ways of falling short that matter — too few files, or files but not the approval — need the field:
project = OPS AND statusCategory = Done AND "Release Evidence.FileCount" < 3
project = OPS AND statusCategory = Done AND "Release Evidence.Categories" = "Approval"
The first returns changes closed with too few files. The second lists the closed changes that do carry an approval; set its count against all closed changes and the difference is your exceptions list — one saved filter per document you care about, and the gap is visible without opening a single work item.
Where this lands in practice
- Change management. No change reaches Done without test evidence, a rollback plan and the CAB approval — the Definition of Done from the wiki page, written somewhere Jira can read it.
- HR onboarding through JSM. The portal collects the ID scan and the signed contract on one File Field; the agent's transition to Complete is refused until both categories hold a file.
- Procurement. A purchase can't move to Paid until the signed contract, the purchase order and the invoice are all on it — three kinds, checked by kind.
Quick answers
Can a Jira Cloud workflow validator require an attachment?
Yes. The built-in Validate a field rule, set to Isn't empty, accepts the Attachment field, provided the transition also has a screen with Attachment on it. It is satisfied only by a file uploaded in that dialog.
Why does the validator block the transition even though the work item has attachments?
Either there is no transition screen with the Attachment field — that is JRACLOUD-74046, closed as Timed out — or the files were attached earlier rather than in the dialog, which is how the rule is designed. Neither can be configured away.
Can I require a minimum number of attachments on a transition?
Not natively. A file custom field with a workflow rule can; File Field's rule takes any whole number from 1 upward.
Can a transition require a specific document, not just any file?
Not natively — the validator sees "a file". With categories on a File Field, a rule can demand one file in each category you name: one Test Evidence and one Approval, not merely two files.
→ File Field – Attachment Custom Field for Jira & JSM on the Atlassian Marketplace
If you gate transitions on files another way — a scripted validator, an Automation rule that reopens, a form — I'd like to read how it holds up in the comments, especially for the "already attached last week" case.
Michał Krysiuk, Terano Apps
