Last updatedJul 17, 2019

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.

Key, name, description, and vendor elements

ElementDescriptionRequired
keyA unique text string to identify the appYes
nameA text string with the name of the app for displayYes
descriptionA sentence describing your appYes
vendorThe 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
3
4
5
6
7
8
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "vendor": {
        "name": "Angry Nerds",
        "url": "https://www.example.com"
    },

baseUrl and authentication

ElementDescriptionRequired
baseUrlThe root or base URL from which all other relative URL's will derive. Must be an https://-based URL.Yes
authenticationThe authentication method your app will use.
It has the following parameter:
  • type: must be either jwt or none
Yes
1
2
3
4
    "baseUrl": "https://example.com",
    "authentication": {
        "type": "jwt"
    },

lifecycle

ElementDescriptionRequired
lifecycleEach 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
3
4
    "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.

ElementDescriptionRequired
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
contextsApp 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
3
    "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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
    "modules": {
        "oauthConsumer": {
            "clientId": "{{consumerKey}}"
        },
        "webhooks": [
            {
                "event": "*",
                "url": "/webhook"
            }
        ],
        "webItems": [
            {
                "url": "http://example.com?repoPath={repo_path}",
                "name": {
                    "value": "Example Web Item"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-web-item",
                "params": {
                    "auiIcon": "aui-iconfont-link"
                }
            }
        ],
        "repoPages": [
            {
                "url": "/connect-example?repoPath={repo_path}",
                "name": {
                    "value": "Example Page"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-repo-page",
                "params": {
                    "auiIcon": "aui-iconfont-doc"
                }
            }
        ],
        "webPanels": [
            {
                "url": "/connect-example?repoPath={repo_path}",
                "name": {
                    "value": "Example Web Panel"
                },
                "location": "org.bitbucket.repository.overview.informationPanel",
                "key": "example-web-panel"
            }
        ]
    },
}

Definitions

The definitions section of the descriptor enables application developers to define their own object schemas. Currently the only place such schemas can be used is when they're referenced from a custom event.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
    "definitions": {
        "com.example.app:myobject": {
            "type": "object",
            "description": "An object",
            "properties": {
                "my-property": {
                    "type": "string",
                    "description": "A property",
                    "required": true
                },
                "repository": {
                    "$ref": "#/definitions/repository"
                }
            }
        }
    }

Definition schemas should use JSON Schema Draft 4 syntax. They may reference other definitions created by the application, or even native Bitbucket object types like repository.

Prefix object definition keys with the key of the application in order to namespace the definitions, since validation will ensure that this is happening.

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
    "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": "*",
                "url": "/webhook"
            }
        ],
        "webItems": [
            {
                "url": "http://example.com?repoPath={repo_path}",
                "name": {
                    "value": "Example Web Item"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-web-item",
                "params": {
                    "auiIcon": "aui-iconfont-link"
                }
            }
        ],
        "repoPages": [
            {
                "url": "/connect-example?repoPath={repo_path}",
                "name": {
                    "value": "Example Page"
                },
                "location": "org.bitbucket.repository.navigation",
                "key": "example-repo-page",
                "params": {
                    "auiIcon": "aui-iconfont-doc"
                }
            }
        ],
        "webPanels": [
            {
                "url": "/connect-example?repoPath={repo_path}",
                "name": {
                    "value": "Example Web Panel"
                },
                "location": "org.bitbucket.repository.overview.informationPanel",
                "key": "example-web-panel"
            }
        ]
    },
    "scopes": ["account", "repository"],
    "contexts": ["account"]
}