links Resources

Overview

Links connect your commit messages and code comments directly to your JIRA issue tracker or Bamboo build server. You can also create custom link resources. The links resource supplies functionality for adding, updating, removing, and viewing links associated with your repositories. Links have the following fields:

Field Description
id A unique id assigned by Bitbucket.
handler

A profile of representing one of the following handler types:

  • Jira
  • Bamboo
  • Cruicible
  • Jenkins
  • Custom

The content of the handler profile depends on whether the handler is a known type or a custom type. The known types of handlers have the following fields:

Field Description
url The location of the service. This can start with
display_from Include references to capture groups with the syntax \1, \2, etc.
name The handler name.
key A value identifying the project on the specified url.
display_to A value created by the Bitbucket service from the url.

A custom handler has the following fields:

Field Description
display_to The display name of the service.
replacement_url Include references to capture groups with the syntax \1, \2, etc.
raw_regex Include capture groups for use in your link url.
name The handler name.
display_from The display URL.

The DVCS connector creates a custom handler.

Gets an array containing the links associated with a repository. The caller must authenticate as a user with administrative access to the repository. The caller can specify the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
  Click here to expand...
[
    {
        "handler": {
            "display_to": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse/\\1",
            "replacement_url": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse/\\1",
            "raw_regex": "(?<!\\w)([A-Z|a-z]{2,}-\\d+)(?!\\w)",
            "name": "custom",
            "display_from": "Custom ((?<!\\w)([A-Z|a-z]{2,}-\\d+)(?!\\w))"
        },
        "id": 25991
    },
    {
        "handler": {
            "url": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse",
            "display_from": "JIRA (PROJ)",
            "name": "jira",
            "key": "PROJ",
            "display_to": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse"
        },
        "id": 34053
    }
]

Gets an individual link on a repository. The caller must authenticate as a user with administrative access to the repository. The caller can specify the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The link id.
GET https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/links/{object_id}
  Click here to expand...
{
        "handler": {
            "display_to": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse/\\1",
            "replacement_url": "http://172-28-13-105.staff.sf.atlassian.com:2990/jira/browse/\\1",
            "raw_regex": "(?<!\\w)([A-Z|a-z]{2,}-\\d+)(?!\\w)",
            "name": "custom",
            "display_from": "Custom ((?<!\\w)([A-Z|a-z]{2,}-\\d+)(?!\\w))"
        },
       "id": 25991
}

Creates a new link on the repository. The following parameters are supported:

Parameter Required Description
handler Yes

Valid values for the handler parameter are:

  • jira
  • bamboo
  • crucible
  • jenkins
  • custom
accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
link_url Yes A valid URL that starts with either http or https. This parameter describes the URL at which your application exists. This value must be unique among all the repository links.
link_key Yes

A non-empty string. This parameter is the project key that you are trying to link to. For example if you are linking to JIRA and your project key is MYPROJ then the value should be MYPROJ.

If you are creating a custom link, this value contains a regular expression that matches the key.

The caller must authenticate as a user with administrative access to the repository.

  Click here to expand...
$ curl --request POST --user mcatalbas:password 'https://bitbucket.org/!api/1.0/repositories/bitbucket/staging/links/' 
{
    "handler": {
        "url": "http://yourjira.com/",
        "display_from": "JIRA (PROJ)",
        "name": "jira",
        "key": "PROJ",
        "display_to": "http://yourjira.com/"
    },
    "id": 87
}

Update a repository link. The following parameters are supported:

Parameter Required? Description
link_url Yes A valid URL that starts with either http or https. This parameter describes the URL at which your application exists. This value must be unique among all the repository links.
link_key Yes A non-empty string. This parameter is the project key that you are trying to link to. For example if you are linking to JIRA and your project key is MYPROJ then the value should be MYPROJ.
accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.

The caller must authenticate as a user with administrative access to the repository. 

{
    "handler": {
        "url": "http://yourjira.com/",
        "display_from": "JIRA (BB)",
        "name": "jira",
        "key": "BB",
        "display_to": "http://yourjira.com/"
    },
    "id": 87
}

Deletes the repository link identified by the object_id. The caller must authenticate as a user with administrative access to the repository. The caller can specify the following parameters:

Parameter

Required?

Description

accountname Yes The team or individual account owning the repository.
repo_slug Yes The repository identifier.
object_id Yes The component identifier.
DELETE https://api.bitbucket.org/1.0/repositories/{accountname}/{repo_slug}/links/{object_id}

When this call succeeds it returns:

HTTP/1.1 204 NO CONTENT

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport