Refs - Update Refs

Reference

Service:: Git

API Version:: 5.0

Creating, updating, or deleting refs(branches).

Updating a ref means making it point at a different commit than it used to. You must specify both the old and new commit to avoid race conditions.

POST https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/refs?api-version=5.0

With optional parameters:

POST https://dev.azure.com/{organization}/{project}/_apis/git/repositories/{repositoryId}/refs?projectId={projectId}&api-version=5.0

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
repositoryId	path	True	string	The name or ID of the repository.
project	path		string	Project ID or project name
api-version	query	True	string	Version of the API to use. This should be set to '5.0' to use this version of the api.
projectId	query		string	ID or name of the team project. Optional if specifying an ID for repository.

Request Body

Name	Type	Description
body	GitRefUpdate[]	List of ref updates to attempt to perform

Responses

Name	Type	Description
200 OK	GitRefUpdateResult[]	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.code_write	Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage pull requests and code reviews and to receive notifications about version control events via service hooks.

Examples

Create/Update/Delete a ref by repositoryId

Sample Request

HTTP

POST https://dev.azure.com/fabrikam/_apis/git/repositories/{repositoryId}/refs?api-version=5.0

[
  {
    "name": "refs/heads/vsts-api-sample/answer-woman-flame",
    "oldObjectId": "0000000000000000000000000000000000000000",
    "newObjectId": "ffe9cba521f00d7f60e322845072238635edb451"
  }
]

Sample Response

Status code:: 200

transfer-Encoding: chunked

Response Body

{
  "value": [
    {
      "repositoryId": "d3d1760b-311c-4175-a726-20dfc6a7f885",
      "name": "refs/heads/vsts-api-sample/answer-woman-flame",
      "oldObjectId": "0000000000000000000000000000000000000000",
      "newObjectId": "ffe9cba521f00d7f60e322845072238635edb451",
      "isLocked": false,
      "updateStatus": "succeeded",
      "success": true
    }
  ],
  "count": 1
}

Definitions

GitRefUpdate
GitRefUpdateResult
GitRefUpdateStatus	Status of the update from the TFS server.

GitRefUpdate

Name	Type	Description
isLocked	boolean
name	string
newObjectId	string
oldObjectId	string
repositoryId	string

GitRefUpdateResult

Name	Type	Description
customMessage	string	Custom message for the result object For instance, Reason for failing.
isLocked	boolean	Whether the ref is locked or not
name	string	Ref name
newObjectId	string	New object ID
oldObjectId	string	Old object ID
rejectedBy	string	Name of the plugin that rejected the updated.
repositoryId	string	Repository ID
success	boolean	True if the ref update succeeded, false otherwise
updateStatus	GitRefUpdateStatus	Status of the update from the TFS server.

GitRefUpdateStatus

Status of the update from the TFS server.

Name	Type	Description
createBranchPermissionRequired	string	The ref update request could not be completed because the user lacks the permission to create a branch
createTagPermissionRequired	string	The ref update request could not be completed because the user lacks the permission to create a tag
forcePushRequired	string	Indicates that the ref update request could not be completed because part of the graph would be disconnected by this change, and the caller does not have ForcePush permission on the repository.
invalidRefName	string	Indicates that the ref update request could not be completed because the ref name presented in the request was not valid.
locked	string	The ref update could not be completed because the ref is locked by another user.
manageNotePermissionRequired	string	The ref update request could not be completed because the user lacks note creation permissions required to write this note
refNameConflict	string	The ref update could not be completed because, in case-insensitive mode, the ref name conflicts with an existing, differently-cased ref name.
rejectedByPlugin	string	The ref update could not be completed because it was rejected by the plugin.
rejectedByPolicy	string	The ref update could not be completed because it was rejected by policy.
staleOldObjectId	string	Indicates that the ref update request could not be completed because the old object ID presented in the request was not the object ID of the ref when the database attempted the update. The most likely scenario is that the caller lost a race to update the ref.
succeeded	string	Indicates that the ref update request was completed successfully.
succeededCorruptRef	string	Indicates that the ref update request was completed successfully, but the passed-in ref was corrupt - as in, the old object ID was bad. This should only happen during deletes.
succeededNonExistentRef	string	Indicates that the ref update request was completed successfully, but the ref doesn't actually exist so no changes were made. This should only happen during deletes.
unprocessed	string	The request was not processed
unresolvableToCommit	string	The ref update request could not be completed because the new object ID for the ref could not be resolved to a commit object (potentially through any number of tags)
writePermissionRequired	string	The ref update request could not be completed because the user lacks write permissions required to write this ref