Refs - Update Refs

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
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

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

transfer-Encoding: chunked
{
  "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

Name Description
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