Jira connector setup

Operator·4 minutes to read

This page is the setup half — creating the OAuth 2.0 (3LO) app Atlassian needs in its developer console and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Atlassian. This connector is for Jira Cloud only; Jira Data Center and Server use a different OAuth provider and different addresses.

1. Create the OAuth app in the Atlassian developer console

  1. Open the Atlassian developer console and create an OAuth 2.0 integration — this is your own app, not Botseon's.

  2. Under Permissions, add the Jira API and its two classic scopes from section 2.

  3. Under Authorization, configure OAuth 2.0 (3LO) and paste the callback URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

    http://127.0.0.1:3000/api/oauth/jira/callback

    It must match exactly — scheme, host and path.

  4. Open Settings. The Client ID and Secret are there — copy both.

A new app is private: only your own Atlassian account can authorise it. To let other sites connect, turn on Distribution → Enable sharing. Until Atlassian has reviewed the app, everyone who authorises it sees "this app has not yet been reviewed by Atlassian", and Atlassian publishes no turnaround for that review. Some sites restrict third-party apps, in which case a site admin, not the member connecting, has to allow it.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

Read:

  • read:jira-work — read projects, issues, comments and transitions.
  • offline_access — stay connected: without it Atlassian issues no refresh token.

Write, on top of the read set:

  • write:jira-work — create and change issues, move them through their workflow, and comment. A comment notifies the issue's watchers, so that tool's approval card names the issue and the comment's text is disclosed on the card.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug jira \
  --client-id <the client ID from step 1> \
  --auth-url https://auth.atlassian.com/authorize \
  --token-url https://auth.atlassian.com/oauth/token \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug jira says whether an app is configured and under which client id; nothing prints the secret back.

After authorising, set the plugin's Atlassian site id (cloud_id): it is the id that GET https://api.atlassian.com/oauth/token/accessible-resources returns for your site, a value in the form 1324a887-45db-1bf4-1e99-ef0ff456d421. It never changes.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

  • jira.search_issues — searches issues with a JQL query, one page of up to 100 at a time.
  • jira.get_issue — one issue, its description as text and the transitions it allows.
  • jira.list_comments — the comments on an issue.
  • jira.list_projects — the projects on the site.
  • jira.create_issue — creates an issue. Tagged write; the approval card names the project.
  • jira.update_issue — changes an issue's summary, description or labels. Tagged write; the approval card names the issue.
  • jira.comment — comments on an issue. Tagged write and external_send, because a comment notifies the issue's watchers; the approval card names the issue and the comment's text is disclosed on the card.
  • jira.transition_issue — moves an issue along one of the transitions jira.get_issue lists for it. Tagged write; the approval card names the issue.

Refresh tokens rotate on every use and expire after 90 days without one; a connection nobody uses for 90 days has to be authorised again.

Jira counts API use in points per hour shared across every site an app reaches, plus per-second limits; a member may notice a short pause when a busy site reaches one.

EU data residency, available on Jira's Standard plan and above, changes where a site's data is stored, not the address this connector calls.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.

Last verified against build 331481c.