Automates the Jira Cloud backup process using using the web UI via Playwright. Includes two scripts:

• jira_backup: Creates a new backup and initiates the download
• jira_download: Downloads an existing backup file

Jira Cloud is deprecating their backup API in favor of a manual process through the UI. These tools automate that manual process. They expect you have a user account with a password and optionally a TOTP 2FA. It has not been tested without at TOTP

Run:

export JIRA_HEADLESS=false
export JIRA_URL=https://ORGANIZATION.atlassian.net
export JIRA_USERNAME=USER@EXAMPLE.COM
export JIRA_PASSWORD=PASSWORD
export JIRA_TOTP_SECRET=TOTP_SECRET
uv sync
uv run playwright install chromium
uv run jira_backup.py
sleep 1h
uv run jira_download.py

• JIRA_HEADLESS=false If "false", a browser window will be shown so you can watch the session. If "true" it will run without a browser window displayed.
• JIRA_URL=https://ORGANIZATION.atlassian.net This is your Jira URL, you can probably find this in the browser URL bar when you are in Jira.
• JIRA_USERNAME=USER@EXAMPLE.COM This is your login username, either of your account or a dedicated account (preferred), but either way it needs to have permissions to run and download backups.
• JIRA_PASSWORD=PASSWORD The plaintext password for the above account.
• JIRA_TOTP_SECRET=TOTP_SECRET If set, this must be a TOTP secret. The secret isn't the 6 digit number, it's the 32 character alphanumeric secret that generates the 6 digit numbers.

• Backup frequency: Jira only lets you take a backup every ~30 hours, so don't run this more frequently than that or the backup step will fail.
• The "jira_backup" script tries to wait for the backup to complete

Creates a new backup:

1. Log in to Jira
2. Navigate directly to Backup Manager
3. Create backup for cloud (with optional attachments)
4. Wait for backup completion
5. Initiate the backup file download

Note: This script initiates the download but exits immediately after verifying it has started. The download will continue in the browser session.

Downloads an existing backup:

1. Log in to Jira
2. Navigate to Backup Manager
3. Download the most recent available backup file

Note: This script fully downloads the backup file to your specified directory (defaults to current directory).

# Install Python dependencies
uv sync

# Install Playwright browsers
uv run playwright install chromium

export JIRA_URL=https://yourcompany.atlassian.net
export JIRA_USERNAME=your.email@company.com
export JIRA_PASSWORD=your_password

For 2FA/TOTP (optional but recommended):

If your account has 2FA enabled, you have two options:

Option 1: Automated TOTP (recommended for scheduled backups)

Export your TOTP secret (base32 encoded):

export JIRA_TOTP_SECRET=JBSWYED73HPDEPXP  # Your TOTP secret from authenticator app

To get your TOTP secret:

• When setting up 2FA in Jira, it shows a QR code
• Most authenticator apps let you view the manual key/secret (base32 encoded string)
• If already set up, you may need to reset 2FA to get the secret again

Option 2: Manual entry (interactive)

If you don't provide JIRA_TOTP_SECRET, the script will pause and prompt you to enter the 6-digit code from your authenticator app.

Additional optional configuration:

# Include attachments, avatars, and logos (default: true)
export JIRA_INCLUDE_ATTACHMENTS=true

# Custom download directory (default: ./backups)
export JIRA_BACKUP_DIR=/path/to/backups

# Run in headless mode (default: true)
export JIRA_HEADLESS=true

# Backup timeout in minutes (default: 60)
export JIRA_BACKUP_TIMEOUT_MINUTES=120

Command Line:

# Create and initiate download of a new backup
uv run python jira_backup.py

As a Python Module:

from pathlib import Path
from jira_backup import create_jira_backup

success = create_jira_backup(
    jira_url="https://yourcompany.atlassian.net",
    username="your.email@company.com",
    password="your_password",
    totp_secret="JBSWY3DPEHPK3PXP",  # Optional, for automated 2FA
    include_attachments=True,
    download_dir=Path("./backups"),  # For debug screenshots only
    headless=True,
    timeout_minutes=60,
)

If you already have a backup created and just want to download it:

Command Line:

# Download the most recent available backup
uv run python jira_download.py

As a Python Module:

from pathlib import Path
from jira_download import download_jira_backup

success = download_jira_backup(
    jira_url="https://yourcompany.atlassian.net",
    username="your.email@company.com",
    password="your_password",
    totp_secret="JBSWY3DPEHPK3PXP",  # Optional, for automated 2FA
    download_dir=Path.cwd(),  # Downloads to current directory
    headless=True,
)

To run automated backups daily at 2 AM:

# Edit crontab
crontab -e

# Add this line (adjust paths as needed)
0 2 * * * cd /path/to/jira-backup && /path/to/uv run python jira_backup.py >> backup.log 2>&1

⚠️ Selectors May Need Adjustment: Jira's UI changes over time. If the script fails, you may need to update the CSS selectors in the code to match the current UI. Look for AIDEV-TODO comments in the code.

⚠️ Backup Times: Large Jira instances can take significant time to back up. Adjust JIRA_BACKUP_TIMEOUT_MINUTES accordingly.

⚠️ Security: Never commit your password or TOTP secret to version control. Always use environment variables or a secure secrets manager.

Run with JIRA_HEADLESS=false to see what's happening in the browser:

export JIRA_HEADLESS=false
uv run python jira_backup.py

Then update the selectors in jira_backup.py to match the current Jira UI.

• Verify your username and password are correct
• Check if your organization uses SSO (may require additional setup)
• Ensure your account has admin access to create backups

If 2FA is not working:

1. Using TOTP secret: Verify your JIRA_TOTP_SECRET is correct (base32 encoded)
2. Manual entry: Run with JIRA_HEADLESS=false to see the 2FA prompt and enter the code manually
3. TOTP selectors: The script tries multiple selectors for the TOTP input field. If it fails, you may need to update the selectors in jira_backup.py (search for "totp_input")

Increase the timeout:

export JIRA_BACKUP_TIMEOUT_MINUTES=120
uv run python jira_backup.py

MIT