Bitbucket Cloud Developer

Bitbucket Cloud Developer

Last updatedApr 13, 2021

Rate this page:

Access to context parameters

To use context parameters in a descriptor the corresponding scopes should be provided. If the required scopes are not specified the context parameters won’t be replaced.

Please refer to the table to see required scopes for each context parameter:

Context parameterRequired scopeExample
useraccount
  • user.username
target_useraccount
  • target_user.username
workspaceaccount
  • workspace.slug
principalaccount
  • principal.uuid
repositoryrepository
  • repository.uuid
  • repository.owner.uuid
branchrepository
  • branch.name
commitrepository
  • commit.hash
filerepository
  • file.name
  • file.commit.hash
directoryrepository
  • directory.links.self.href
pullrequestpullrequest
  • pullrequest.to_repository.owner.uuid
  • pullrequest.destination.branch.name
snippetsnippet
  • snippet.name
issueissue
  • issue.key

Certain conditions will also require an additional scope according to the table bellow:

Condition keyRequired scope
has_account_permissionaccount
has_permissionrepository
has_workspace_permissionaccount
has_issue_permissionrepository
meets_access_requirementsaccount
property_existsrepository
has_filerepository
scmrepository
user_has_premiumaccount
has_addonaccount
flag_is_activeaccount
has_featureaccount

Examples

Context parameters in a URL

In this example, we used context parameters repository.uuid and pullrequest.id. According to the table, we need to provide repository and pullrequest scopes to populate context data in the url.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/selectTarget?repository={repository.uuid}&pr={pullrequest.id}",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ] 
    },
    "scopes": ["repository", "pullrequest"]
}

NOTE: In this example you can also provide pullrequest scope only as it implies repository.

Multiple context objects in one context parameter

In the url below, we reference several context objects in one context parameter - repository, app and user. app doesn't require a scope, so we need to add just repository and account scopes to the descriptor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/url?enabled=repository.properties.get(attribute=app.key).enabled.get(attribute=user.uuid)",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ] 
    },
    "scopes": ["repository", "account"]
}

Context parameters in conditions

Context parameters used in a condition also requires a scope. In this example, we used repository.owner.uuid as a condition target and user.uuid as a condition value. So we should add repository and account scopes to the descriptor.

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
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "conditions": [
                    {
                        "condition": "equals",
                        "target": "repository.owner.uuid",
                        "params": {
                            "value": {
                                "eval": "user.uuid"
                            }       
                        }                 

                    }
                ]     
            }
        ] 
    },
    "scopes": ["repository", "account"]
}

Inline conditions

In this example, we access a repository context data and use has_account_permission condition so required scopes are repository and account

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "url": "/url?is_admin={repository.owner.has_account_permission(permission=\"admin\")}",
                "location": "org.bitbucket.pullrequest.summary.actions",
                "key": "webItem-example",
                "name": {
                    "value": "WebItem example"
                }
            }
        ] 
    },
    "scopes": ["repository", "account"]
}

Module condition section

In this example we use multiple conditions:

  1. equals condition requires repository and account scopes to access context data.
  2. user_has_premium condition requires account scope.
  3. has_addon condition requires account scope to evaluate condition and repository scope to substitute target

As a result, repository and account scopes should be provided in the scope section.

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
{
    "key": "example-app",
    "name": "Example App",
    "description": "An example app for Bitbucket",
    "baseUrl": "https://www.example.com",
    "modules": {
        "webItems": [
            {
                "conditions": [
                    {
                        "condition": "equals",
                        "target": "repository.owner.uuid",
                        "params": {
                            "value": {
                                "eval": "user.uuid"
                            }       
                        }                 
                    },
                    {
                        "condition": "user_has_premium"
                    },
                    {
                        "condition": "has_addon",
                        "target": "repository.owner",
                        "params": {
                            "key": "my-addon"
                        },
                        "invert": true             
                    }
                ]     
            }
        ] 
    },
    "scopes": ["repository", "account"]
}

Rate this page: