Automating the installing, uninstalling, upgrading and downgrading of Marketplace apps on Bitbucket Server or Data Center using REST API

Summary

Install, uninstall, upgrade, and downgrade the Marketplace apps using Bitbucket REST API.

Environment

Bitbucket Data Center

Diagnosis

Bitbucket Data Center REST API is useful to the Bitbucket administrator to automate some tasks.

The Universal Plugin Manager (UPM) has a set of API methods that may help automate some of the tasks associated with Marketplace Apps (aka Plugins or Addons) administration.

Cause

Apart from the two methods of install the app from Marketplace or install the app from file as described in Installing Marketplace Apps.

If Bitbucket system is not connected to the internet (Marketplace Apps), you can write a script to automate marketplace plugins install, uninstall, upgrade or downgrade for Bitbucket using REST API.

Solution

The following Sections will show an example of using the UPM REST API to perform a few tasks. You may also want to check the Atlassian Marketplace REST API.

These examples were coded using shell script, but you may port it to your preferred coding language.

Some of the shell commands use jq to parse the output data.

Installing a Marketplace App using the REST API

 Here we are installing Security for Bitbucket version 2.1.0, which is not the latest version.

1. Download the App .jar/.obr file from the Marketplace.

   1 2 3 4 export APP_FILE_PATH=/tmp/security-for-bitbucket-2.1.0.jar curl -k -L -o ${APP_FILE_PATH} https://marketplace.atlassian.com/download/apps/1221399/version/200100010 ls -la ${APP_FILE_PATH}; file ${APP_FILE_PATH}

2. Get the UPM token, which is necessary on the next step.

   1 2 3 4 5 6 7 export BITBUCKET_SERVER_URL=http://localhost:21310 export BITBUCKET_SERVER_CONTEXT_PATH=/b61310 export ADMIN_USRNAME=admin export ADMIN_PWD=admin BITBUCKET_BASE_URL=$BITBUCKET_SERVER_URL$BITBUCKET_SERVER_CONTEXT_PATH UPM_TOKEN=$(curl -I --user $ADMIN_USRNAME:$ADMIN_PWD -H 'Accept: application/vnd.atl.plugins.installed+json' $BITBUCKET_BASE_URL'/rest/plugins/1.0/?os_authType=basic' 2>/dev/null | grep 'upm-token' | cut -d " " -f 2 | tr -d '\r')

3. Install the App.

   1 curl --user ${ADMIN_USRNAME}:${ADMIN_PWD} -H 'Accept: application/json' ${BITBUCKET_BASE_URL}'/rest/plugins/1.0/?token='${UPM_TOKEN} -F plugin=@${APP_FILE_PATH}{{}}

4. Check if the App was properly installed.

   1 2 3 export APP_NAME="Security for Bitbucket" curl --user $ADMIN_USRNAME:$ADMIN_PWD $BITBUCKET_BASE_URL/rest/plugins/latest/ 2>/dev/null | jq -r '.plugins[] | select(.name | contains("'${APP_NAME}'"))'

Uninstalling a Marketplace App using the REST API

In this example, we are uninstalling the same App that was installed in the previous Section.

1. Get the App key.

   1 2 3 4 5 6 7 BITBUCKET_SERVER_URL=http://localhost:21310 BITBUCKET_SERVER_CONTEXT_PATH=/b61310 ADMIN_USRNAME=admin ADMIN_PWD=admin   APP_NAME="Security for Bitbucket" APP_KEY=$(curl --user $ADMIN_USRNAME:$ADMIN_PWD $BITBUCKET_BASE_URL/rest/plugins/latest/2>/dev/null| jq -r'.plugins[] | select(.name | contains("'${APP_NAME}'")) | "\(.key)"')

2. Uninstall the App; a HTTP 204 response means it was uninstalled.

   1 curl -I --user ${ADMIN_USRNAME}:${ADMIN_PWD} -H 'Accept: application/json' -X DELETE ${BITBUCKET_BASE_URL}'/rest/plugins/1.0/'${APP_KEY}'-key' 2>/dev/null

Upgrading a Marketplace App using the REST API

To upgrade an existing App you may download a more recent version from the Atlassian Marketplace and follow the same procedure described in theInstalling a Marketplace App using the REST APISection.

Downgrading a Marketplace App using the REST API

Directly downgrading an App isn't possible, not even from the UPM UI.

In this case, you need to follow these steps:

1. Uninstall the current installed version.

2. Download an old, target version of the App.

3. Install the target version of the App.