Reverts - Create

Service:

Git

API Version:

7.1

Starts the operation to create a new branch which reverts changes introduced by either a specific commit or commits that are associated to a pull request.

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

URI Parameters

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

Request Body

Name	Type	Description
generatedRefName	string	Proposed target branch name for the cherry pick or revert operation.
ontoRefName	string	The target branch for the cherry pick or revert operation.
repository	GitRepository	The git repository for the cherry pick or revert operation.
source	GitAsyncRefOperationSource	Details about the source of the cherry pick or revert operation (e.g. A pull request or a specific commit).

Responses

Name	Type	Description
200 OK	GitRevert	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_manage	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 code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks.

Examples

Sample request

HTTP

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

{
  "repository": {
    "id": "9a6b6a4a-83df-47ab-8c2a-07742cede4cb",
    "name": "FabrikamOps",
    "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb",
    "project": {
      "id": "0807fc91-4393-482d-9e23-defdbb7d0857",
      "name": "Test1",
      "url": "https://dev.azure.com/fabrikam/_apis/projects/0807fc91-4393-482d-9e23-defdbb7d0857",
      "state": "wellFormed",
      "revision": 165
    },
    "defaultBranch": "refs/heads/master",
    "remoteUrl": "https://dev.azure.com/fabrikam/Test1/_git/FabrikamOps"
  },
  "source": {
    "commitList": [
      {
        "commitId": "4388fbc9e8511520a9ae8dc6ab0080322a9ebe01"
      }
    ]
  },
  "ontoRefName": "refs/heads/master",
  "generatedRefName": "refs/heads/vsts-dotnet-samples/stop-brass-division"
}

Sample response

Status code:

201

{
  "revertId": 19,
  "parameters": {
    "repository": {
      "id": "9a6b6a4a-83df-47ab-8c2a-07742cede4cb",
      "name": "FabrikamOps",
      "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb",
      "project": {
        "id": "0807fc91-4393-482d-9e23-defdbb7d0857",
        "name": "Test1",
        "url": "https://dev.azure.com/fabrikam/_apis/projects/0807fc91-4393-482d-9e23-defdbb7d0857",
        "state": "wellFormed",
        "revision": 165
      },
      "remoteUrl": "https://dev.azure.com/fabrikam/Test1/_git/FabrikamOps",
      "sshUrl": "ssh://fabrikam@vs-ssh.visualstudio.com:22/Test1/_ssh/FabrikamOps"
    },
    "source": {
      "commitList": [
        {
          "commitId": "4388fbc9e8511520a9ae8dc6ab0080322a9ebe01",
          "url": "https://dev.azure.com/fabrikam/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb/commits/4388fbc9e8511520a9ae8dc6ab0080322a9ebe01"
        }
      ]
    },
    "ontoRefName": "refs/heads/master",
    "generatedRefName": "refs/heads/vsts-dotnet-samples/stop-brass-division"
  },
  "status": "queued",
  "detailedStatus": null,
  "_links": {
    "self": {
      "href": "https://dev.azure.com/fabrikam/0807fc91-4393-482d-9e23-defdbb7d0857/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb/reverts/19"
    },
    "repository": {
      "href": "https://dev.azure.com/fabrikam/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb"
    }
  },
  "url": "https://dev.azure.com/fabrikam/0807fc91-4393-482d-9e23-defdbb7d0857/_apis/git/repositories/9a6b6a4a-83df-47ab-8c2a-07742cede4cb/reverts/19"
}

Definitions

Name	Description
ChangeCountDictionary
GitAsyncOperationStatus
GitAsyncRefOperationDetail	Information about the progress of a cherry pick or revert operation.
GitAsyncRefOperationFailureStatus	Provides a status code that indicates the reason the cherry pick or revert failed.
GitAsyncRefOperationParameters	Parameters that are provided in the request body when requesting to cherry pick or revert.
GitAsyncRefOperationSource	GitAsyncRefOperationSource specifies the pull request or list of commits to use when making a cherry pick and revert operation request. Only one should be provided.
GitChange
GitCommitRef	Provides properties that describe a Git commit and associated metadata.
GitPushRef
GitRepository
GitRepositoryRef
GitRevert
GitStatus	This class contains the metadata of a service/extension posting a status.
GitStatusContext	Status context that uniquely identifies the status.
GitStatusState	State of the status.
GitTemplate
GitUserDate	User info and date for Git operations.
IdentityRef
ItemContent
ItemContentType
ProjectState	Project state.
ProjectVisibility	Project visibility.
ReferenceLinks	The class to represent a collection of REST reference links.
ResourceRef
TeamProjectCollectionReference	Reference object for a TeamProjectCollection.
TeamProjectReference	Represents a shallow reference to a TeamProject.
VersionControlChangeType	The type of change that was made to the item.

ChangeCountDictionary

Object

GitAsyncOperationStatus

Enumeration

Value	Description
abandoned	The operation has been abandoned.
completed	The operation has completed.
failed	The operation has failed. Check for an error message.
inProgress	The operation is currently in progress.
queued	The operation is waiting in a queue and has not yet started.

GitAsyncRefOperationDetail

Object

Information about the progress of a cherry pick or revert operation.

Name	Type	Description
conflict	boolean	Indicates if there was a conflict generated when trying to cherry pick or revert the changes.
currentCommitId	string	The current commit from the list of commits that are being cherry picked or reverted.
failureMessage	string	Detailed information about why the cherry pick or revert failed to complete.
progress	number (double)	A number between 0 and 1 indicating the percent complete of the operation.
status	GitAsyncRefOperationFailureStatus	Provides a status code that indicates the reason the cherry pick or revert failed.
timedout	boolean	Indicates if the operation went beyond the maximum time allowed for a cherry pick or revert operation.

GitAsyncRefOperationFailureStatus

Enumeration

Provides a status code that indicates the reason the cherry pick or revert failed.

Value	Description
asyncOperationNotFound	Async operation was not found
createBranchPermissionRequired	The ref update request could not be completed because the user lacks the permission to create a branch
emptyCommitterSignature	Initiator of async operation has signature with empty name or email
gitObjectTooLarge	Git object is too large to materialize into memory
invalidRefName	Indicates that the ref update request could not be completed because the ref name presented in the request was not valid.
none	No status
operationIndentityNotFound	Identity who authorized the operation was not found
other	Unexpected failure
refNameConflict	The ref update could not be completed because, in case-insensitive mode, the ref name conflicts with an existing, differently-cased ref name.
targetBranchDeleted	Target branch was deleted after Git async operation started
writePermissionRequired	The ref update request could not be completed because the user lacks write permissions required to write this ref

GitAsyncRefOperationParameters

Object

Parameters that are provided in the request body when requesting to cherry pick or revert.

Name	Type	Description
generatedRefName	string	Proposed target branch name for the cherry pick or revert operation.
ontoRefName	string	The target branch for the cherry pick or revert operation.
repository	GitRepository	The git repository for the cherry pick or revert operation.
source	GitAsyncRefOperationSource	Details about the source of the cherry pick or revert operation (e.g. A pull request or a specific commit).

GitAsyncRefOperationSource

Object

GitAsyncRefOperationSource specifies the pull request or list of commits to use when making a cherry pick and revert operation request. Only one should be provided.

Name	Type	Description
commitList	GitCommitRef[]	A list of commits to cherry pick or revert
pullRequestId	integer (int32)	Id of the pull request to cherry pick or revert

GitChange

Object

Name	Type	Description
changeId	integer (int32)	ID of the change within the group of changes.
changeType	VersionControlChangeType	The type of change that was made to the item.
item	string (T)	Current version.
newContent	ItemContent	Content of the item after the change.
newContentTemplate	GitTemplate	New Content template to be used when pushing new changes.
originalPath	string	Original path of item if different from current path.
sourceServerItem	string	Path of the item on the server.
url	string	URL to retrieve the item.

GitCommitRef

Object

Provides properties that describe a Git commit and associated metadata.

Name	Type	Description
_links	ReferenceLinks	A collection of related REST reference links.
author	GitUserDate	Author of the commit.
changeCounts	ChangeCountDictionary	Counts of the types of changes (edits, deletes, etc.) included with the commit.
changes	GitChange[]	An enumeration of the changes included with the commit.
comment	string	Comment or message of the commit.
commentTruncated	boolean	Indicates if the comment is truncated from the full Git commit comment message.
commitId	string	ID (SHA-1) of the commit.
commitTooManyChanges	boolean	Indicates that commit contains too many changes to be displayed
committer	GitUserDate	Committer of the commit.
parents	string[]	An enumeration of the parent commit IDs for this commit.
push	GitPushRef	The push associated with this commit.
remoteUrl	string	Remote URL path to the commit.
statuses	GitStatus[]	A list of status metadata from services and extensions that may associate additional information to the commit.
url	string	REST URL for this resource.
workItems	ResourceRef[]	A list of workitems associated with this commit.

GitPushRef

Object

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
date	string (date-time)
pushId	integer (int32)
pushedBy	IdentityRef
url	string

GitRepository

Object

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
defaultBranch	string
id	string (uuid)
isDisabled	boolean	True if the repository is disabled. False otherwise.
isFork	boolean	True if the repository was created as a fork.
isInMaintenance	boolean	True if the repository is in maintenance. False otherwise.
name	string
parentRepository	GitRepositoryRef
project	TeamProjectReference	Represents a shallow reference to a TeamProject.
remoteUrl	string
size	integer (int64)	Compressed size (bytes) of the repository.
sshUrl	string
url	string
validRemoteUrls	string[]
webUrl	string

GitRepositoryRef

Object

Name	Type	Description
collection	TeamProjectCollectionReference	Team Project Collection where this Fork resides
id	string (uuid)
isFork	boolean	True if the repository was created as a fork
name	string
project	TeamProjectReference	Represents a shallow reference to a TeamProject.
remoteUrl	string
sshUrl	string
url	string

GitRevert

Object

Name	Type	Description
_links	ReferenceLinks	The class to represent a collection of REST reference links.
detailedStatus	GitAsyncRefOperationDetail	Information about the progress of a cherry pick or revert operation.
parameters	GitAsyncRefOperationParameters	Parameters that are provided in the request body when requesting to cherry pick or revert.
revertId	integer (int32)
status	GitAsyncOperationStatus
url	string	A URL that can be used to make further requests for status about the operation

GitStatus

Object

This class contains the metadata of a service/extension posting a status.

Name	Type	Description
_links	ReferenceLinks	Reference links.
context	GitStatusContext	Context of the status.
createdBy	IdentityRef	Identity that created the status.
creationDate	string (date-time)	Creation date and time of the status.
description	string	Status description. Typically describes current state of the status.
id	integer (int32)	Status identifier.
state	GitStatusState	State of the status.
targetUrl	string	URL with status details.
updatedDate	string (date-time)	Last update date and time of the status.

GitStatusContext

Object

Status context that uniquely identifies the status.

Name	Type	Description
genre	string	Genre of the status. Typically name of the service/tool generating the status, can be empty.
name	string	Name identifier of the status, cannot be null or empty.

GitStatusState

Enumeration

State of the status.

Value	Description
error	Status with an error.
failed	Status failed.
notApplicable	Status is not applicable to the target object.
notSet	Status state not set. Default state.
pending	Status pending.
succeeded	Status succeeded.

GitTemplate

Object

Name	Type	Description
name	string	Name of the Template
type	string	Type of the Template

GitUserDate

Object

User info and date for Git operations.

Name	Type	Description
date	string (date-time)	Date of the Git operation.
email	string	Email address of the user performing the Git operation.
imageUrl	string	Url for the user's avatar.
name	string	Name of the user performing the Git operation.

IdentityRef

Object

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.

ItemContent

Object

Name	Type	Description
content	string
contentType	ItemContentType

ItemContentType

Enumeration

Value	Description
base64Encoded
rawText

ProjectState

Enumeration

Project state.

Value	Description
all	All projects regardless of state except Deleted.
createPending	Project has been queued for creation, but the process has not yet started.
deleted	Project has been deleted.
deleting	Project is in the process of being deleted.
new	Project is in the process of being created.
unchanged	Project has not been changed.
wellFormed	Project is completely created and ready to use.

ProjectVisibility

Enumeration

Project visibility.

Value	Description
private	The project is only visible to users with explicit access.
public	The project is visible to all.

ReferenceLinks

Object

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

ResourceRef

Object

Name	Type	Description
id	string
url	string

TeamProjectCollectionReference

Object

Reference object for a TeamProjectCollection.

Name	Type	Description
avatarUrl	string	Collection avatar Url.
id	string (uuid)	Collection Id.
name	string	Collection Name.
url	string	Collection REST Url.

TeamProjectReference

Object

Represents a shallow reference to a TeamProject.

Name	Type	Description
abbreviation	string	Project abbreviation.
defaultTeamImageUrl	string	Url to default team identity image.
description	string	The project's description (if any).
id	string (uuid)	Project identifier.
lastUpdateTime	string (date-time)	Project last update time.
name	string	Project name.
revision	integer (int64)	Project revision.
state	ProjectState	Project state.
url	string	Url to the full version of the object.
visibility	ProjectVisibility	Project visibility.

VersionControlChangeType

Enumeration

The type of change that was made to the item.

Value	Description
add
all
branch
delete
edit
encoding
lock
merge
none
property
rename
rollback
sourceRename
targetRename
undelete