Summary

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

Environment

Bitbucket Server or Data Center

Diagnosis

Bitbucket Server/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 be helpful to automate some of the tasks associated to 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.

   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.

   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.

   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.

   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.

   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.

   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 the Installing a Marketplace App using the REST API Section.

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.