Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

atlassian-connect-express: Bitbucket app

In this article we will create a Bitbucket Cloud app using atlassian-connect-express.

Make sure that you installed nodejs on your computer.

You can find the source code for the article here.

You can find a video over here.

Create app

First of all you need to install atlassian-connect express with the following command:

npm i -g atlas-connect

Then let’s create a Bitbucket app:

atlas-connect new bb-test-app

You will see a question for which product to create the app:

Screenshot 2021-04-17 at 14.22.53.png

Choose Bitbucket and push enter. A new folder will be created in the current folder called bb-test-app.

Screenshot 2021-04-17 at 14.24.52.png

Have a look at the package.json file:

    "name": "my-app",
    "version": "0.0.1",
    "private": true,
    "scripts": {
        "start": "node -r esm app.js",
        "lint": "eslint app.js routes"
    "dependencies": {
        "atlassian-connect-express": "^6.6.0",
        "body-parser": "^1.19.0",
        "compression": "^1.7.4",
        "cookie-parser": "^1.4.5",
        "errorhandler": "^1.5.1",
        "esm": "^3.2.25",
        "express": "^4.17.1",
        "express-hbs": "^2.3.5",
        "morgan": "^1.10.0",
        "static-expiry": ">=0.0.11",
        "sequelize": "^6.6.2"
    "devDependencies": {
        "eslint": "^7.24.0"

You can see the required dependencies in the dependencies sections. The versions of these dependencies are not up to date. We make these versions be up to date with the ncu package. Install ncu package and execute:


In my case I have the following output:

Screenshot 2021-04-17 at 14.32.17.png

Now let’s install those dependencies:

npm install

All dependencies in the package.json will be installed.

Run app

Now execute:

npm start

In my case I have the following output:

Screenshot 2021-04-17 at 14.35.34.png

Ok. Let’s install sqlite3 manually:

npm install sqlite3

Now let’s try to run again:

npm start

This time the app is running

Screenshot 2021-04-17 at 14.40.02.png

Connect app to Bitbucket

Next we need to connect our app to Bitbucket. To do this you need Bitbucket to be able to access your app. During development process most developers do not have access from internet to their computers. That is why you can use ngrok to create a tunnel from internet to your computer. Install ngrok and run this command:

./ngrok http 3000

Screenshot 2021-04-17 at 14.43.31.png

You created a tunnel to port 3000 because by default your application runs on port 3000. This port is provided in the config.json file.

 "development": {
        // Port the Express server will listen on.
        "port": 3000,

Now take the url which I marked in red in the screenshot above and paste it for the localBaseUrl in the config.json file:

"localBaseUrl": ""

Rerun your app.

Now you are ready to connect your app to Bitbucket.

Open your Bitbucket workspace:

Screenshot 2021-04-17 at 14.55.13.png

In my case I have two workspaces. My personal workspace – Alexey Matveev and a team’s workspace = alex1mmmcprime. I will choose alex1mmmcprime:

Screenshot 2021-04-17 at 14.56.48.png

Choose settings:

Screenshot 2021-04-17 at 14.57.47.png

Choose Develop apps:

Screenshot 2021-04-17 at 14.58.44.png

Choose register app and paste the ngrok url you copied earlier:

Screenshot 2021-04-17 at 14.59.50.png

Push register app:

Screenshot 2021-04-17 at 15.00.39.png

And I have an error that an app with this key exists. Change the app key in the atlassian-connect.json to a key which should be unique. For example, I made it like this:

"key": "matveev-bb-test-app"

Push the register app button again. This time everything should work:

Screenshot 2021-04-17 at 15.03.54.png

If you have a look at the terminal where your app runs, you will see the following logs:

Screenshot 2021-04-17 at 15.04.29.png

It means Bitbucket queried your atlassian-connect.json. But your app is not yet installed. To install your app you need to click on the Installation Url:

Screenshot 2021-04-17 at 15.06.36.png

Choose the workspace you want to install the app and push Grant access:

Screenshot 2021-04-17 at 15.07.46.png

Now your app is installed. How to test it?

Test app

atlassian-connect.json file contains all modules which will be used in Bitbucket. We can see, for example, the webPanels module:

"webPanels": [
                "url": "/connect-example?repoPath={repository.full_name}",
                "name": {
                    "value": "Example Web Panel"
                "location": "org.bitbucket.repository.overview.informationPanel",
                "key": "example-web-panel"

This module provides our page in the source menu of any repo in our workspace:

Screenshot 2021-04-17 at 15.14.52.png

It means that our app was successfully installed and running.

Uninstall your app

To uninstall your app. Go to the workspace where you installed your app and open settings -> installed apps:

Screenshot 2021-04-17 at 15.22.41.png

Push the remove button:

Screenshot 2021-04-17 at 15.23.53.png

And you have an error – Something went wrong. What happened?

If we have a look at the terminal where our app runs, we will see the following error:

Screenshot 2021-04-17 at 15.24.53.png

It means that Bitbucket called the uninstalled method from our app but it was not found.

Let’s add the method.

Open routes/index.js and add these lines to the end:'/uninstalled', addon.authenticate(), function (req, res) {

Now rerun your app, install your app again and try to uninstall:

Screenshot 2021-04-17 at 15.29.24.png

This time. No errors. Everything worked.

That is all for this article.



Log in or Sign up to comment
AUG Leaders

Atlassian Community Events