bb2git-attachments

A lightweight companion tool for handling attachments during Bitbucket → GitHub migrations.

About

• Designed to work alongside the Bitbucket migration tool: https://github.com/twenty20solutions/bitbucket-migration
• Tested using PowerShell (note: the main migration tool runs on Linux only)
• Successfully used on three repositories
• BitBucket download will only be available until Atlassian turn it off on Aug 20th 2026
• Works with external file attachments AND inline image file
• detailed description including commandline options are included in the script pydoc string
• Best to use environment variables to pass the following:
  • BITBUCKET_EMAIL
  • BITBUCKET_TOKEN
  • BITBUCKET_COOKIE = "cloud.session.token= ..." (copy from a browser session using developer tools(inspect)/network/doc/headers/request headers/cookie)
  • GITHUB_TOKEN

Usage

1. Download attachments Run the download step to retrieve attachments. This populates the attachments_temp folder created by the migration tool, which helps avoid crashes when private repository attachments cannot be fetched.
2. Run migration tool Execute the main migration tool to migrate issues and comments.
3. Upload attachments Run the upload step to push attachments to GitHub.
4. Optional cleanup
   • Inline images can be reattached manually for proper display. Edit the comment in GitHub, then drag and drop the attachment file to embed it inline.
   • Check for multiple attachments in a single comment (see below)

Known Issues / Limitations

1. When multiple attachments exist in a single comment, only the last attachment is preserved in the original comment. The remaining attachments are appended at the end as separate comments (one per attachment). These can be manually moved back into the original comment if needed.
2. The last comment in BitBucket documenting the issue being resolved is sometimes missing from GitHub. Potentially this is an issue with the migration tool. I have not investigated this at all.