> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tembo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Atlassian

> Connect Jira and Confluence to Tembo for issues, pages, and agent triggers.

![Jira](https://mintcdn.com/test-8862363a/_KF7n4fDwDrxMgZe/images/integrations/jira.png?fit=max\&auto=format\&n=_KF7n4fDwDrxMgZe\&q=85\&s=582fb44d215832ec37b4778e0f308d73)

The Atlassian integration connects both Jira and Confluence. Jira issues trigger implementation work; Confluence pages can trigger agents on page and comment activity.

## Jira

### Features

* Add the `Tembo` label to trigger implementation
* Use `tembo/{repo-name}` labels to target specific repositories
* Status updates and PR links posted as comments

### Installation

> [!NOTE]
>
> **We recommend giving Tembo its own Atlassian service account.** Install the integration with OAuth first, then connect a service account for Tembo. Jira comments and issue actions then come from a dedicated Tembo bot instead of the person who installed the integration.

**1. Connect Atlassian**

Go to **Settings > Integrations**, click **Install** next to Atlassian, and authorize your Atlassian site. Tembo uses this OAuth connection for webhooks, trigger configuration, and Confluence, so authorize with an account that can see the projects you want Tembo to work in.

**2. Connect a Tembo service account (recommended)**

Create a service account for Tembo in Atlassian and connect it to the integration. Follow [Set up a Tembo service account](#set-up-a-tembo-service-account) below.

**3. Add labels**

Create a `Tembo` label in your Jira project (recommended). Add it to any issue you want Tembo to work on.

### Service account

A service account is a non-human Atlassian account that exists only for Tembo. Once connected, Tembo uses it to work on Jira issues and post comments. The OAuth connection from installation stays in place and is still required.

> [card] Without a service account
>
> Tembo's comments and Jira actions show up under the personal account of the person who installed the integration.

> [card] With a service account
>
> Tembo's comments and Jira actions show up under a dedicated Tembo account that you manage in Atlassian Administration.

#### Prerequisites

* The Atlassian integration is installed through OAuth (see [Installation](#installation))
* Permission to manage integrations in your Tembo organization
* Access to Atlassian Administration for the organization that owns your Jira site

#### Set up a Tembo service account

**1. Create the service account**

In Atlassian Administration, go to **Directory → Service accounts** and create a service account with an OAuth 2.0 credential. See Atlassian's guide to [creating OAuth 2.0 credentials for service accounts](https://support.atlassian.com/user-management/docs/create-oauth-2-0-credential-for-service-accounts/).

Give the credential these **classic** scopes:

* `read:me`
* `read:jira-user`
* `read:jira-work`
* `write:jira-work`

Name the service account `Tembo` (or anything that contains `Tembo`). That name appears on every comment Tembo posts, and it's needed for @-mentions of the account to trigger Tembo (see [Mentions and comments](#mentions-and-comments)).

**2. Grant Jira access**

Give the service account the **Jira User** role on your site, plus access to every project you want Tembo to work in.

**3. Connect it in Tembo**

Go to **Settings > Integrations** and open your Atlassian integration. Under **Jira service account**, click **Connect service account** and enter the **Client ID** and **Client Secret**.

When you connect, Tembo checks the credentials before saving them. The credential must:

* Exchange successfully for an access token
* Include all four required scopes
* Belong to an active Jira user
* Have access to at least one project on the connected site

If any check fails, nothing is saved. When it succeeds, the settings page shows **Connected as** followed by the service account's display name. Tembo stores the client secret as an integration credential and never returns it in the settings page or API responses.

#### Which identity Tembo uses

| Service account | OAuth connection |
| - | - |
| Reading Jira issues and comments | Jira webhook registration and event delivery |
| Posting status, reply, and completion comments | Trigger configuration and evaluation (projects, statuses, users, labels, boards) |
| Jira tools used by agents during sessions | Syncing the installation |
| Recognizing Tembo's own comments and @-mentions | Confluence |

If the service account can't get a token or is refused access, the Jira action fails. Tembo never falls back to the OAuth user for that action.

#### Agent tools in bot mode

With a service account connected, agents can use only these core Jira tools:

* **Read:** search, get issue, list projects, list project issues, get worklogs, get transitions, search fields, list issue link types, get user profile, list project versions, list project components
* **Write:** create issue, batch create issues, update issue, add comment, transition issue, add worklog, create issue link, remove issue link

Board, sprint, and administration tools are unavailable in bot mode. Confluence tools keep working through the OAuth connection.

New agent sessions start using the service account immediately. Existing sessions pick up the change the next time their credentials refresh.

#### Mentions and comments

Once a service account is connected, Tembo treats the service account as its own Jira user:

* Tembo ignores comments written by the service account, so it doesn't respond to its own comments.
* @-mentioning the service account triggers Tembo only if the account's display name contains `Tembo`. Writing `@tembo` or `/tembo` in a comment still works whatever the account is named.

If Jira refuses to let Tembo edit a status comment it posted earlier, for example one posted before you connected the service account, Tembo posts the completion update as a new comment.

#### Replace or disconnect

* **Replace credentials** runs the same checks on the new Client ID and Client Secret, then swaps them in.
* **Disconnect service account** deletes the stored service account credentials. Jira actions and comments go back to the OAuth user. The Atlassian integration and its webhooks stay connected.

Reconnecting through OAuth keeps an existing service account. If the reconnect would switch to a different Jira site than the service account belongs to, Tembo rejects it and leaves your existing integration settings unchanged.

#### Limitations

* A service account can't replace the OAuth installation. Webhooks and the other features that use the OAuth connection still need it.
* Jira and Confluence must use the same Atlassian site. If your integration uses Confluence on a different site from Jira, you can't connect a service account.

### Usage

Add the `Tembo` label to any issue. Tembo reads the description, creates a coding session, and opens a PR.

If you add a `tembo/{repo-name}` label, that also triggers Tembo and routes the task to the selected repository.

#### Target a specific repository

Add a label in the format `tembo/{repo-name}` (for example, `tembo/monorepo`). This label also triggers processing on its own, so you do not need a separate `Tembo` label.

* `{repo-name}` must match the repository name as it appears in Tembo (the `name` field on the connected repository).
* The `tembo/` prefix is case-sensitive: use lowercase `tembo/`.
* Valid characters in `{repo-name}` are letters, numbers, `_`, `.`, and `-`.

When multiple `tembo/{repo-name}` labels are present, Tembo uses the first one that matches a connected, enabled repository.

#### Fallback behavior

If no `tembo/{repo-name}` label matches a connected, enabled repository, Tembo falls back to the default repository configured for your Jira integration in Tembo.

### Agents

See [Agents](https://docs.tembo.io/features/agents.md) for available Jira event triggers.

### Advanced

> [accordion] Tembo not responding to labels
>
> Verify the issue has the `Tembo` label or a `tembo/{repo-name}` label (for example, `tembo/monorepo`). If you connected a service account, confirm it can access the issue's project. Check integration status in **Settings > Integrations**.

> [accordion] Issues not being processed
>
> Ensure GitHub/GitLab/Bitbucket is connected. Include clear descriptions with acceptance criteria.

> [accordion] Service account connection fails
>
> * **Missing required scopes:** add the listed scopes to the service account's OAuth 2.0 credential. They must be classic scopes.
> * **Check the service account credentials, scopes, Jira User role, and access to this site:** confirm the Client ID and Client Secret are correct and the account has the Jira User role on the connected site.
> * **Give the service account the Jira User role and access to at least one project:** the account can't see any projects on the site yet. Grant it project access.
> * **Require Jira and Confluence to use the same connected site:** your integration uses Confluence on a different site from Jira. Service accounts don't support that setup.
> * **Atlassian is unavailable** or **validation timed out:** wait, then try connecting again.

> [accordion] Tembo can't comment or update issues after connecting a service account
>
> Tembo doesn't fall back to the OAuth user when the service account fails. Check that the service account can access the project the issue is in. If the account was deleted or its credential revoked, replace the credentials or disconnect the service account.

## Confluence

Confluence page and comment activity can trigger agents once Confluence triggers are enabled on your Atlassian integration.

### Setup

**1. Enable Confluence triggers**

In **Settings > Integrations**, click **Enable Confluence triggers**. This installs Tembo's companion Forge app; a site admin must approve the installation.

### Triggers

| Trigger | Description |
| - | - |
| Confluence Page Created | When a page is created in Confluence |
| Confluence Page Updated | When a page is updated in Confluence |
| Confluence Page Moved | When a page is moved in Confluence |
| Confluence Comment Created | When a comment is created on a Confluence page |
| Confluence Page Label Added | When a label is added to a Confluence page |
| Confluence Page Label Removed | When a label is removed from a Confluence page |

See [Agents](https://docs.tembo.io/features/agents.md) for how to use these as agent triggers.

### Filters

Each Confluence trigger supports optional filters so an automation only fires for the pages, spaces, or content you care about. Configure filters when you add the trigger to an agent.

| Filter | Available on | Description |
| - | - | - |
| Spaces | All triggers | Only trigger if the page is in a space with one of these names or IDs |
| Title contains | All triggers | Only trigger if the page title contains one of these substrings |
| Previous spaces | Page Moved | Only trigger if the page was moved from a space with one of these names or IDs |
| Locations | Comment Created | Only trigger for footer comments, inline comments, or both |
| Labels | Page Label Added, Page Label Removed | Only trigger if the added or removed label has one of these values |
| Comment contains | Page Label Added, Page Label Removed | Only trigger if the comment on the label event contains one of these substrings |

Leave a filter empty to match every event for that trigger.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.