Hyperlinking 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.

Source view URL

URI Template for src
{+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. master
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

https://bitbucket.org/atlassian/python-bitbucket/src/master/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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport