How to perform a safe upgrade and rollback of a Bitbucket instance

Below is a practical, step‑by‑step workflow you can follow to upgrade a Bitbucket Server or Data Center instance while keeping a reliable rollback path. The instructions are generic; adapt them to your specific environment (OS, database, add‑ons, custom scripts, etc.).

Prerequisites & Assumptions

• Current Bitbucket version is supported for upgrade (see Atlassian Version Support Matrix).
• Database (PostgreSQL, Oracle, MS SQL Server) is in a supported version and the database driver matches the new Bitbucket release.
• You have full administrative access to the Bitbucket installation directory and the underlying OS.
• You can stop the Bitbucket service and restart it without impacting other services.
• You have a backup strategy that includes the file system, database, and any custom configuration files.

1. Preparation

1. Read Release Notes – Download the release notes for the target version. Note any breaking changes, deprecated features, or required database schema updates.
2. Validate Add‑On Compatibility – Check the Add‑On Compatibility Matrix for your version. Identify add‑ons that need updates or removal.
3. Document Custom Configurations – Export bitbucket.properties, server.xml, jetty.xml, and any custom scripts. Keep a change log.
4. Notify Users – Schedule downtime and inform teams about the planned maintenance window.

2. Backup

1. Stop Bitbucket Service – systemctl stop atlbitbucket (or equivalent).
2. File System Backup – Archive the /opt/atlassian/bitbucket directory (or your install path). Example: tar -czf bitbucket-files-$(date +%F).tar.gz /opt/atlassian/bitbucket.
3. Database Backup – Perform a full logical backup (e.g., pg_dump, mysqldump, expdp) and store it securely. Verify the backup by restoring to a test database.
4. Snapshot (Optional) – If you use a hypervisor or cloud VM, take a snapshot before proceeding.

3. Test Upgrade in Staging

1. Clone Production – Spin up a staging environment that mirrors production (same OS, database, add‑ons).
2. Apply Upgrade – Follow the same upgrade steps as production. Record any issues.
3. Run Integration Tests – Verify REST APIs, webhooks, and custom scripts work.
4. Performance Benchmark – Optionally run a light load test to detect regressions.

4. Upgrade Execution

1. Download Upgrade Package – Get the correct installer (.tar.gz for Linux, .zip for Windows) from Atlassian.
2. Stop Bitbucket – systemctl stop atlbitbucket.
3. Unpack – Replace the bitbucket directory with the new files, preserving home and conf if they are separate.
4. Run Database Upgrade – Execute the embedded upgrade script (e.g., ./bin/upgrade.sh or run the installer’s database migration step). Follow prompts for schema changes.
5. Restart Service – systemctl start atlbitbucket.

5. Verification

1. Health Checks – Confirm the service is up: curl http://localhost:7990/rest/api/1.0/ should return JSON.
2. Functional Tests – Verify repository cloning, pull requests, permissions, and CI integrations.
3. Add‑On Tests – Ensure all add‑ons load without errors in the UI and in logs.
4. Performance & Logs – Monitor CPU, memory, and log files for abnormal activity.

6. Rollback Procedure

1. Stop Bitbucket – systemctl stop atlbitbucket.
2. Restore Files – Replace the upgraded directory with the backup archive. If a snapshot was taken, revert the VM to that snapshot.
3. Restore Database – Drop the upgraded schema and restore the pre‑upgrade database backup. Example: psql -U bitbucket -d bitbucket -f bitbucket-db-$(date +%F).sql.
4. Restart Service – systemctl start atlbitbucket.
5. Validate Rollback – Repeat the verification steps to ensure the instance is fully functional.

7. Post‑Upgrade Cleanup

1. Remove old backup snapshots if they are no longer needed.
2. Update documentation and incident playbooks to reflect the new version.
3. Plan the next maintenance window and repeat the cycle.