Jira Project Backup & Restore

Backup and restore individual Jira Cloud projects via REST API — issues, comments, worklogs, attachments, boards, and sprints. Fully resumable, with an interactive menu and CLI mode.

Why?

Jira Cloud has no built-in per-project backup/restore. The only native option was the full-instance Backup Manager, which Atlassian deprecated in March 2026. This tool fills the gap using standard REST API v3 endpoints.

Features

Quick Start

1. Install

Via PyPI (recommended):

pip install jira-project-backup-restore

Or clone for development:

git clone https://github.com/davidmalko87/jira-project-backup-restore.git
cd jira-project-backup-restore
pip install -r requirements.txt

2. Configure

cp .env.example .env

Edit .env with your Jira Cloud credentials:

JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=your-api-token

Generate an API token at id.atlassian.com/manage-api-tokens

3. Run

Interactive menu:

python main.py

==================================================
  Jira Backup & Restore Tool v1.5.0
==================================================
  Instance : https://your-domain.atlassian.net
  Auth     : API Token
  Backups  : ./backups

  --- Backup & Restore ---
  1) Backup project(s)
  2) Restore project from backup

  --- Browse & Analyze ---
  3) List existing backups
  4) Validate backup integrity
  5) Upload attachments only
  6) Export backup to CSV
  7) Inspect backup details

  --- Settings & Tools ---
  8) Test Jira connection
  9) Show current configuration
  10) Cleanup incomplete backups
  0) Exit

CLI — backup:

python main.py --backup PROJ
python main.py --backup PROJ1,PROJ2
python main.py --backup PROJ1,PROJ2 --skip-existing

CLI — restore:

python main.py --restore backups/PROJ_20260322_143000 --target NEWPROJ
python main.py --restore backups/PROJ_20260322_143000 --target NEWPROJ --dry-run

CLI — export to CSV:

python main.py --export-csv backups/PROJ_20260322_143000
python main.py --export-csv backups/PROJ_20260322_143000 --output-dir /tmp/report

CLI — validate a backup (exits non-zero on problems, for scripts/cron):

python main.py --validate backups/PROJ_20260322_143000

What Gets Backed Up

Restore Phases

Each phase can be toggled individually and is fully resumable via restore_progress.json:

Phases 1–5 run by default. Phase 6 is opt-in (it fires workflow rules and notifications): enable it with --with-statuses on the CLI, or by selecting 6 in the interactive phase prompt.

Issue key mapping between source and target is saved in key_mapping.json inside the backup directory.

✅ Round-trip Verified

The backup→restore round-trip has been proven end-to-end against a live Jira Cloud site: a project was backed up, restored into a fresh project, and diffed via the API — issue count, types, hierarchy (epics/subtasks), ADF bodies, labels, links (no duplicates), comments, worklogs, and attachment bytes (SHA-256) all matched. A backup is only proven once it has been restored end-to-end and verified; structural checks alone are necessary but not sufficient.

Known Limitations

These are Jira Cloud REST API constraints — not tool limitations:

Project Structure

jira-project-backup-restore/
├── main.py                   # Entry point — interactive menu + CLI flags
├── .env.example              # Configuration template
├── requirements.txt          # Python dependencies
│
├── jira_tool/
│   ├── config.py             # .env loader and validation
│   ├── auth.py               # Session builder (API token / cookie auth)
│   ├── api_client.py         # HTTP client with retry and rate-limit handling
│   ├── backup.py             # BackupManager — orchestrates full project backup
│   ├── restore.py            # RestoreManager — 5-phase restore
│   ├── export.py             # CSV export and backup statistics
│   ├── attachments.py        # Standalone attachment uploader
│   ├── adf.py                # Atlassian Document Format helpers
│   ├── progress.py           # Resumability tracker
│   ├── utils.py              # Logging, JSON I/O, utilities
│   ├── cli.py                # Console-script entry point
│   └── menu.py               # Interactive CLI menu
│
└── backups/                  # Backup output directory (gitignored)
    └── PROJ_20260322_143000/
        ├── manifest.json     # Completion marker + file index
        ├── issues.json
        ├── attachments/
        └── ...

Configuration Reference

All settings live in .env (copy from .env.example):

* Either JIRA_EMAIL + JIRA_API_TOKEN or JIRA_COOKIE_HEADER is required.

Requirements

• Python 3.10+
• requests >= 2.28
• python-dotenv >= 1.0

Changelog

See CHANGELOG.md for the full version history.

Contributing

See CONTRIBUTING.md for the versioning policy and how to bump the version when making changes.

License

MIT