atlassian-sync

bmad-atlassian-sync

Bidirectional sync between Markdown artifacts and Jira Cloud / Confluence Cloud. Built for the BMAD Method but works standalone with any project.

---

Quick Start (Claude Code Plugin)

claude plugin add https://github.com/3D-Stories/bmad-atlassian-sync.git
claude plugin install atlassian-sync

Then in any project:

1. /atlassian-sync:configure — walks you through credentials and project setup
2. /atlassian-sync:sync-jira — push, pull, and sync your .md files with Jira/Confluence

No Node.js required. Only Python 3.8+ (stdlib only, zero pip packages).

---

Features

• Push stories and epics to Jira as Stories/Epics (creates new issues or updates existing ones)
• Pull Jira state into local .md frontmatter (status, timestamps, remote changes)
• Bidirectional conflict resolution — never-downgrade rule ensures status only moves forward
• Publish Confluence pages — sprint summaries, retrospectives, and change proposals
• Claude Code plugin — install once, use /atlassian-sync:sync-jira in any project
• BMAD workflow integration — agent critical actions hook into dev-story, sprint-planning, and more (v6.2.1+)
• Standalone CLI — works without BMAD or Claude Code for any project with Markdown files
• Frontmatter-driven — jira_key, confluence_page_id, last_synced_at written back to .md files automatically
• Zero external dependencies — Python API client uses only stdlib; no pip packages, no runtime bloat

---

Prerequisites

• Python 3.8+ — the API client uses only stdlib (no pip packages required)
• Atlassian Cloud account with:
  • A Jira project
  • A Confluence space
  • A service account API token (see Authentication below)

For BMAD module or TypeScript CLI usage, you also need:

• Node.js 18+ and npm 9+

---

Authentication

This tool authenticates via the Atlassian Cloud API (api.atlassian.com) using Basic auth with a service account email and API token.

Create a Service Account

1. Go to admin.atlassian.com
2. Create a service account (or use an existing one)
3. Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens

Required API Token Scopes

Read:

• read:jira-user
• read:jira-work
• read:me
• read:account
• read:board-scope.admin:jira-software
• read:board-scope:jira-software
• read:epic:jira-software
• read:issue:jira-software
• read:sprint:jira-software
• read:confluence-content.all
• read:confluence-content.summary
• read:confluence-space.summary

Write:

• write:jira-work (classic scope — required for creating/updating issues via REST v3)
• write:board-scope:jira-software
• write:board-scope.admin:jira-software
• write:epic:jira-software
• write:issue:jira-software
• write:sprint:jira-software
• write:confluence-content
• write:confluence-file
• write:confluence-props
• write:content:confluence
• write:content.property:confluence

Note: The Agile v1 API (boards, sprints) requires the granular Jira Software scopes above. If you get 401 Unauthorized; scope does not match on board/sprint operations, verify these scopes are on your token. The classic write:jira-work scope is also required alongside the granular scopes — they are not interchangeable.

Find Your Cloud ID

Visit https://your-domain.atlassian.net/_edge/tenant_info and copy the cloudId value.

Environment Variables

Create a .env file in your project root (copy from .env.example):

ATLASSIAN_SA_EMAIL=your-service-account@serviceaccount.atlassian.com
ATLASSIAN_API_TOKEN=your-api-token
ATLASSIAN_CLOUD_ID=your-cloud-id
ATLASSIAN_SITE_URL=https://your-domain.atlassian.net
JIRA_PROJECT_KEY=PROJ
CONFLUENCE_SPACE_KEY=PROJ
JIRA_BOARD_ID=1

---

Installation

Option A: Claude Code Plugin (recommended)

Works with any project. No BMAD required. Only needs Python 3.8+.

claude plugin add https://github.com/3D-Stories/bmad-atlassian-sync.git
claude plugin install atlassian-sync

Test locally during development:

claude --plugin-dir ./path/to/bmad-atlassian-sync

Two skills are available after install:

• /atlassian-sync:configure — set up credentials and project config
• /atlassian-sync:sync-jira — push, pull, and sync operations

Option B: BMAD Module (for BMAD teams)

Requires BMAD v6.2.1+.

git clone https://github.com/3D-Stories/bmad-atlassian-sync.git
cd bmad-atlassian-sync
./scripts/install-bmad.sh /path/to/your-bmad-project