Jira
Data Center, Server and Cloud: two integrations, their access, webhooks and specifics.
Jira is connected with an integration from the catalogue — like any other tracker. The general behaviour (how to address the bot, what it writes, visibility scope, events) is described in “Tracker integrations”; here is only what concerns Jira specifically.
Two integrations, not one
jira | jira-cloud | |
|---|---|---|
| What for | Jira Data Center and Server (self-hosted, including old versions) | Jira Cloud (*.atlassian.net) |
| Sign-in | Personal Access Token (Jira 8.14+) or login and password (older) | the account email + an API token from id.atlassian.com |
| Comment | text with Jira markup | a document (ADF): paragraphs and mentions are nodes, not text |
| Search | JQL, POST /rest/api/2/search | JQL, GET /rest/api/3/search/jql |
| Webhook signature | checked | Cloud does not sign — the secret in the link serves as the pass |
| Showcase page | /marketplace/jira | /marketplace/jira-cloud |
They had to be split because Cloud has a different API — to the point that the familiar
POST /rest/api/2/search answers “410 Gone” there. One integration “just in case”
would mean that half of its code was not tested on any installation.
Setup
Install the integration from the catalogue and create a connection. The fields:
| Field | jira | jira-cloud |
|---|---|---|
| Address | https://jira.corp.local (with the context path, if there is one) | https://your-company.atlassian.net |
| Project keys | PROJ, OPS — the letters before the ticket number | the same |
| Credentials | a token (or login and password on old versions) | the account (email) and an API token |
| Alias | a short name for the bot, for example buff | the same |
| Development project | a project or space in Buff: questions and tasks from Jira go there, and its “Ask” and research get Jira’s tools | the same |
Create a separate account for the bot and give it access only to the projects you need: the account’s permissions are the outer boundary, the list of project keys is the inner one. Permissions to view and comment are enough; the bot must not be an administrator.
“Check connection” answers not with “ok” but with the version and edition of your Jira and the account the agent signed in with — so you can see that exactly what you need has been set up.
Mentioning the bot
Three forms work:
- Jira’s autocomplete — inserts a real mention (a link and a notification to the bot);
- plain text
@buff— for Jira this is ordinary text, but the bot still answers; - a slash command —
/ask,/research,/task.
In Cloud accounts have no login: there you address the display name (“@Buff Bot”) or the alias from the settings. Case does not matter.
The link and the document in the ticket
Jira can store links separately from comments, and the integration uses this: the link to the conversation or research in Buff goes into the ticket’s links block once — with the first answer; later answers in the same ticket do not duplicate it. The research document is attached to the ticket as an attachment — in both Data Center and Cloud — so it can be opened and forwarded without going into Buff.
The PDF in the ticket and the export from the app are typeset independently and do not look the same. The content is identical. Every page carries a colophon — the version and the commit of the code the research was prepared on — so that a printed copy stays identifiable.
Webhooks
Polling always works; a webhook only speeds up delivery. The general procedure is the same as for other trackers; the place in Jira is Administration → System → WebHooks → Create a WebHook. Tick “Issue updated” and “Comment created”; if you like, narrow the coverage with a JQL filter for the projects you need.
Data Center can sign its calls, and the connector checks this signature. Cloud cannot — there the secret inside the issued link serves as the pass, so the link must not be published.
If something does not work
| Symptom | Cause |
|---|---|
| “Failed: … personal access tokens” | Jira is older than 8.14 — switch to login and password |
“Jira answered 410” on the jira integration | the address leads to the cloud: this search method no longer exists there — install jira-cloud |
401 with a correct token in jira-cloud | the account is not filled in: Cloud signs in with the “email + token” pair |
| the bot is silent on a mention | the project is not among the connection’s project keys |
the “Overview” section says the jira section is not used | the config is left over from the version with the built-in integration — see below |
The built-in Jira integration has been removed. It used to be configured right in the agent,
with a jira: section in the config; now it is an integration from the catalogue. An agent with such a config
starts — it keeps the section untouched, does not use it and says so on
the settings page — but the section no longer works: the connection has to be created anew.