Jira

A Jira ticket can start a Promptless session, and Promptless replies on the ticket when the work is done. This is separate from using Jira as a read-only context source, which lets Promptless read tickets for background but never acts on them or writes back.

How a Jira ticket starts a session

Four paths start a session from a ticket. Three are built in and active whenever Atlassian is connected, with no YAML to configure:

• Assignment — Assigning an issue to the account Promptless acts as.
• Reserved label — Adding a label whose first token is promptless (for example promptless or promptless-urgent). These promptless-prefixed labels are reserved for this built-in path and never route to a configured Jira trigger.
• Mention — @mentioning the Promptless account in a comment. The mention is matched by the account’s ID, not the literal handle text—an @mention picked from Jira’s autocomplete inserts the account’s display name, so no literal @promptless string appears in the comment.

For each of these three built-in paths, Promptless owes an answer on the ticket and tracks it the way it tracks an unanswered Slack thread. All three are the built-in jira_mention trigger—active whenever Atlassian is connected, with no YAML configuration. Like other built-in triggers, these paths are always on when Atlassian is connected and cannot be disabled. (Internally they are the assignment, label, and mention subtypes, but they route through the single jira_mention key, so a policy rule targets jira_mention rather than a per-path key.)

The fourth path is a configured Jira trigger that activates when an issue is created, when a label is added, or when an issue changes status. Like the three built-in paths, Promptless shares updates on the ticket and tracks it the same way.

Reply on the ticket

Promptless answers on the ticket and attaches the documentation PR as a remote link (a linked reference on the Jira issue). The link is deduplicated by a stable identifier, so re-posting never adds a duplicate link.

How a configured trigger activates

Each trigger type names the edge an issue crosses—the moment it activates on, whether the issue is created, a label is added, or the status changes—and a trigger activates once per crossing—never on a later delivery about an issue that still matches. Editing the description of a DOCS issue does not re-activate a new-issue trigger, and commenting on an issue that already carries needs-docs does not re-activate a label trigger.

Creating an issue crosses every edge at once: the issue comes into existence with its labels and its status. A new DOCS issue filed with needs-docs matches both the new-issue trigger and the label trigger, and dispatches once tagged with both keys—the trigger names you give in the triggers: map (for example jira-new-docs-issue and jira-needs-docs-label).

Match semantics follow the same rules as other triggers: within one clause the fields are ANDed; multiple clauses are ORed. All Jira fields match case-insensitively.

Multi-value matches compare each value on its own: a second listed label activates the trigger even when the issue already holds the first, and a move between two listed statuses activates it again.

Configuration

Configure Jira triggers in your Configuration page using the triggers section. Each type names the moment it activates on—an issue created, a label added, or a status change:

triggers:
  jira-new-docs-issue:
    trigger_type: jira_new_issue
    match:
      - project_key: [DOCS]
  jira-needs-docs-label:
    trigger_type: jira_label_added
    match:
      - new_label: [needs-docs]
  jira-ready-for-docs:
    trigger_type: jira_status_change
    match:
      - is_done: true
      - new_status: ["In Review", "Pull Request"]

The trigger map keys (jira-new-docs-issue) are yours to name; the trigger_type values (jira_new_issue) are the fixed type identifiers.

Fields inside a clause (each - item under match:) are ANDed and clauses are ORed. So jira-ready-for-docs above activates when an issue reaches any done status, and separately when it reaches In Review or Pull Request.

Scoping to projects

project_key is required on jira_new_issue, which would otherwise activate on every issue created anywhere in the site. It is optional on the other two types, and worth setting unless you mean the whole site—jira-needs-docs-label above matches a needs-docs label in any project. A jira_status_change clause may hold project_key alone, which matches any status movement within those projects.

Labels

Labels whose first token is promptless are reserved for the built-in jira_mention path (see How a Jira ticket starts a session), which claims them before any configured trigger is consulted. A new_label listing one never matches, so name the label something else (needs-docs). A label that merely contains the word (docs-promptless, not-promptless) is not reserved and is free to use.

Matching done statuses

new_status names statuses one by one, which is brittle: status names are per-project, anyone can rename them, and a done-like status added later is silently uncovered. is_done: true matches Jira’s done category instead, which is stable across projects and renames, so one clause covers every done status a site has whatever it is called.

is_done accepts only true. There is no way to say “moved to something not done”: that would match ordinary in-progress churn, and the statuses worth acting on are better named with new_status.

Note

An issue moved between two done statuses—Shipped to Closed—activates an is_done: true trigger a second time. This is expected, not a bug: the move is a second status change into a done status, so it is a second crossing of the edge the trigger names.

Instructions and output

instructions is optional on all three types (it is required on schedule triggers) and carries the same meaning: standing work handed to Promptless on each run. It is how a label carries a standing job—apply the label and Promptless runs those instructions against the issue. Omit it to work from the issue alone; a present-but-blank value is invalid.

triggers:
  jira-docs-plan:
    trigger_type: jira_label_added
    instructions: Scope the docs impact, do not publish.
    match:
      - new_label: [docs-plan]
        project_key: [DOCS]

A Jira trigger’s output lands wherever the run’s escalation and publishing settings send it—a docs suggestion and PR, plus the usual Slack or Teams notification. Like the built-in jira_mention trigger, Promptless comments on the ticket and flags it for follow-up if it goes unanswered (see Reply on the ticket). A blocker or escalation from the run also comments on the ticket and notifies any configured escalation channel.

See the Configuration Reference for the full schema.

Give Promptless an identity to post as

Promptless replies on the ticket either way—a service account is not required for it to write. What the identity determines is who the reply posts as. Attaching a dedicated Atlassian service account gives Promptless its own bot identity to post as.

Without a service account, Promptless acts as—and posts as—the account that connected Atlassian. Assigning a ticket to that person starts a session, and that person’s own ticket activity is ignored—Promptless does not act on its own identity’s activity. Mention and assignment matching both key on the acting account, so the identity determines who the reply posts as and who triggers Promptless. With a personal connecting account, any colleague who @mentions or assigns that person in ordinary work starts a session. That’s one more reason to give Promptless a dedicated identity, covered on the Atlassian integration page.

Attach the service account from the Atlassian integration card by entering its Client ID and Client secret (“Attach service account”). See the Atlassian integration guide for the full setup.

Note

Reading Jira for context is a separate, read-only capability. See the Jira context source page.

Example

A team adds the jira-docs-plan trigger above. A writer adds the docs-plan label to ticket DOCS-204 in the DOCS project. Applying that label activates the trigger. Following the standing instructions (Scope the docs impact, do not publish), Promptless analyzes the linked change and scopes what documentation is affected, then comments on the ticket with that scope, the same way the built-in paths comment on the ticket. Because this run is do-not-publish, there’s no PR to link.

Later, the same team moves DOCS-204 into In Review. That status crossing activates the jira-ready-for-docs trigger, which watches for the In Review and Pull Request statuses. And when someone files a brand-new DOCS issue that already carries needs-docs, it crosses both the new-issue edge and the label edge at once, matching both jira-new-docs-issue and jira-needs-docs-label—Promptless dispatches once, tagged with both keys.

Separately, an engineer @mentions the Promptless account on DOCS-204 to ask for the update. Promptless replies on the ticket and attaches the documentation PR as a remote link.

Setup instructions

To connect Atlassian and attach a service account, see the Atlassian integration guide.