Last updated Oct 28, 2024

App descriptor

The descriptor is a JSON object that provides the base upon which connect apps are built. The descriptor provides the structure, connection, and permissions for the app you develop.

Essentially when a user installs an app they are installing the JSON descriptor object.

We've broken up the descriptor from our example app into sections to describe all the elements of the descriptor in context. The full descriptor example is at the bottom of the page. It should not be considered an exhaustive list of all the available elements and properties.

Descriptor JSON schema

The descriptor format for apps is defined by a JSON schema and can be found here.

Key, name, description, and vendor elements

Element	Description	Required
`key`	A unique text string to identify the app	Yes
`name`	A text string with the name of the app for display	Yes
`description`	A sentence describing your app	Yes
`vendor`	The vendor field is available to show your company name and a URL. It has the following parameters: `name`: The name of your company or team. `url`: Any URL you choose to link to your company or team.	No

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "vendor": {
        "name": "Angry Nerds",
        "url": "https://www.example.com"
    },

baseUrl and authentication

Element	Description	Required
`baseUrl`	The root or base URL from which all other relative URL's will derive. Must be an https://-based URL.	Yes
`authentication`	The authentication method your app will use. It has the following parameter: `type`: must be either `jwt` or `none`	Yes

1
2
    "baseUrl": "https://example.com",
    "authentication": {
        "type": "jwt"
    },

lifecycle

Element	Description	Required
`lifecycle`	Each property in this object is a URL that can be absolute or relative to the app's baseUrl. When a lifecycle event is fired, Bitbucket will POST to the appropriate URL registered for the event. Can have one of the following values: `installed`: contains the URL or relative URL to POST to when the app is installed. `uninstalled`: contains the URL or relative URL to POST to when the app is uninstalled	Yes

1
2
    "lifecycle": {
        "installed": "/installed",
        "uninstalled": "/uninstalled"
    },

Scopes and contexts

Scopes define which access permissions your app will require or request from Bitbucket. The scopes here are just an example of how they might be applied in the descriptor, the full list of scopes is extensive and available at: Bitbucket Cloud REST API scopes.

Contexts here are app contexts which determine the level at which an app is visible and active once a user installs the app.

Element	Description	Required
`scopes`	Define the access permissions your app will require or request from Bitbucket. Has the following parameters: `account`: Ability to see all the user's account information. Note that this does not include any ability to mutate any of the data. `repository`: read access to all the repositories the authorizing user has access to. Note that this scope does not give access to a repository's pull requests.	Yes
`contexts`	App contexts determine the account level at which an app is installed. Can have one of the following values: `account`: the app will be visible in all the locations that the owner of the installing account has access. `individual`: the app will only be visible to the owner of the individual account.	Yes

1
2
    "scopes": ["account", "repository"],
    "contexts": ["account"]
}

modules

Modules are the specific integration points implemented by your app. These include UI elements like pages, web panels, and web items. Other types of modules do not modify the Bitbucket UI, but describe how your app interacts programmatically with Bitbucket, such as webhooks and Oauth consumers.

1
2
    "modules": {
        "oauthConsumer": {
            "clientId": "{{consumerKey}}"
        },
        "webhooks": [
            {
                "event": "*",
                "url": "/webhook"
            }
        ],
        "webItems": [
            {
                "url": "http://example.com?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Web Item"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-web-item",
                "params": {
                    "auiIcon": "aui-iconfont-link"
                }
            }
        ],
        "repoPages": [
            {
                "url": "/connect-example?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Page"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-repo-page",
                "params": {
                    "auiIcon": "aui-iconfont-doc"
                }
            }
        ],
        "webPanels": [
            {
                "url": "/connect-example?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Web Panel"
                },
                "location": "org.bitbucket.repository.overview.informationPanel",
                "key": "example-web-panel"
            }
        ]
    },
}

Complete descriptor example

Our example app descriptor provides a good example of all the required parts of the descriptor you will need to construct for your app.

1
2
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "vendor": {
        "name": "Angry Nerds",
        "url": "https://www.atlassian.com/angrynerds"
    },
    "baseUrl": "https://example.com",
    "authentication": {
        "type": "jwt"
    },
    "lifecycle": {
        "installed": "/installed",
        "uninstalled": "/uninstalled"
    },
    "modules": {
        "oauthConsumer": {
            "clientId": "{{consumerKey}}"
        },
        "webhooks": [
            {
                "event": "pullrequest:created",
                "url": "/webhook"
            },
            {
                "event": "pullrequest:updated",
                "url": "/webhook"
            },
            {
                "event": "pullrequest:fulfilled",
                "url": "/webhook"
            }
        ],
        "webItems": [
            {
                "url": "http://example.com?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Web Item"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-web-item",
                "params": {
                    "auiIcon": "aui-iconfont-link"
                }
            }
        ],
        "repoPages": [
            {
                "url": "/connect-example?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Page"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-repo-page",
                "params": {
                    "auiIcon": "aui-iconfont-doc"
                }
            }
        ],
        "webPanels": [
            {
                "url": "/connect-example?repoUuid={repository.uuid}",
                "name": {
                    "value": "Example Web Panel"
                },
                "location": "org.bitbucket.repository.overview.informationPanel",
                "key": "example-web-panel"
            }
        ]
    },
    "scopes": ["account", "repository", "pullrequest"],
    "contexts": ["account"]
}