Atlassian integration

Used for: Context and triggers

Note

Promptless integrates with both Jira and Confluence through a single OAuth connection. When engineers reference Jira issue keys in GitHub PRs or commit messages (like “PROJ-123”), Promptless automatically retrieves the ticket for context. Promptless also searches your Confluence spaces for existing patterns, terminology, and architectural decisions to keep new documentation consistent.

Note

If you previously connected Jira to Promptless, reconnect to access Confluence spaces. Your existing Jira project configuration is preserved.

Permissions required

The OAuth consent screen displays the permissions Promptless requests when you connect Atlassian. Promptless requests only the scopes needed to read Jira issues and Confluence pages for documentation context.

Jira scopes

Scope	Purpose
read:jira-work	Read Jira issues, projects, and work data
write:jira-work	Used to reply on a ticket and attach the documentation PR as a remote link when a Jira trigger runs
read:jira-user	Read user information for issue context

Confluence scopes

Scope	Purpose
read:confluence-space.summary	Read space names and metadata
read:confluence-content.all	Read page content for documentation context
read:space:confluence	Read space information (granular scope)
read:page:confluence	Read individual pages (granular scope)
read:content:confluence	Read content body (granular scope)
search:confluence	Search spaces with CQL to find relevant pages (granular scope)
read:content-details:confluence	Read content metadata returned by search (granular scope)

Additional scopes

Scope	Purpose
offline_access	Allow Promptless to refresh tokens without re-authentication

Note

Confluence scopes include both classic and granular variants for compatibility with Atlassian’s API v2. Promptless writes to Jira only when a Jira trigger runs—posting the reply comment and attaching the documentation PR as a remote link—never proactively, and never to Confluence. This write happens whether or not a service account is attached; the service account only changes the identity Promptless posts as (a dedicated bot account instead of the connecting user). Reading Jira and Confluence for context remains read-only.

Note

If you connected Atlassian before Promptless started requesting the Confluence search scopes, reconnect from the integrations page to grant search:confluence and read:content-details:confluence. Until you do, Confluence searches fail with 401 Unauthorized; scope does not match—Jira and existing Confluence page reads keep working, so the connection still shows as connected and that search error is your signal to reconnect. Reconnecting preserves your existing Jira and Confluence configuration.

Service account permissions

When creating a dedicated Atlassian account for Promptless, the account needs:

1. Jira access: The “User” role (not “User access admin”) on projects you want Promptless to reference
2. Confluence access: “Can view” permission on spaces you want Promptless to search

The account does not need administrative permissions. See Provision an Atlassian account for Promptless for step-by-step instructions.

Jira Cloud installation

For Atlassian Cloud-hosted Jira instances:

1. Connect Jira Cloud. Click “Connect Jira Cloud” from the integrations page.

2. Atlassian Login. If you’re not already logged in, you’ll see the Atlassian login screen:

   

3. OAuth Consent. Review the permissions Promptless is requesting on the OAuth consent screen:

   

4. Complete Connection. Click “Accept” and verify the connection in Promptless. If you don’t see the option to accept, you may not have the required permissions. Contact your Jira administrator or invite them to Promptless. For more information about adding new members, see our Account Management page.

After connecting, manage Promptless access by going to your avatar > Account settings > Connected apps in Atlassian:

What you can do with Atlassian

Once connected, you can use Jira and Confluence as context sources to enhance documentation suggestions:

• Jira: Automatically retrieve ticket information and search for related issues using JQL queries. See the Jira Context Source page for details.
• Confluence: Search your Confluence spaces for existing documentation patterns, terminology, and architectural decisions. See the Confluence Context Source page for details.

Atlassian service account

Attaching an Atlassian service account gives Promptless its own bot identity, so it can start sessions from Jira tickets and reply on them. See the Jira trigger page for what the identity does. This is distinct from the invited-user account described in Provision an Atlassian account for Promptless: that account is a standard Atlassian user you invite by email and authenticate through the normal OAuth connect flow, whereas the client-credentials service account described here is authenticated directly with a Client ID and secret and is what gives Promptless a dedicated write identity for Jira triggers.

How to attach. An Atlassian organization admin first creates OAuth 2.0 credentials for a service account in Atlassian admin (Directory → Service accounts → create OAuth 2.0 credentials). From the Atlassian integration card, enter the service account’s Client ID and Client secret, plus an optional Atlassian Admin address, then click “Attach service account.” The admin address isn’t required—attaching works without it. If Atlassian rejects the credentials, Promptless leaves the account unattached and shows an error notification. The card then shows the attached account’s display name, email, account ID, and client ID.

Token handling. The service account uses a client-credentials grant with 60-minute tokens that Promptless re-mints as needed; there is no refresh token.

Required scopes and role. The service account needs the following OAuth scopes, plus the Jira User application role:

• read:me
• read:jira-user
• read:jira-work
• write:jira-work

These scopes are Jira-only—there is no Confluence scope—so the service account is used for Jira trigger writes, not Confluence.

Identity implications. Whichever account Promptless acts as is the identity behind assignment triggering, mention matching, and ignoring its own activity. Attaching a service account moves that identity off the connecting admin. Without one, the connecting admin is that identity—so assigning a ticket to them starts a session, and their own ticket activity is ignored. Because mention and assignment matching both key on the acting account, making that identity a real person has a cost: any colleague who @mentions or assigns them in the ordinary course of Jira work starts a Promptless session—a noisy experience for that person and their team. A dedicated, non-personal identity avoids this. That identity can be either the service account described here or the standard user you invite through Provision an Atlassian account for Promptless.

The Atlassian integration card shows a labeled panel naming the account that authorized the connection—the connecting admin’s display name and email. Promptless always reads Jira and Confluence as this account, whether or not a service account is attached. What changes with a service account is who Jira comments post as, and the panel’s label reflects that:

• No service account attached: the panel reads “Reading Jira and Confluence, and commenting on Jira, as this person.”
• Service account attached: comment identity moves to the service account, and the panel reads “Reading Jira and Confluence as this person”—scoping the connecting admin to reads.

The panel’s secondary line shows the account’s email, falling back to the account ID when Atlassian hides the email. When no Atlassian account is recorded and no service account is attached, the panel instead warns that mentioning or assigning Promptless on a Jira issue won’t start a session until you reconnect Atlassian.

Service-account health. The Atlassian integration card’s service-account section expands into a drawer; its collapsed line carries a health badge. It reads Not working (red) when Atlassian refuses the credential (for example, a rotated or revoked secret, or an account that has lost its Jira User application role), and Unconfirmed (amber) when Promptless can’t reach Atlassian to check. Opening the drawer shows a health message alongside Last worked… · Checked… timings.

To fix a broken service account, re-attach it: re-enter its Client ID and secret on the integrations page. Reconnecting (re-consenting) the Atlassian OAuth connection does not fix a broken service account, because the OAuth connection and the service-account credential are separate. If you’re troubleshooting from a symptom instead, see Connection health.

Attaching a service account does not change the read-only context-source behavior—reading Jira for context still works the same way (see the Jira context source page). The next section covers inviting a standard Atlassian user account instead.

Provision an Atlassian account for Promptless

You can also provision a dedicated Atlassian account by inviting a standard user rather than attaching a service account. We recommend creating a dedicated Atlassian account for Promptless to access both Jira and Confluence. A dedicated account gives you complete audit trail visibility and lets you configure fine-grained permissions for both services.

Create the account using an email alias like your_email+promptless@company.com, or ask your IT admin to provision a new email account like promptless@company.com.

1. Navigate to User management. In Atlassian, go to your settings and select User management under Atlassian admin settings.

   

2. Invite the Promptless account. Click “Invite people” and enter the email address for your Promptless account. Under the Jira app, select the User role (not User access admin).

   

   Caution

   When accepting the invite, make sure you’re logged out of your personal account, and logged into the Jira account you created for Promptless, otherwise this won’t work.

3. Accept the invitation. Check your own email inbox (if you’re using the alias), or Promptless’s email inbox.

   

   When setting up the account, you can use the name “Promptless Bot”.

   Once complete, you’ll see the account listed as ACTIVE. It might take up to an hour for the status to update from INVITED to ACTIVE after you accept the invite.

   

Data processing and security

For information about how Promptless processes Jira data, including redaction capabilities and privacy controls, see the Jira Context Source page.

Troubleshooting

How do I restrict Promptless from accessing confidential Jira projects or Confluence spaces?

Promptless inherits the permissions of the Atlassian account used during OAuth connection. There are several ways to manage access depending on your security requirements:

Standard approach: After connecting Atlassian, configure which Jira projects and Confluence spaces Promptless should search in your Configuration page using the context_sources section. Promptless won’t access projects or spaces you don’t explicitly configure, even if the connected account has permission to see them.

For highly confidential content: Create an Atlassian user account that only has access to non-confidential projects and spaces, then connect Atlassian to Promptless using this limited-access account. This restricts access at the Atlassian permissions level, adding an extra security layer.

For granular control: Provision a dedicated Atlassian account for Promptless and configure fine-grained permissions for both Jira projects and Confluence spaces in Atlassian’s user management before connecting it to Promptless.

Promptless actions are attributed to my personal account

• Disconnect Atlassian from the integrations page
• Sign out of your personal Atlassian account in your browser
• Sign in to the Promptless bot account you created
• Reconnect Atlassian to Promptless while signed in to the bot account