statuses/build Resource

This resource manages build statuses on a commit. When someone makes a commit on a Bitbucket Cloud repository, the vendor or build system runs the build and displays the build status on the commit, on the branch with the commit, and on the pull request with the commit. Because a single commit can involve multiple builds, the commit can have more than one build status.

GET the build status for a commit

Returns the status for specific build associated with a commit.

For OAuth consumers, the GET endpoint requires the repository scope. This URL includes the following parameters:

Parameter Description
owner The account of the repository owner.
repo_slug The repository name.
revision The SHA1 value for the commit where you want to retrieve the build status.
key The key that distinguishes the build status from other statuses associated with the same commit. The vendor or system that generates the build status provides this key.
GET  https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/commit/{revision}/statuses/build/{key}
Click to expand and view a response
{
    "state": "SUCCESSFUL",
    "type": "build",
    "key": "BAMBOO-PROJECT-X",
    "name": "Build #34",
    "url": "https://example.com/path/to/build",
    "description": "Changes by John Doe",
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466/statuses/build/BAMBOO-PROJECT-X"
        },
        "commit": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466"
        }
    }
}

POST a build status for a commit

Adds a build status to a commit. If the build is already associated with the commit, a POST also updates the status. During an update, Bitbucket replaces the status that previously displayed.

For OAuth consumers, the POST endpoint requires the repository:write scope. This URL includes the following parameters:

Parameter Description
owner The account of the repository owner.
repo_slug The repository name.
revision The SHA1 value for the commit where you want to add the build status.

The POST request body includes the following fields:

Parameter Required Description
state Yes

An indication of the status of the commit:

  • INPROGRESS indicates that a build for the commit is in progress but not yet complete.
  • SUCCESSFUL indicates that a build for the commit completed successfully.
  • FAILED indicates that a build for the commit failed.
key Yes

A key that the vendor or build system supplies to identify the submitted build status. Because a single commit can involve multiple builds, the key needs to be unique compared to other builds associated with the commit.

For example, BAMBOO-PROJECT-X or JENKINS-BUILD-5.

name No The name of the build. Your build system may provide the name, which will also appear in Bitbucket. For example, Unit Tests.
url Yes The URL for the vendor or system that produces the build.
description No A user-defined description of the build. For example, 4 out of 128 tests passed.
POST  https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/commit/{revision}/statuses/build
Click to expand and view a request and response

Request

{
    "state": "SUCCESSFUL",
    "key": "BAMBOO-PROJECT-X",
    "name": "Build #34",
    "url": "https://example.com/path/to/build/info",
    "description": "Changes by John Doe"
}

Response

{
    "state": "SUCCESSFUL",
    "type": "build",
    "key": "BAMBOO-PROJECT-X",
    "name": "Build #34",
    "url": "https://example.com/path/to/build",
    "description": "Changes by John Doe",
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466/statuses/build/BAMBOO-PROJECT-X"
        },
        "commit": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466"
        }
    }
}

PUT a build status for a commit

Updates the build status for a commit. During an update, Bitbucket replaces the status that previously displayed. For example, a build that previously failed could appear as a success after an update. In that case, the failed status no longer appears.

For OAuth consumers, the PUT endpoint requires the repository:write scope. This URL includes the following parameters:

Parameter Description
owner The account of the repository owner.
repo_slug The repository name.
revision The SHA1 value for the commit where you want to update the build status.
key The key that distinguishes the build status from other builds associated with the same commit. The vendor or system that generates the build status provides this key.

The PUT request body includes the following fields:

Parameter Required Description
state Yes

An indication of the status of the commit:

  • INPROGRESS indicates that a build for the commit is in progress but not yet complete.
  • SUCCESSFUL indicates that a build for the commit completed successfully.
  • FAILED indicates that a build for the commit failed.
name No The name of the build. Your build system may provide the name, which will also appear in Bitbucket. For example, Unit Tests.
url Yes The URL for the vendor or system that produces the build.
description No A user-defined description of the build. For example, 4 out of 128 tests passed.
PUT  https://api.bitbucket.org/2.0/repositories/{owner}/{repo_slug}/commit/{revision}/statuses/build/{key}
Click to expand and view a request and response

Request

{
    "state": "SUCCESSFUL",
    "name": "Build #34",
    "url": "https://example.com/path/to/build/info",
    "description": "Changes by John Doe"
}

Response

{
    "state": "SUCCESSFUL",
    "type": "build",
    "key": "BAMBOO-PROJECT-X",
    "name": "Build #34",
    "url": "https://example.com/path/to/build",
    "description": "Changes by John Doe",
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466/statuses/build/BAMBOO-PROJECT-X"
        },
        "commit": {
            "href": "https://api.bitbucket.org/2.0/repositories/emmap1/MyRepo/commits/61d9e64348f9da407e62f64726337fd3bb24b466"
        }
    }
}
Last modified on Nov 16, 2015

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.