Bitbucket now supports OAuth2 and fine-grained scopes for resources

By on July 30, 2015

Bitbucket just added different levels of access to its APIs, enabling add-on and integration developers to request read, write, or admin access to repos, issues, wikis, and snippets. For Bitbucket users this means that add-ons and integrations now only get the level of access they actually need.

More details can be found in Bitbucket documentation.

Why OAuth2?

Our previous OAuth1 implementation provided only all-or-nothing access to resources. As a developer building integrations or add-ons, you had less control. Additionally, some operations that were not possible via OAuth 1, such as cloning, are now possible via OAuth2, enabling a new set of add-on and integration functionalities.

How do I use OAuth2?

OAuth2 is available within webhooks, REST APIs, and Atlassian Connect for Bitbucket. When you register your application (add-on or integration) with Bitbucket you become an “OAuth consumer”. OAuth 1 consumers that have been previously instantiated have been grandfathered into all-access. However, all new consumers will now need to specify the scopes requested, with a much more granular set of scopes available now for both OAuth options.

How does it impact me if I am a Bitbucket user?

You have complete control and visibility over what levels of access are granted to resources and repositories when you plan to use a certain integration or add-on. You may choose to grant access via a page similar to the one shown below:

Screen Shot 2015-07-29 at 9.51.15 AM

You can also revoke access easily via “OAuth” under “Access Management” on your Settings page as shown below:

Screen Shot 2015-07-28 at 3.36.33 PM

Please upgrade to OAuth2

We encourage all developers of Bitbucket integrations and add-ons to upgrade the authentication mechanism they’re using to scopes and OAuth2 wherever possible.

Happy coding!

An easier way to call an api from your web app

By on July 24, 2015

This guest post is written by Ivan Storck, Director of Developer Relations at Aerobatic. Ivan has been programming, teaching, and leading startups for 20 years. He founded two training companies, a web hosting company, and taught at the University of Washington.

At Aerobatic, our mission is to empower front-end developers to innovate faster – less time spent thinking about infrastructure, more time spent developing amazing customer-facing experiences; less time spent building and maintaining custom toolchains, more time spent innovating with clients; less time switching contexts between disparate tools, more time spent coding in a seamless flow.

In this post, I’ll show you how to build a form that posts notifications to HipChat using the Aerobatic add-on for Bitbucket. It’s simple, and no server-side code will be required.

Do you have the time to be a full-stack developer?

Like many of you, I moved from server-generated web pages in PHP or Rails, to Single Page Apps (SPA). There is only one choice for the language: JavaScript, but there is still a lot to keep track of. I’m capable of creating a virtual server, Docker image, database setup, node API, or whatever I need. I can add in the JavaScript flavor of the month, from Backbone to Angular to React.

Lately, however, I have been asking the question, do I need to know all of this? Do I even have the time? What do I enjoy the most? The answer is that I love to create online products that are beautiful, useable, and technically well-crafted. The front-end is a big enough world for me to do that. But I don’t want to lose control of the back-end, or need to team up with others to get simple apps done. Realistically, my back-end needs can be simple, and similar to many other people.

Many of you may host your static sites on Amazon S3, and manually configure CloudFront CDN via the (confusingly large) Amazon Web Services interface. But this gives you no chance at a back-end. Others code a simple node server and publish it to a PaaS provider, but this means you write boilerplate back-end with a basic REST API yet again. Maybe you even have a puppet/chef/Docker script to spin up your own virtual server, but then you’re stuck upgrading it whenever a security patch is released. What if you didn’t have to worry about all this stuff? And if you didn’t understand any of the jargon in this paragraph, doesn’t that kind of prove my point?

The Aerobatic add-on for Bitbucket

Whether you have a Jekyll blog, a static site documenting your open-source project, or a full-featured web app built with a framework such as AngularJS, Ember, or React, you can now edit your code, push your changes to Bitbucket, and your site will be deployed automatically. Assets are automatically hosted on a content delivery network (CDN) so that your site visitors will see the site faster. You can also have a custom domain point to your Aerobatic site with a DNS CNAME record.

Express Request Proxy

Expanding our core hosting service for Bitbucket developers, Aerobatic is happy to introduce a custom webhook plugin for static site apps called Express Request Proxy. This means that you can call APIs on the internet without worrying about cross-origin resource sharing (CORS) policies or leaking secret keys to the client. You can even contribute your own plugins to the 4Front open-source project, which powers our back-end.

The Express Request Proxy plugin is a high performance, intelligent proxy that supports proxying AJAX requests to remote HTTP endpoints. In addition to simple pass-through proxying, it also supports caching, parameter injection (to query string, path, and body), as well as response transforms. In the package.json virtual router setup, you can define one or more instances of the proxy plugin.

The Express Request Proxy is available now in the Aerobatic Bitbucket add-on. Other plugins that will soon be supported include custom error pages, form processing, authentication, and more.

Post to HipChat from your web app with Aerobatic

I’ll walk you through using the Aerobatic Express Request Proxy to set up an integration with HipChat (a popular chat app). We will create a simple web app. It has a form that posts a message to a HipChat room using the HipChat API.

HTML page – index.html

Below I set up a basic index.html with a form, include main.js, and the simple Skeleton CSS framework.

<!DOCTYPE html>
<html lang="en">
  <meta charset="UTF-8">
  <title>Send a Support Message to a HipChat Room</title>
                    <link rel="stylesheet" href="">
  <meta name="viewport" content="width=device-width, initial-scale=1">
<div class="container">
<h1>Send a message</h1>
Use the form below to send a message to our HipChat room. Include your
      email and someone will contact you as soon as possible.

This form sends directly to the webhook

<form id="hipchat" action="#">
<div class="row">
<div class="twelve columns">
          <label for="name">Name:</label>
          <input class="u-full-width" type="text" id="name" placeholder="Your Name">
          <label for="email">Email:</label>
          <input class="u-full-width" type="text" id="email" placeholder="">
          <label for="message">Message:</label>
          <input class="u-full-width" type="text" id="message" placeholder="your message to the chat room">
          <button id="submit-button" type="submit" class="button button-primary">Send</button></div>
<div style="display: none" id="confirm">
      <button>Your request was sent to the HipChat room successfully</button></div>
<script charset="utf-8" src="main.js"></script>


Here’s the meat of the app – It processes the form and sends the data via AJAX. I decided to use vanilla JS , and not to use jQuery, because what I’m doing does not need the whole library.

var ready = function(fn) {
  if (document.readyState != 'loading') {
  } else {
    document.addEventListener('DOMContentLoaded', fn);

var checkLoad = function() {
  if (this.status >= 200 && this.status < 400) {
    document.getElementById('hipchat').style.display = 'none';
    document.getElementById('confirm').style.display = 'block';
  } else {
    alert('Error with API Endpoint\n' + this.response);

var ajaxError = function() {
  alert('Connection Error with API Endpoint');

var processFormData = function() {
  var formData = 'Name: ' + document.getElementById('name').value +
    ' | Email: ' + document.getElementById('email').value +
    ' | Message: ' + document.getElementById('message').value;

  return JSON.stringify({
    color: 'green',
    message: formData,
    notify: 'true'

var submitter = function(event) {
  var request = new XMLHttpRequest();
  var room = '1753375';'POST', '/hipchat/' + room, true);

    'application/json; charset=UTF-8'


  request.onload = checkLoad;
  request.onerror = ajaxError;

ready(function() {
     .addEventListener('submit', submitter);

Configuring the Express-Request-Proxy plugin

You might have noticed that I posted to a local endpoint ‘/hipchat’. Where does that come from? Here, in package.json, you can specify the plugin options. It’s all in the _virtualApp section.

  "name": "aerohip",
  "version": "0.0.1",
  "description": "Demo of using express-request-proxy on hosted apps",
  "main": "index.html",
  "scripts": {
    "start": "node ./node_modules/live-server/live-server.js"
  "repository": {
    "type": "git",
    "url": "git+ssh://"
  "keywords": [
  "author": "Ivan Storck",
  "license": "ISC",
  "homepage": "",
  "_virtualApp": {
    "router": [
        "module": "express-request-proxy",
        "path": "/hipchat/:room",
        "method": "post",
        "options": {
          "url": "",
          "query": {
            "auth_token": "env:HIPCHAT_AUTH_TOKEN"
  "devDependencies": {
    "live-server": "^0.7.1"

The Aerobatic section is called _VirtualApp because much like a virtual server, you can host multiple apps on an Aerobatic installation. The router section specifies how various paths in your application work. Each path matches a module. You’ll notice that in the “path” argument, there is a parameter called “:room” The actual value is contained in our client JavaScript in main.js. You’ll change that room value to be the room name or room ID that you wish to post to.

Configuring the environment variables for secrets

You need to get an access token from HipChat. This token should be kept secret. It’s not something you want to check into Bitbucket for the public to see. Even if you have a private repo, it should not be kept in a file, in case you decide to open-source the repo later. The Aerobatic plugin for Bitbucket has the ability to store environment variables, which is a good place to store authorization secrets.

Get your token

Visit and get either a personal access token, or an integration token, depending on whether you are doing this for just yourself or a team.

We will follow the personal access token path here. You will get asked to log in to your HipChat account next.

After that, you must choose an access scope for your token. To post to a HipChat room, you need ‘Send Notification’

The page will refresh and you should see your token appear above the form. Copy it to your clipboard for now.

We had specified the name of the environment variable in package.json as HIPCHAT_AUTH_TOKEN. Now we need to add it to your Repo Settings on Bitbucket.

The following section assumes you have already installed the Aerobatic add-on, linked your repo to Aerobatic, and that you are an administrator of the repo:

Try it out for yourself!

Let us know how it’s working for you — and if you run into any roadblocks. Visit our version of this demo app to drop us a line!

bitHound integration with Atlassian Connect for Bitbucket

By on July 15, 2015

This guest post is written by Dan Silivestru, CEO & Co-Founder of bitHound. Dan is a seasoned entrepreneur with over 15 years of experience in the field of software and technology. Previously, Dan was co-founder and CTO at tinyHippos, acquired by BlackBerry in 2011. Dan spent two years as an Executive in Residence (EIR) at Communitech, applying his expertise to mentor and advise startups. In late 2013, Dan co-founded bitHound Inc., a code insights startup in Kitchener, Ontario.

At bitHound we are passionate about helping developers better understand their code so that they can build great software. Building software involves making many decisions that can ultimately affect your outcome. By gaining insights into the impact of those decisions, bitHound helps developers deliver in a more reliable and secure fashion.

The development process and bitHound

Having spent our entire careers building software and working as developers, CTOs, and everything in between, we’ve lived the pain associated with building and delivering great software. We asked ourselves, “What if we could look at all of the data we generate: the code we write, the comments we make, the dependencies we use, and provide real, objective insights into the health of the software we’re creating?” And so bitHound was born.

What we do at bitHound

bitHound is code insights for your JavaScript, TypeScript, and JSX projects. We aim to keep you, the developer, in the driver’s seat: decide what and how you want to build software and who you want to build it with. Getting started with bitHound is simple. Login with your Bitbucket account and choose a project. It’s as simple as that.

Our insights arm you with the information you need to make educated decisions about whether or not your code is ready for production. These insights include vulnerabilities in your npm packages, developer identified tech debt, your most problematic files in your codebase, and more.

Earlier this year, we introduced support for Bitbucket on bitHound. The response from the Bitbucket community was overwhelmingly positive so when we were approached by Atlassian to build an add-on for the new Atlassian Connect for Bitbucket platform, we immediately got on board.

Atlassian Connect for Bitbucket

bitHound strives to work with developers in their existing workflows, delivering insights when needed. With our add-on for Atlassian Connect for Bitbucket, we can deliver on that promise. Review bitHound insights right in your repository without leaving Bitbucket.

Atlassian sees the pain point developers face with constant switching between tools that never seem to integrate seamlessly. As such, we are really excited they’ve brought Atlassian Connect for Bitbucket to market so bitHound can become part of that ecosystem to help developers build remarkable software.

Get started with the bitHound add-on

If you’re interested in getting started with the bitHound add-on, simply go to your Bitbucket settings and look for bitHound in the Find new add-ons section.

We’re thrilled about this integration. Stay tuned for more to come!

The new Bitbucket webhooks

By on June 24, 2015

Bitbucket webhooks are used by teams every day to test, analyze, deploy, and distribute great software to millions of people.

As Bitbucket webhooks are one of our most popular integration points, we’ve had the opportunity to gather lots of feedback regarding our webhook payloads, usage, and integrations.

We’ve listened to the community (check out public issues #7775, #5938, #4467, #6545 + more) and collaborated with CI vendors to make crucial improvements to this process.

We’re proud to announce the new Bitbucket webhooks.


The new webhooks can be accessed in your repository administration settings as shown in the image above. The webhooks provide a host of improvements over the previous, and soon-to-be deprecated “POST and Pull Request POST” hooks, which have now been renamed to “Services”.

Let’s look at some of the improvements and attributes of the new webhooks.

Fuller, more descriptive payload

Bitbucket webhooks now send more comprehensive information in the payload. For example, a repo:push event now includes detailed payload information about each and every reference that was updated:


Please visit our payload documentation for more examples of changes and improvements.

Better controls

We’ve added fine-grained control over the events you want to receive hooks for, such as repository, issue, and pull request events:


Improved troubleshooting

You can now troubleshoot malfunctioning webhooks more easily by reviewing the recent requests, including status codes and response times:



The new Bitbucket webhooks have been written from the ground up as a Connect add-on using our Atlassian Connect for Bitbucket platform, leveraging the same APIs for building powerful add-ons for extending Bitbucket.


This is just the beginning. We’ve got more features on the way, such as viewing request details (headers, event payloads, etc.), retrying requests, advanced queuing, and much more.

If you’re currently integrating with the old webhooks (renamed to “Services”), these will be deprecated soon. Please visit our payload documentation for the new payload descriptions.

Take the new Bitbucket webhooks for a spin – you can configure them in your repository settings. Are you inspired to build new, exciting integrations?  Clone our webhook-listener demo project to quickly get started with Bitbucket webhooks.

Atlassian Connect for Bitbucket: A new way to extend your workflow in the cloud

By on June 10, 2015

More than 3 million developers and 450,000 teams use Bitbucket to manage and collaborate on source code. But code collaboration is only a fraction of what software teams do on a daily basis to ship software.

Nowadays, shipping great software involves constant context switching using tools that don’t integrate tightly. Even when integrations are made, toolchains have to be painstakingly maintained on an ongoing basis with reams of messy bespoke integration code that has to be regularly re-written.

This is a challenge that development teams face every day. Most integration architectures available right now in the software industry only partially solve the problem. They only provide simple integration points that prevent teams from creating deeper integrations and a more unified workflow.

Not your average platform

To solve this problem, we’ve re-engineered Bitbucket into a platform that helps remove the interrupt-driven workflow and brings all the information to ship software in one place. Atlassian Connect for Bitbucket provides an integration architecture that embeds your add-ons right within the product UI creating a more unified workflow.

Here is a demo of code search enabled by the add-on built by Sourcegraph:


Why build using Atlassian Connect for Bitbucket?

If you’re still wondering why you should build an add-on using Atlassian Connect for Bitbucket, here are three reasons:

  1. Atlassian Connect is a next generation extensibility framework, providing much deeper integration than what is offered by standard REST APIs and webhooks.
  2. Add-ons are straightforward to implement. You can build an add-on in any language, on any stack, using any interface.
  3. You also can distribute your great add-ons to more than three million developers and 450,000 teams using Bitbucket.

Add-ons available for early preview

We couldn’t launch an integration platform without the help of the community. Here are previews of add-ons currently available on Bitbucket:

If you are currently a user of Bitbucket and want to take a sneak peak, click on your avatar, select “Manage Account”, and simply install these new add-ons by selecting “Find new add-ons” from the left menu.

Get started with Atlassian Connect for Bitbucket

It is now super-easy to extend Bitbucket so that you have the best workflow for your team. Click here for documentation to get started with Atlassian Connect for Bitbucket.

We look forward to seeing what exciting and interesting add-ons you build using Atlassian Connect for Bitbucket. Imagine the possibilities – happy developing!

Get Started

Bitbucket’s SSL certificate is changing for SHA-2

By on May 6, 2015

We’ll be replacing our main SSL certificate on May 8 at 00:00 UTC. The new certificate is signed with SHA-2, so Chrome and Firefox users will no longer see certificate warnings when they load any Bitbucket page.

Most users won’t notice the change, and won’t have to take any action. However, if you’re using Mercurial over HTTPS, you may see this error message:

abort: certificate for has unexpected fingerprint
(check hostfingerprint configuration)

If you see this error, you’ll need to update the host fingerprint for in your ~/.hgrc or Mercurial.ini configuration file:

[hostfingerprints] = 46:de:34:e7:9b:18:cd:7f:ae:fd:8b:e3:bc:f4:1a:5e:38:d7:ac:24

Thanks, and happy branching!

Mercurial: Onward and upward

By on April 30, 2015

Hi, I’m Sean, the newest member on the Bitbucket team. I currently work on Mercurial but come from a scientific background with the PETSc team. My responsibilities here are working on the backend but what I’m most excited about is improving Mercurial support.

I’ve been a contributor to Mercurial for about three years and have loved Mercurial for its human-friendly user interface and supportive community. Some of my work for Mercurial includes the addition of namespaces and improving the in-memory context object. I also wrote the experimental remotenames extension (to be added to core Mercurial in the future) and the most fun smb extension.

The future of Mercurial

In my time with Mercurial, I have seen it grow in fascinating ways. These include the concept of changeset evolution coming to life and the announcement of Facebook choosing Mercurial over Git. The future of Mercurial is that of scalability and because of that, I believe the best days of Mercurial are ahead.

Mercurial 3.4 Sprint at PyCon

Here at Bitbucket, with the support of the team, I’d like to build up relations with the community and the first step was attending the Mercurial 3.4 Sprint at PyCon in Montreal this year. There were many topics discussed: new manifest version, narrow checkouts, commit signing, obsolescence marker exchange, evolve UI, reflog equivalent, new path options, and remote bookmarks. Of these topics, manifests received the most attention. A new manifest format means we can enable checkouts of only a subdirectory (called a ‘narrow’ checkout). On top of that, it opens the door for only retrieving a truncated history (called a ‘shallow’ checkout). My personal favorites are the inclusion of remote bookmarks that will be built on top of the journal i.e. reflog equivalent, and the new path features i.e. the ability to define a custom revset for pushing to a particular path.

Here are some pictures from the event (photos by Ryan McElroy and me):




Celebrating Mercurial’s 10th anniversary

Now that I am here, with the support of Atlassian and the Bitbucket team, we will be improving relations with the Mercurial community by hosting many events this year. We begin with celebrating Mercurial’s 10th anniversary on Wed, May 6th by hosting the first official Bay Area Mercurial Meetup at Atlassian’s San Francisco office. We will have speakers from Google to talk about scaling Mercurial and Facebook to talk about why they picked Mercurial as the version control system and what this means for the future of Mercurial. Register immediately if you are interested since we can only accommodate 100 attendees. We look forward to seeing you next week with the rest of the Mercurial community.

[*Note: An earlier version had accidentally stated that Google had chosen Mercurial over Git but that is untrue. Google is working on Mercurial scalability, but also uses Git and contributes to Git development.]

Fare-thee-well, Digest access authentication

By on April 3, 2015


Today, we are deprecating support for Digest access authentication, or “Digest auth” on Bitbucket. Digest auth support is currently slated to be turned off on May 1st, 2015.

What is Digest authentication?

Digest auth (RFC-2617) is one of the older standardized methods of authenticating HTTP requests that was used to avoid sending a password in clear text, and to prevent replay attacks. Over unsecured channels it was (in the late 90s and early 00s) a much better approach than traditional Basic Auth. We have always offered Digest auth — currently under SSL only — as an alternative to Basic auth, but today very few users use it.

Why are we deprecating it?

Over the past couple of years, as SSL-only sites became the norm, having this end-to-end encryption has effectively made Digest auth obsolete. Today, Digest auth under SSL offers nothing over Basic Auth except added complexity and, in most cases, an additional round trip to request the necessary auth challenge.

Bitbucket has been SSL-only for years and we have been planning to deprecate Digest auth. In recent years, Bitbucket’s Digest auth support has been limited to select endpoints, and aimed at providing backwards compatibility with older clients only.

Next steps

As of May 1st, clients that exclusively support Digest auth will cease to work. This might affect some older curl-based scripts that use the `–digest` parameter. Simply removing that parameter will make curl use Basic auth (over SSL, of course) instead. For all users, we recommend using one of the more modern auth methods available.

OpenSSL Security Advisory

By on March 19, 2015

Bitbucket is not affected by the vulnerabilities announced by the OpenSSL project today. Two high severity security vulnerabilities CVE-2015-0291 and CVE-2015-0204 have been announced:

The CVE-2015-0291 vulnerability results in a potential denial of service attack against a server that requests a client’s certificate, which is not something that would happen in most circumstances as it is usually the client that requests the server’s certificate.

The CVE-2015-0204 vulnerability is a reclassification of the existing and well known FREAK vulnerability (CVE-2015-0204 & CVE-2015-1637), which allows an attacker to intercept HTTPS connections between vulnerable clients and servers and force them to use weakened encryption, which the attacker can break to steal or manipulate sensitive data.

Both vulnerabilities described in the OpenSSL security advisory posted at do not affect Bitbucket.

Snippets for teams are here with a rich set of APIs

By on March 18, 2015

Teams that use Bitbucket often want to share important information that isn’t part of their project repository – favorite regexes, config files, code snippets, homebrew recipes (beers, and the package manager). And yes – image, audio, video, and a host of other MIME types. Currently, there is no way to share such information via Bitbucket.

Snippets for teams

Today, we’re thrilled to announce Snippets, available now in Bitbucket,  to create and manage multi-file snippets of all kinds. We took a different approach than standard pastebin or gist – we built Snippets around teams. Snippets can be shared with your team, private to you, or fully public; you control read and write privileges. If you create a snippet owned by your team, the snippet will stay with the team forever, even after you leave that team.


Additional features

In Bitbucket, you’ll find a clean, easy interface to create, edit, version, and share Snippets. It’s media-friendly, supports drag-and-drop, and features syntax highlighting for over 90 programming languages.

Because Snippets are backed by Git or Mercurial repositories, power users can clone and edit them like any other distributed code repositories.

Rich set of APIs

You can use Snippets’ rich set of APIs to further extend functionality, and access the core set of features from desktop, mobile, and web apps. For example, this command line interface for creating, inspecting, and editing Bitbucket Snippets uses this python wrapper built on top of the Snippets API. For more info, please visit the Snippets API documentation: Snippets REST API

Snippets via command line

Most importantly, we have made it easy to create Snippets via the command line. Creating a snippet from your local file is just a single curl command:

$ curl -X POST{username or teamname} \
-u {username} -F file=@myawesomefile.txt

Got Snippets?

We hope you’re as excited as we are. We look forward to hearing from you in the comments below.