Automating the installing, uninstalling, upgrading and downgrading of Marketplace apps on Bitbucket Server or Data Center using REST API
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
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.
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}
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')
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}{{}}
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.
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)"')
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:
Uninstall the current installed version.
Download an old, target version of the App.
Install the target version of the App.
Was this helpful?