Atlassian integration
Overview
Section titled “Overview”Connect Atlassian so Promptless can use your Jira issues and Confluence pages when it drafts documentation, and start documentation work from Jira. One Atlassian Cloud OAuth connection covers Jira, Confluence, or both:
| Capability | What Promptless does | Set it up |
|---|---|---|
| Jira context | Reads the Jira issues that pull requests and commits reference, such as PROJ-123, and searches with JQL for related issues. | Jira context source |
| Confluence context | Searches your Confluence spaces for existing patterns, terminology, and architectural decisions, so new documentation stays consistent. | Confluence context source |
| Jira triggers | Starts documentation work from Jira issues, and replies on the issue that started it. | Jira trigger |
| Jira issue creation | Creates a Jira issue when you ask for one during a session. | Create a Jira issue on request |
Promptless reads Confluence and never writes to it. In Jira, it posts replies and documentation PR links, and creates the issues you ask for. Which account it writes as, and when it needs your permission first, depends on whether you attach a service account.
In this guide, you connect Atlassian, choose the account Promptless uses, and attach a service account so mentions and assignments in Jira start documentation work.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization.
- The Atlassian account Promptless should read as. Promptless sees what that account sees, so a dedicated account gives you the most control.
- For Jira mentions and assignments, an Atlassian organization admin who can create a service account.
Permissions required
Section titled “Permissions required”The OAuth consent screen lists the permissions Promptless requests. Promptless requests the scopes only for the products you select when you connect:
| Product | Scope | What Promptless uses it for |
|---|---|---|
| Jira | read:jira-work | Reads Jira issues, projects, and work data. |
| Jira | write:jira-work | Comments on the ticket that started a session, attaches the documentation PR as a remote link, and creates a Jira issue on request. |
| Jira | read:jira-user | Reads user information for issue context. |
| Jira | manage:jira-webhook | Registers, renews, and deletes the webhook that delivers Jira ticket events. |
| Confluence | read:confluence-space.summary | Reads space names and metadata. |
| Confluence | read:confluence-content.all | Reads page content for documentation context. |
| Confluence | read:space:confluence | Reads space information. Granular scope. |
| Confluence | read:page:confluence | Reads individual pages. Granular scope. |
| Confluence | read:content:confluence | Reads content bodies. Granular scope. |
| Confluence | search:confluence | Searches spaces with CQL to find relevant pages. Granular scope. |
| Confluence | read:content-details:confluence | Reads the content metadata that search returns. Granular scope. |
| Both | offline_access | Refreshes tokens without asking you to reauthorize. |
The Confluence scopes include classic and granular variants for compatibility with Atlassian’s API v2.
Connect Atlassian
Section titled “Connect Atlassian”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.
-
On the Promptless Integrations page, select Connect Atlassian.
-
Select Jira, Confluence, or both, and select Continue to Atlassian. Promptless requests only the permissions for the products you select.
-
If Atlassian shows its login screen, log in with the account you want Promptless to use.
-
On the OAuth consent screen, review the permissions Promptless requests. For what each scope is for, see Permissions required.
-
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.
-
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.
If you connected Jira before Promptless supported Confluence, reconnect to give it access to your Confluence spaces. Reconnecting keeps your existing Jira configuration.
Provision an Atlassian account for Promptless
Section titled “Provision an Atlassian account for Promptless”Connect Atlassian as a dedicated account, such as “Promptless Bot,” to get a separate audit trail. A dedicated account also lets you control exactly which Jira projects and Confluence spaces Promptless can see. The account is a standard Atlassian user that you invite by email, and it connects through the same OAuth flow. It needs no administrative permissions:
| Product | Permission the account needs |
|---|---|
| Jira | The User role, not User access admin, on projects Promptless should reference. |
| Confluence | Can view on spaces Promptless should search. |
A dedicated account gives Promptless a separate identity for reading and commenting, but it doesn’t turn on Jira mentions and assignments. Only an attached service account does that.
Use an email alias like your_email+promptless@company.com, or ask your IT admin for a new address like promptless@company.com.
-
In Atlassian, go to your settings, and under Atlassian admin settings, select User management.
-
Select Invite people, and enter the email address for the Promptless account. Under the Jira app, select the User role.
-
Log out of your personal Atlassian account. The invitation works only when you accept it as the Promptless account.
-
Open the invitation in the Promptless account’s inbox, or in your own inbox if you used an alias, and accept it. You can name the account “Promptless Bot.”
-
In User management, confirm that the account’s status is ACTIVE. The status can take up to an hour to change from INVITED.
-
While logged in as the Promptless account, connect Atlassian.
Atlassian service account
Section titled “Atlassian service account”Attach an Atlassian service account to give Promptless its own Jira identity. A service account is a non-personal Atlassian account that authenticates with a Client ID and secret instead of through the OAuth connection. Which account Promptless uses for Jira changes what it does there:
| Jira behavior | Without a service account | With a service account attached |
|---|---|---|
| Account Promptless reads Jira as | The connecting account | The service account, whose Jira project permissions set which issues Promptless can see |
| Comments, links, and new issues | Posted as the connecting account, and only when your request or your Agent Knowledge Base explicitly permits that action | Posted as the service account |
Built-in promptless label and configured Jira triggers | Start sessions | Start sessions |
| @mentions and assignments | Start no session | Start sessions, and Promptless replies on the issue |
Confluence always uses the connecting account. A trigger configuration on its own doesn’t permit Promptless to write as the connecting account. Without that permission, Promptless still does the documentation work and skips the Jira write. Either way, Promptless ignores its own activity on a ticket. For how each Jira path starts a session, see the Jira trigger page.
Mentions and assignments require a service account by design. Without one, the account Promptless acts as is a real person. A colleague who @mentions or assigns that person during ordinary Jira work would summon Promptless, which is noisy for that person and their team. A dedicated, non-personal identity avoids that noise.
Attach a service account
Section titled “Attach a service account”An Atlassian organization admin creates the service account’s credentials, and a Promptless admin attaches them:
-
In Atlassian Admin, go to Directory > Service accounts, and create a service account.
-
On the same screen, give the account the Jira User application role. For an existing account, use ⋯ > Allow access instead.
-
On the account’s Credentials tab, select Create credentials.
-
Choose OAuth 2.0 as the authentication type, and name the credential.
-
On Select scopes, grant these classic scopes:
read:me,read:jira-user,read:jira-work, andwrite:jira-work. -
Select Create, and copy the client ID and secret. Atlassian doesn’t show the secret again.
-
On the Promptless Integrations page, on the Atlassian card, enter the Client ID and Client secret.
-
Optional. Enter the Atlassian Admin address, so the card can link to the account’s credentials page.
-
Select Attach.
The card then shows the attached account’s display name, email, account ID, and client ID. If Atlassian rejects the credentials, Promptless leaves the account unattached and shows an error. The service account uses a client-credentials grant, so Promptless mints a new 60-minute token as needed and stores no refresh token. Its scopes cover Jira only.
Fix a broken service account
Section titled “Fix a broken service account”The service-account section of the Atlassian card carries a health badge:
| Badge | What it means | What to do |
|---|---|---|
| Not working | Atlassian refuses the credential, for example because its secret was rotated or revoked, or the account lost its Jira User role. | Re-attach the service account with its current Client ID and secret. |
| Unconfirmed | Promptless couldn’t reach Atlassian to check the credential. | No action needed. Promptless checks again during its next health check. |
Reconnecting the Atlassian OAuth connection doesn’t fix a broken service account, because the OAuth connection and the service-account credential are separate. Promptless also doesn’t fall back to the connecting account when the service account fails. If you’re troubleshooting from a symptom instead, see Connection health.
Create a Jira issue on request
Section titled “Create a Jira issue on request”Ask Promptless during a session to create a Jira issue. With a service account attached, a Slack or Microsoft Teams message that names the target project is enough. Promptless creates issues only when you ask, never on its own or in response to a trigger. Before it creates one, it searches the project for an issue that already covers the same work, and reuses that issue when it finds one. It can’t set custom fields on the issues it creates.
The new issue’s reporter is the account Promptless uses for Jira: the attached service account, or else the person who connected Atlassian. Without a service account, Promptless creates the issue only when the request or your Agent Knowledge Base explicitly permits issue creation as that person. Permission to comment doesn’t cover issue creation. Issue creation uses the write:jira-work scope that Promptless already holds, so you don’t need to reconnect.
To have Promptless open issues as part of a task you define, pair issue creation with your own trigger and written instructions. See Teach Promptless a custom task.
Fix common Atlassian problems
Section titled “Fix common Atlassian problems”| Problem | Cause | Fix |
|---|---|---|
| Promptless doesn’t respond to Jira @mentions or ticket assignments. | No service account is attached, so those deliveries start no session. | Attach a service account. |
| Promptless didn’t comment on a Jira issue, though no service account is attached. | Writing as the connecting account needs explicit permission, and none was given. | Ask for the comment in your request, add standing permission to your Agent Knowledge Base, or attach a service account. |
Confluence searches fail with 401 Unauthorized; scope does not match, while Jira works and the connection shows as connected. | The connection predates the search:confluence and read:content-details:confluence scopes. | Reconnect Atlassian from the Integrations page. Reconnecting keeps your Jira and Confluence configuration. |
| Promptless can see confidential Jira projects or Confluence spaces. | Promptless inherits the permissions of the connecting account, or of the service account for Jira when one is attached. | List only the projects and spaces Promptless should search under context_sources on the Configuration page. For a hard limit, connect as an account that can’t see the confidential content, such as a dedicated account. |
| The Atlassian card shows No Atlassian account recorded. | Promptless couldn’t read the account that connected Atlassian, so it can’t tell its own Jira comments from a person’s. | Reconnect Atlassian from the Integrations page. |
| Promptless actions are attributed to your personal account. | You connected Atlassian while logged in as yourself. | Disconnect Atlassian, log out of your personal Atlassian account, log in as the Promptless account, and connect again. |
For how Promptless processes Jira data, including redaction and privacy controls, see the Jira context source page.
See also
Section titled “See also”- Jira trigger, to choose which Jira events start documentation work
- Jira context source and Confluence context source, to set which projects and spaces Promptless searches
- Connection health, to find and fix integrations that stopped working