Hyperlink to source code in Bitbucket

Typical stack traces often contain file path and line number, but rarely know about Bitbucket accounts, repositories, or Git commits. Products need to negotiate this outside of the run-time context so they can go from run-time error back to the source code. This usually meant lining up stack traces, exception reports, or log messages to local copies of source code, with the hope that the local copy is at the same revision as production.

How hyperlinking helps solve this problem

Now integrators can hyperlink from error reports to a specific line of code in Bitbucket. The trick is to base your linking on the right information: account, repository, commit, file path, and line number.

Mac users

In the source file, to select multiple lines of code hold shift or command and click row numbers you want to select. then you can copy the browser URL and share it.

Windows

In the source file, to select multiple lines of code hold shift or CTRL and click row numbers you want to select, then you copy the browser URL and share it. to unselect lines, hold command/ctrl and click row numbers that are already selected.

Source view URL

URI Template for src

1 {+bitbucket}{/owner, repository_name}/src{/commitish}{/filepath}{?fileviewer}{#fileline}

Key

Required

Description

Example value

bitbucket

Yes

The base URL for Bitbucket Cloud.

https://bitbucket.org

owner

Yes

The account owner the repository that contains the target file.

atlassian

repository_name

Yes

The name of the repository that contains the target file. Also known as the repo slug.

python-bitbucket

commitish

Yes

The ref (branch or tag) or commit SHA for the state of the target file. Note: Forward slashes are not supported in branch names.

main

filepath

Yes

The path within the repository and the name of the target file.

tests/test_auth.py

fileviewer

No: optional

The file viewer for the target file. If not provided, Bitbucket will append the default file viewer to the URL.

file-view-default

fileline

No: optional

The target file name plus the line number, separated by a dash. Without the fileline segment, the URL simply navigates to the target file.

test_auth.py-29

Example URL for src

1 https://bitbucket.org/atlassian/python-bitbucket/src/main/tests/test_auth.py?fileviewer=file-view-default#test_auth.py-29

How to obtain the owner, repository name, and commit

Since this metadata is not available with most stack traces, it needs to be negotiated with specific knowledge of Bitbucket. Here are some options:

  • Extract the metadata during build-time. For example, let's consider building a Java project with Bamboo. Bamboo exposes the Bitbucket repository URL and revision as environment variables. Parsing the URL will reveal the owner and repository name. All 3 can be written into the META-INF/MANIFEST.MF before packaging into the JAR.

  • Correlate Bitbucket web hooks for push events with artifact deployment events.

  • Require naming conventions.

  • Ask for it.

About the file viewer

When using a file viewer for linking stack traces we recommend using Bitbucket's default file viewer.

Bitbucket provides, as add-ons, a number of file viewers which can be useful for files that are not source code: like graphics, videos, or 3D models. However, most products that do production monitoring don't own the format of the underlying source code. Moreover, using a custom file viewer will require that any user who clicks the link has that file viewer installed.

 

Additional Help