Jira and Confluence

When a pull request mentions a Jira issue, MergeHarbor reads the issue (and, on Jira Cloud, the Confluence pages linked from it) and checks the change against its acceptance criteria. The same connection can comment on linked issues, turn findings into issues, triage new issues and feed automations. Azure Boards works the same way.

There are two ways to connect:

Integration	Connects with	Confluence
Atlassian (Jira Cloud)	OAuth 2.0 with your Atlassian account	Yes
Jira Data Center / Server	A personal access token (Jira 8.14 or later)	Not yet

What it does in reviews

• Finds linked issues. MergeHarbor looks for issue keys such as ENG-123, or issue URLs such as https://acme.atlassian.net/browse/ENG-123, in the branch name, the pull request title, its description and its commit messages, in that order. Branch names match in any case (feature/eng-123-rate-limit). Up to three issues are used per pull request. Strings that look like keys but are not, such as UTF-8, SHA-256, ISO-8601, RFC-… and CVE-…, are ignored.
• Adds a requirements check to the review summary. Acceptance criteria come from an “Acceptance criteria” or “Definition of done” section, a checklist, or Given/When/Then scenarios in the issue. Each criterion is marked Met, Not met or Unclear, with file:line evidence from the pull request. If the issue has no criteria, MergeHarbor lists up to three requirements it inferred from the description, labelled “(inferred)”. Under each issue, Docs read lists the Confluence and Notion pages the review read for it.
• Costs no extra model call. The check is part of the review itself. The issue text is bounded (by default it adds at most 3,000 input tokens), and nothing is added when no issue is linked.
• Looks for related work when nothing is linked. If the pull request names no issue, MergeHarbor searches the allowed projects (and Confluence spaces) for up to two issues and one page that match the title, and gives them to the review as background only. They are never checked as requirements and never commented on. Turn this off with Look for related work.
• Cites what it used. A comment that relied on an issue or page ends with a “Source used:” line linking to it.
• Lets the review look things up. During a review the agent can read another issue by key or search for related issues, within the same project, space and repository limits.
• Shows linked issues in the console. The pull request page lists linked issues with links to Jira, the latest requirements check, and the docs read for each issue.

Acceptance criteria

The description is converted to plain text (Atlassian Document Format on Cloud, wiki markup on Data Center) before criteria are read from it. Secrets such as tokens and keys are removed before any text reaches a model.

Connect

Jira Cloud

1. In the console, open Integrations and choose Connect on Jira & Confluence Cloud. You need the settings.manage permission.
2. Sign in to Atlassian and approve access. MergeHarbor reads as the account that approved it, so it sees what that account can see.
3. Choose Test connection to list the Jira projects and Confluence spaces the connection can see on each site.

Scopes MergeHarbor requests:

Scope	Why
read:jira-work	Read issues, their links and project keys
read:confluence-content.all	Read Confluence pages linked from an issue
read:confluence-space.summary	List the Confluence spaces the connection can see
search:confluence	Find related pages when no issue is linked
offline_access	Keep the connection working without signing in again
write:jira-work	Only when you allow comments: comment on issues and create issues

Jira Data Center or Server

1. In Jira, create a personal access token (Profile → Personal Access Tokens). Use an account that can read the projects you want; the token has that user’s permissions. To comment or create issues, the account needs those permissions too.
2. In Integrations, choose Connect on Jira Data Center, and enter your Jira base URL and the token.

MergeHarbor checks the token before saving it and sends it as a Bearer token. Your Jira URL must be reachable from MergeHarbor; private and internal addresses are refused unless your installation allows them. Confluence Data Center is not supported yet.

Settings

Open Manage on the card:

• Sites (Jira Cloud): if the account reaches several Atlassian sites, tick the ones to use (all by default).
• Jira projects (and Confluence spaces on Cloud): empty means everything the connection can see.
• Repositories: only reviews of these repositories use the integration, and only people who can read them see what it returned.
• Look for related work: on by default.
• Use in pull request conversations: off by default. When on, people who can read an allowed repository can get answers that draw on the allowed projects when they ask MergeHarbor about a pull request. Turning it off hides earlier answers that relied on it.
• Comment on linked issues: off by default. See below.

The switch on the card turns the integration off without disconnecting it: reviews, chat, triage, automations and comments skip it, and its settings are kept.

Comments on linked issues

When you turn on Comment on linked issues, MergeHarbor comments on each linked issue when a review completes, for example:

MergeHarbor reviewed PR #12 in acme/api: 2 findings, confidence 4/5. Requirements: 2 of 3 met. View the review

It keeps one comment per issue and updates it on later reviews. On Jira Cloud this needs the write:jira-work scope: if you connected without it, the console asks you to reconnect with comment permission.

Create issues from findings

On a pull request, choose Create issue on a finding, then pick the project and issue type. The issue gets the finding’s title, explanation, file and line, a link to the pull request and a link to the review in MergeHarbor. Secrets are removed first. The issue key appears on the finding, and asking again for the same finding returns the same issue. You need the pulls.review permission, and the connection needs write access.

Issue triage

Issue triage reads new Jira issues in the projects you turn on and keeps one comment on each with possible duplicates, questions, acceptance criteria and suggested labels, priority and component. For instant triage, add a Jira webhook for Issue created (Settings → System → WebHooks) with the URL and secret from Triage settings; without one, MergeHarbor checks for new issues every few minutes.

Automations

Automations can start on a new Jira issue (through a webhook with a secret, header X-Hub-Signature) and can post a review summary as a comment on the linked issue after an approval.

PR chat and lookup tools

With Use in pull request conversations on, PR chat and chat apps read the issues named in a question, the pull request title, description or branch. The review agent’s lookup_ticket and search_tickets tools read and search the same allowed projects.

What MergeHarbor keeps

• Issue key, title, status, labels, description and acceptance criteria; on Jira Cloud, the title and text of up to two linked Confluence pages per issue.
• Issue and page text is cached for a short time (10 minutes by default) and deleted within 24 hours. It is never written to logs. The one exception is opt-in: if an administrator turns on Keep linked documents in the knowledge base, pages that issue triage reads are kept for the number of days they choose (1–365) after their last use (issue triage).
• A pull request keeps the keys and links of its issues and the requirements check from its review.
• The connection is named after your Jira site. No user names, email addresses or account ids are stored.
• Tokens are encrypted at rest and never shown again.

Turn off or disconnect

Use the switch on the card to pause the integration. To remove it, choose Disconnect from the card’s menu. MergeHarbor deletes its tokens and cached issue text. Then remove access at the service:

• Jira Cloud: Atlassian has no API to revoke the app’s access, so remove MergeHarbor at id.atlassian.com/manage-profile/apps.
• Jira Data Center / Server: delete the personal access token in Jira.

Self-hosted installations

To offer Connect for Jira Cloud, register an OAuth 2.0 (3LO) app in the Atlassian developer console:

1. Add the Jira API scope read:jira-work (and write:jira-work for comments and issue creation) and the Confluence scopes read:confluence-content.all, read:confluence-space.summary and search:confluence.
2. Set the callback URL to {PUBLIC_URL}/integrations/connect/atlassian/callback.
3. Set ATLASSIAN_OAUTH_CLIENT_ID and ATLASSIAN_OAUTH_CLIENT_SECRET on the API, and make sure SECRETBOX_KEYS is set.

Without these, Jira Data Center / Server still works with a personal access token. Optional server settings: INTEGRATIONS_CACHE_TTL (default 10m), INTEGRATIONS_MAX_TICKETS (3), INTEGRATIONS_MAX_PAGES (2), INTEGRATIONS_CONTEXT_TOKENS (3000) and INTEGRATIONS_FETCH_TIMEOUT (8s).