Skip to content

For the complete documentation index, see llms.txt.

Jira

Start a Promptless session from a Jira ticket. Promptless reports back on the ticket, as Reply on the ticket describes. Use Jira triggers when your team plans and tracks documentation work in Jira.

A ticket starts a session in one of four ways:

PathWhat starts a sessionWhat it needs
LabelAdding a label whose first token is promptless, such as promptless or promptless-urgent.Atlassian connected.
Mention@mentioning the account Promptless acts as in a comment.An attached Atlassian service account.
AssignmentAssigning the issue to the account Promptless acts as.An attached Atlassian service account.
Configured triggerCreating an issue, adding a label, or changing an issue’s status, when it matches a Jira trigger you add.Atlassian connected and a Jira trigger.

The label, mention, and assignment paths are built in and need no YAML configuration. A configured trigger starts sessions whether or not a service account is attached.

Two related capabilities work differently. Jira as a context source lets Promptless read tickets for background without acting on them or writing back. To have Promptless create a Jira issue, see Create a Jira issue on request.

Skip this section if Atlassian is already connected on the Integrations page.

One Atlassian Cloud connection covers Jira, Confluence, or both. You need an admin role in your Promptless organization to connect it. Promptless reads Jira and Confluence with the permissions of the Atlassian account that approves the connection. If you attach an Atlassian service account, Promptless uses it for Jira instead. To connect a dedicated Atlassian account, log in to Atlassian as that account first.

  1. On the Promptless Integrations page, select Connect Atlassian.

  2. Select Jira, Confluence, or both, and select Continue to Atlassian. Promptless requests only the permissions for the products you select.

  3. If Atlassian shows its login screen, log in with the account you want Promptless to use.

    Atlassian Login Screen
  4. On the OAuth consent screen, review the permissions Promptless requests. For what each scope is for, see Permissions required.

    Jira OAuth Consent Screen
  5. Select Accept. If the consent screen shows no Accept option, your Atlassian account might not have the required permissions. Ask your Jira administrator to connect, or invite them to Promptless.

  6. On the Promptless Integrations page, confirm the connection on the Atlassian card.

To manage Promptless’s access later, open Atlassian and go to your avatar > Account settings > Connected apps.

Atlassian Connected Apps Management

Connecting Atlassian turns on the built-in label path and lets you add configured Jira triggers.

To start a session from a ticket on a built-in path, do one of the following:

  • Add a label whose first token is promptless. The label path works whenever Atlassian is connected.
  • With a service account attached, @mention the account Promptless acts as in a comment. Promptless matches the mention by the account’s ID. A mention picked from Jira’s autocomplete shows the account’s display name, so the comment needs no literal @promptless text.
  • With a service account attached, assign the issue to the account Promptless acts as.

Without a service account, a mention or an assignment starts no session.

Labels whose first token is promptless are reserved for the built-in label path, and they never route to a configured Jira trigger.

What Promptless posts on the ticket depends on how the session started. See Reply on the ticket.

The three built-in paths share one built-in trigger, jira_mention. To set publishing or notifications for them, target jira_mention in a policy rule. Each path has no key of its own.

When one Jira update carries more than one built-in path, Promptless starts at most one session, for the highest-precedence path that applies:

  • A promptless label starts a session even when a mention or assignment on the same update starts none.
  • Assignment outranks the label. With a service account attached, an update that both assigns the issue and adds a promptless label starts the session as the assignment.

What Promptless posts on the ticket depends on how the session started:

How the session startedWhat Promptless posts on the ticket
Mentioning or assigning PromptlessAn acknowledgement, progress updates when there’s something useful to share, and an answer, even when no documentation change is needed. A ticket left without an answer is flagged for follow-up.
A promptless label or a configured triggerA comment with the result when the work produces a suggestion, or a blocker you can act on. Promptless posts no progress updates, and no comment when there’s no documentation change.

A result comment links the suggestion and the documentation PR. Promptless also attaches the documentation PR as a remote link, a linked reference on the Jira issue. Re-posting never adds a duplicate link. Your configured Slack or Teams notification and escalation channels receive their usual messages as well.

With an Atlassian service account attached, Promptless reads tickets, comments, adds remote links, and creates issues as the service account. If Atlassian refuses the service account, Promptless reports the failure and doesn’t fall back to the person who connected Atlassian.

Without a service account, Promptless reads Jira as the person who connected Atlassian. Its comments, remote links, and new issues would appear under that person’s name. Promptless makes each of those writes only when your Knowledge Base or the current request explicitly permits that action:

  • Permission covers only the action and scope it names. A Knowledge Base note that says Promptless may comment on DOCS tickets permits comments there, not remote links or new issues.
  • Permission given in one request applies to that request only.
  • A configured trigger, a notification setting, or a request for documentation work doesn’t grant permission.

Without permission for these extra actions, Promptless still does the documentation work. It skips writing to Jira, records why, and delivers the result through your other notification channels.

Add a configured Jira trigger to start sessions when an issue is created, gets a label, or changes status in the projects you choose.

  1. On the Configuration page, switch to YAML mode.

  2. In the triggers section, add one or more Jira triggers. Each trigger_type names the moment it activates on:

    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"]
  3. Select Save.

You can also add these triggers on the Triggers tab. Under Tasks & tickets, select A new Jira issue, A Jira label, or A Jira status.

The trigger map keys, such as jira-new-docs-issue, are yours to name. The trigger_type values, such as jira_new_issue, are fixed type identifiers. See the Configuration Reference for the full schema.

Each trigger type names the edge an issue crosses: the issue being created, a label being added, or the status changing. A trigger activates once per crossing. A later update about an issue that still matches doesn’t activate it again. For example, editing the description of a DOCS issue doesn’t re-activate a new-issue trigger. Commenting on an issue that already carries needs-docs doesn’t re-activate a label trigger.

Creating an issue crosses every edge at once, because the issue arrives with its labels and its status. A new DOCS issue filed with needs-docs matches both jira-new-docs-issue and jira-needs-docs-label, and Promptless starts one session tagged with both keys.

Within one match clause (each - item), the fields are ANDed. Separate 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. 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.

project_key is required on jira_new_issue, which would otherwise activate on every issue created anywhere in the site. It’s optional on the other two types. Set it unless you mean the whole site: as written, jira-needs-docs-label above matches a needs-docs label in any project. A jira_status_change clause can hold project_key alone, which matches any status change within those projects.

A new_label that lists a label whose first token is promptless never matches, because the built-in label path claims those labels first. Name the label something else, such as needs-docs. A label that only contains the word, such as docs-promptless or not-promptless, isn’t reserved.

new_status names statuses one by one. Status names differ by project, anyone can rename them, and a done status added later isn’t covered. is_done: true matches Jira’s done status category, which stays stable across projects and renames, so one clause covers every done status your site has.

is_done accepts only true. To act on statuses outside the done category, name them with new_status.

instructions is optional on all three Jira trigger types. It holds standing work that Promptless runs each time the trigger activates. Use it to give a label a standing job: apply the label, and Promptless runs those instructions against the issue. Omit instructions to work from the issue alone. A blank value is invalid.

triggers:
jira-api-docs:
trigger_type: jira_label_added
instructions: Update the API reference for the change described in the issue.
match:
- new_label: [api-docs]
project_key: [DOCS]

A Jira trigger’s output goes wherever the run’s escalation and publishing settings send it. That’s a docs suggestion and PR, plus the usual Slack or Teams notification. Promptless also comments on the ticket when the run produces a suggestion or hits a blocker you can act on. A run with no documentation change posts nothing on the ticket. See Reply on the ticket.

Attach a service account for mentions and assignments

Section titled “Attach a service account for mentions and assignments”

Attach a dedicated Atlassian service account to give Promptless its own identity in Jira. Promptless then reads and writes Jira as that account, and the mention and assignment paths start sessions.

Without a service account, the account Promptless acts as is the real person who connected Atlassian. Promptless can’t tell ordinary ticket traffic for that colleague from a request for Promptless, so mentions and assignments do nothing. Promptless drops the update, doesn’t reply on the ticket, and doesn’t notify you in Slack or Teams. Only the label path and configured triggers start sessions. They read the ticket as the connecting account and write to Jira only with permission. See Which account Promptless uses in Jira.

Before you attach one, an Atlassian admin creates the service account’s credentials with the scopes it needs. See Atlassian service account.

  1. On the Integrations page, go to the Atlassian card.

  2. Enter the service account’s Client ID and Client secret.

  3. Select Attach.

The card then lists the attached account’s details. A Not working or Unconfirmed badge on the service account section flags a problem to fix.

Promptless ignores its own activity in Jira. It recognizes its own updates by the service account when one is attached, and by the connecting account otherwise.

A team with an attached service account adds the jira-api-docs trigger above. A writer adds the api-docs label to ticket DOCS-204 in the DOCS project. Applying that label activates the trigger. Following the standing instructions, Promptless updates the API reference and opens a suggestion and documentation PR. It then comments on the ticket with links to both and posts the usual Slack notification.

Later, the team moves DOCS-204 into In Review. That status change activates jira-ready-for-docs, which watches for the In Review and Pull Request statuses. When someone files a new DOCS issue that already carries needs-docs, the issue crosses the new-issue edge and the label edge at once. It matches both jira-new-docs-issue and jira-needs-docs-label, and Promptless starts one session tagged with both keys.

Separately, an engineer @mentions the service account on DOCS-204 to ask for a related update. Promptless acknowledges the request on the ticket and answers there when the work is done. It attaches the documentation PR as a remote link.