Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Server

Bitbucket Data Center / / Modules

Sync

Operations

GET/sync/latest/projects/{projectKey}/repos/{repositorySlug}POST/sync/latest/projects/{projectKey}/repos/{repositorySlug}POST/sync/latest/projects/{projectKey}/repos/{repositorySlug}/synchronize

GET

Get sync latest projects {projectKey} repos {repositorySlug}

Retrieves the synchronization status for the specified repository. In addition to listing refs which cannot be synchronized, if any, the status also provides the timestamp for the most recent synchronization and indicates whether synchronization is available and enabled. If "?at" is specified in the URL, the synchronization status for the specified ref is returned, rather than the complete repository status.

The authenticated user must have REPO_READ permission for the repository, or it must be public if the request is anonymous. Additionally, after synchronization is enabled for a repository, meaning synchronization was available at that time, permission changes and other actions can cause it to become unavailable. Even when synchronization is enabled, if it is no longer available for the repository it will not be performed.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

string

Responses

Synchronization status for the specified repository, or specific ref within that repository.

application/json

RestRefSyncStatus

GET/sync/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/sync/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json'

200Response

{
  "aheadRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "divergedRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "lastSync": 1331038800000,
  "orphanedRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "enabled": true,
  "available": true
}

POST

Post sync latest projects {projectKey} repos {repositorySlug}

Enables or disables synchronization for the specified repository. When synchronization is enabled, branches within the repository are immediately synchronized and the status is updated with the outcome. That initial synchronization is performed before the REST request returns, allowing it to return the updated status.

The authenticated user must have REPO_ADMIN permission for the specified repository. Anonymous users cannot manage synchronization, even on public repositories. Additionally, synchronization must be available for the specified repository. Synchronization is only available if:

The repository is a fork, since its origin is used as upstream
The owning user still has access to the fork's origin, if the repository is a personalfork

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request bodyapplication/json

enabled

boolean

Responses

The updated synchronization status for the repository, after enabling synchronization. 204 NO CONTENT is returned instead after disabling synchronization.

application/json

RestRefSyncStatus

POST/sync/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/sync/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": true
}'

200Response

{
  "aheadRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "divergedRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "lastSync": 1331038800000,
  "orphanedRefs": {
    "tag": true,
    "state": "AHEAD",
    "displayId": "master",
    "id": "refs/heads/master",
    "type": "BRANCH"
  },
  "enabled": true,
  "available": true
}

POST

Post sync latest projects {projectKey} repos {repositorySlug} synchronize

Allows developers to apply a manual operation to bring a ref back in sync with upstream when it becomes out of sync due to conflicting changes. The following actions are supported:

MERGE: Merges in commits from the upstream ref. After applying this action, the synchronized ref will be AHEAD (as it still includes commits that do not exist upstream.
- This action is only supported for DIVERGED refs
- If a "commitMessage" is provided in the context, it will be used on the merge commit. Otherwise a default message is used.
DISCARD: Throws away local changes in favour of those made upstream. This is a destructive operation where commits in the local repository are lost.
- No context entries are supported for this action
- If the upstream ref has been deleted, the local ref is deleted as well
- Otherwise, the local ref is updated to reference the same commit as upstream, even if the update is not fast-forward (similar to a forced push)

The authenticated user must have REPO_WRITE permission for the specified repository. Anonymous users cannot synchronize refs, even on public repositories. Additionally, synchronization must be enabled and available for the specified repository.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request bodyapplication/json

action

string

context

Context

refId

string

Responses

The requested action was successfully performed, and has updated the ref's state, but the ref if is still not in sync with upstream. For example, after applying the MERGE action, the ref will still be AHEAD of upstream. If the action brings the ref in sync with upstream, 204 NO CONTENT is returned instead.

application/json

RestRejectedRef

POST/sync/latest/projects/{projectKey}/repos/{repositorySlug}/synchronize

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/sync/latest/projects/{projectKey}/repos/{repositorySlug}/synchronize' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "action": "MERGE",
  "context": {
    "commitMessage": "Merging in latest from upstream."
  },
  "refId": "refs/heads/master"
}'

200Response

{
  "tag": true,
  "state": "AHEAD",
  "displayId": "master",
  "id": "refs/heads/master",
  "type": "BRANCH"
}