Jira

Jira is an issue-only integration: your assigned, open issues land in the Inbox, complete with attached images, and Birch can move them through your workflow when you start a workspace or open a PR. Jira Cloud uses your email plus an API token; Server/Data Center uses a personal access token — Birch detects which kind of Jira it’s talking to automatically.

Cloud vs Server/Data Center

Birch decides the deployment type by asking the site itself: it probes Jira’s unauthenticated serverInfo endpoint and reads the deployment type it reports. Only when that probe can’t be reached does Birch fall back to the site URL’s host — .atlassian.net means Jira Cloud, anything else is treated as Server/Data Center. That choice controls both how Birch authenticates and where the token link points:

	Jira Cloud	Jira Server / Data Center
Site URL	https://your-domain.atlassian.net	Your self-hosted Jira URL
Email field	Required — your Atlassian account email	Ignored
Token	Atlassian API token	Jira personal access token (PAT)

The site URL is required in both cases.

Creating the token

Click Create an API token or PAT ↗ in the connect form:

• With a Cloud URL (or no URL yet), it opens the Atlassian account token page, https://id.atlassian.com/manage-profile/security/api-tokens — Cloud API tokens belong to your Atlassian account, not to the Jira site.
• With a self-hosted URL, it opens that instance’s profile page on its Personal Access Tokens tab. If your Jira version doesn’t offer PATs, the link degrades to the plain profile page — ask your admin about enabling personal access tokens.

Adding the account

1. Open Settings → Integrations (⌘, / Ctrl+,) and click the Jira tile.

2. Fill the form:

   Field	What to enter
   Email	Your Atlassian account email (used for Jira Cloud; ignored for Server/DC)
   Token	API token (Cloud) or personal access token (Server/DC)
   Site URL	Required. https://your-domain.atlassian.net or your self-hosted Jira URL

3. Click Verify & connect. Birch verifies the credentials before storing them; on success the account appears with a Connected badge and Sync now / Remove buttons.

The token is stored in the system keychain, and multiple Jira sites can be connected side by side. See the providers overview for the shared connection model.

What you get

• Assigned issues in the Inbox Tasks tab, synced roughly every 10 minutes — see the Inbox overview.
• Attached images as thumbnails. Jira issue descriptions don’t embed images in a way Birch can fetch from the text, so Birch takes the issue’s image attachments instead — they appear as thumbnails in the task’s detail pane and are handed to the agent when a workspace launches from the task.
• Hierarchy. Birch reads each issue’s parent — a sub-task’s story, or a story’s epic — and nests tasks under their parent in the Inbox list.
• Issue identifiers like PROJ-123 label the task and its status prompts.

No PRs, no repository matching

Jira has no pull requests and no git remote, so a Jira task can’t be matched to a local repository. Clicking Start workspace on a Jira task opens the Choose Repository dialog — pick where the work should happen. That’s the designed flow. See Start a workspace from a task.

Status transitions

When you start a workspace from a Jira task, or create a PR from that workspace, Birch offers to move the issue. The statuses offered are Jira’s own workflow transitions for the issue, so applying one moves the issue exactly as clicking that transition in Jira would.

Configure the behavior per account in Settings → Tasks: Ask each time, Change automatically (after a status has been remembered), or Never offer — see status transitions.

Troubleshooting

• Cloud account fails to verify — make sure you entered your Atlassian account email plus an API token, not your password. API tokens are created at id.atlassian.com, not inside Jira.
• Server/DC account fails to verify — use a personal access token, not your Jira password, and check that your Jira version supports PATs.
• Cloud site treated as Server/DC — deployment detection probes the site’s serverInfo endpoint, so this usually means the probe was blocked (by a proxy or firewall) and Birch fell back to the URL heuristic, which only recognizes .atlassian.net hosts. Check that the site is reachable from your machine, or enter your site’s https://your-domain.atlassian.net address rather than a custom vanity domain.
• Issues missing from the Inbox — Birch syncs issues assigned to you that are still open; resolved issues and issues your token can’t browse won’t appear.