atlassian-connect-express: Bitbucket app

[#1]

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:

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

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:

ncu

In my case I have the following output:

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:

Ok. Let’s install sqlite3 manually:

npm install sqlite3

Now let’s try to run again:

npm start

This time the app is running

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

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": "https://e5ea3761696e.ngrok.io"

Rerun your app.

Now you are ready to connect your app to Bitbucket.

Open your Bitbucket workspace:

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

Choose settings:

Choose Develop apps:

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

Push register app:

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:

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

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:

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

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:

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:

Push the remove button:

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:

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:

app.post('/uninstalled', addon.authenticate(), function (req, res) {
        res.send(200)
    })

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

This time. No errors. Everything worked.

That is all for this article.