BuildRestClient class

Base class that should be used (derived from) to make requests to VSS REST apis

Extends

Constructors

BuildRestClient(IVssRestClientOptions)

Properties

RESOURCE_AREA_ID

Methods

addBuildTag(string, number, string)

Adds a tag to a build.

addBuildTags(string[], string, number)

Adds tags to a build.

addDefinitionTag(string, number, string)

Adds a tag to a definition

addDefinitionTags(string[], string, number)

Adds multiple tags to a definition.

addRetentionLeases(NewRetentionLease[], string)

Adds new leases for pipeline runs.

authorizeDefinitionResources(DefinitionResourceReference[], string, number)
authorizeProjectResources(DefinitionResourceReference[], string)
createArtifact(BuildArtifact, string, number)

Associates an artifact with a build.

createDefinition(BuildDefinition, string, number, number)

Creates a new definition.

createFolder(Folder, string, string)

Creates a new folder.

deleteBuild(string, number)

Deletes a build.

deleteBuildTag(string, number, string)

Removes a tag from a build. NOTE: This API will not work for tags with special characters. To remove tags with special characters, use the PATCH method instead (in 6.0+)

deleteDefinition(string, number)

Deletes a definition and all associated builds.

deleteDefinitionTag(string, number, string)

Removes a tag from a definition. NOTE: This API will not work for tags with special characters. To remove tags with special characters, use the PATCH method instead (in 6.0+)

deleteFolder(string, string)

Deletes a definition folder. Definitions and their corresponding builds will also be deleted.

deleteRetentionLeasesById(string, number[])

Removes specific retention leases.

deleteTag(string, string)

Removes a tag from builds, definitions, and from the tag store

deleteTemplate(string, string)

Deletes a build definition template.

getArtifact(string, number, string)

Gets a specific artifact for a build.

getArtifactContentZip(string, number, string)

Gets a specific artifact for a build.

getArtifacts(string, number)

Gets all artifacts for a build.

getAttachment(string, number, string, string, string, string)

Gets a specific attachment.

getAttachments(string, number, string)

Gets the list of attachments of a specific type that are associated with a build.

getBadge(string, number, string)

Gets a badge that indicates the status of the most recent build for a definition. Note that this API is deprecated. Prefer StatusBadgeController.GetStatusBadge.

getBuild(string, number, string)

Gets a build

getBuildBadge(string, string, string, string)

Gets a badge that indicates the status of the most recent build for the specified branch.

getBuildBadgeData(string, string, string, string)

Gets a badge that indicates the status of the most recent build for the specified branch.

getBuildChanges(string, number, string, number, boolean)

Gets the changes associated with a build

getBuildController(number)

Gets a controller

getBuildControllers(string)

Gets controller, optionally filtered by name

getBuildGeneralSettings(string)

Gets pipeline general settings.

getBuildLog(string, number, number, number, number)

Gets an individual log file for a build.

getBuildLogLines(string, number, number, number, number)

Gets an individual log file for a build.

getBuildLogs(string, number)

Gets the logs for a build.

getBuildLogsZip(string, number)

Gets the logs for a build.

getBuildLogZip(string, number, number, number, number)

Gets an individual log file for a build.

getBuildOptionDefinitions(string)

Gets all build definition options supported by the system.

getBuildProperties(string, number, string[])

Gets properties for a build.

getBuildReport(string, number, string)

Gets a build report.

getBuildReportHtmlContent(string, number, string)

Gets a build report.

getBuilds(string, number[], number[], string, Date, Date, string, BuildReason, BuildStatus, BuildResult, string[], string[], number, string, number, QueryDeletedOption, BuildQueryOrder, string, number[], string, string)

Gets a list of builds.

getBuildSettings(string)

Gets the build settings.

getBuildTags(string, number)

Gets the tags for a build.

getBuildTimeline(string, number, string, number, string)

Gets details for a build

getBuildWorkItemsRefs(string, number, number)

Gets the work items associated with a build. Only work items in the same project are returned.

getBuildWorkItemsRefsFromCommits(string[], string, number, number)

Gets the work items associated with a build, filtered to specific commits.

getChangesBetweenBuilds(string, number, number, number)

Gets the changes made to the repository between two given builds.

getDefinition(string, number, number, Date, string[], boolean)

Gets a definition, optionally at a specific revision.

getDefinitionMetrics(string, number, Date)

Gets build metrics for a definition.

getDefinitionProperties(string, number, string[])

Gets properties for a definition.

getDefinitionResources(string, number)
getDefinitionRevisions(string, number)

Gets all revisions of a definition.

getDefinitions(string, string, string, string, DefinitionQueryOrder, number, string, Date, number[], string, Date, Date, boolean, boolean, string, number, string)

Gets a list of definitions.

getDefinitionTags(string, number, number)

Gets the tags for a definition.

getDefinitionYaml(string, number, number, Date, string[], boolean)

Converts a definition to YAML, optionally at a specific revision.

getFile(string, number, string, string, string)

Gets a file from the build.

getFileContents(string, string, string, string, string, string)

Gets the contents of a file in the given source code repository.

getFolders(string, string, FolderQueryOrder)

Gets a list of build definition folders.

getLatestBuild(string, string, string)

Gets the latest build for a definition, optionally scoped to a specific branch.

getPathContents(string, string, string, string, string, string)

Gets the contents of a directory in the given source code repository.

getProjectMetrics(string, string, Date)

Gets build metrics for a project.

getProjectResources(string, string, string)
getPullRequest(string, string, string, string, string)

Gets a pull request object from source provider.

getResourceUsage()

Gets information about build resources in the system.

getRetentionHistory(number)

Returns the retention history for the project collection. This includes pipelines that have custom retention rules that may prevent the retention job from cleaning them up, runs per pipeline with retention type, files associated with pipelines owned by the collection with retention type, and the number of files per pipeline.

getRetentionLease(string, number)

Returns the details of the retention lease given a lease id.

getRetentionLeasesByMinimalRetentionLeases(string, MinimalRetentionLease[])

Returns any leases matching the specified MinimalRetentionLeases

getRetentionLeasesByOwnerId(string, string, number, number)

Returns any leases owned by the specified entity, optionally scoped to a single pipeline definition and run.

getRetentionLeasesByUserId(string, string, number, number)

Returns any leases owned by the specified user, optionally scoped to a single pipeline definition and run.

getRetentionLeasesForBuild(string, number)

Gets all retention leases that apply to a specific build.

getRetentionSettings(string)

Gets the project's retention settings.

getStatusBadge(string, string, string, string, string, string, string)

<p>Gets the build status for a definition, optionally scoped to a specific branch, stage, job, and configuration.</p> <p>If there are more than one, then it is required to pass in a stageName value when specifying a jobName, and the same rule then applies for both if passing a configuration parameter.</p>

getTags(string)

Gets a list of all build tags in the project.

getTemplate(string, string)

Gets a specific build definition template.

getTemplates(string)

Gets all definition templates.

getWorkItemsBetweenBuilds(string, number, number, number)

Gets all the work items between two builds.

listBranches(string, string, string, string, string)

Gets a list of branches for the given source code repository.

listRepositories(string, string, string, string, ResultSet, boolean, string)

Gets a list of source code repositories.

listSourceProviders(string)

Get a list of source providers and their capabilities.

listWebhooks(string, string, string, string)

Gets a list of webhooks installed in the given source code repository.

queueBuild(Build, string, boolean, string, number, number)

Queues a build

restoreDefinition(string, number, boolean)

Restores a deleted definition

restoreWebhooks(DefinitionTriggerType[], string, string, string, string)

Recreates the webhooks for the specified triggers in the given source code repository.

saveTemplate(BuildDefinitionTemplate, string, string)

Updates an existing build definition template.

updateBuild(Build, string, number, boolean)

Updates a build.

updateBuildGeneralSettings(PipelineGeneralSettings, string)

Updates pipeline general settings.

updateBuildProperties(JsonPatchDocument, string, number)

Updates properties for a build.

updateBuilds(Build[], string)

Updates multiple builds.

updateBuildSettings(BuildSettings, string)

Updates the build settings.

updateBuildTags(UpdateTagParameters, string, number)

Adds/Removes tags from a build.

updateDefinition(BuildDefinition, string, number, number, number)

Updates an existing build definition. In order for this operation to succeed, the value of the "Revision" property of the request body must match the existing build definition's. It is recommended that you obtain the existing build definition by using GET, modify the build definition as necessary, and then submit the modified definition with PUT.

updateDefinitionProperties(JsonPatchDocument, string, number)

Updates properties for a definition.

updateDefinitionTags(UpdateTagParameters, string, number)

Adds/Removes tags from a definition.

updateFolder(Folder, string, string)

Updates an existing folder at given existing path

updateRetentionLease(RetentionLeaseUpdate, string, number)

Updates the duration or pipeline protection status of a retention lease.

updateRetentionSettings(UpdateProjectRetentionSettingModel, string)

Updates the project's retention settings.

updateStage(UpdateStageParameters, number, string, string)

Update a build stage

Constructor Details

BuildRestClient(IVssRestClientOptions)

new BuildRestClient(options: IVssRestClientOptions)

Parameters

Property Details

RESOURCE_AREA_ID

static RESOURCE_AREA_ID: string

Property Value

string

Method Details

addBuildTag(string, number, string)

Adds a tag to a build.

function addBuildTag(project: string, buildId: number, tag: string): Promise<string[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

tag

string

The tag to add.

Returns

Promise<string[]>

addBuildTags(string[], string, number)

Adds tags to a build.

function addBuildTags(tags: string[], project: string, buildId: number): Promise<string[]>

Parameters

tags

string[]

The tags to add. Request body is composed directly from listed tags.

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<string[]>

addDefinitionTag(string, number, string)

Adds a tag to a definition

function addDefinitionTag(project: string, definitionId: number, tag: string): Promise<string[]>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

tag

string

The tag to add.

Returns

Promise<string[]>

addDefinitionTags(string[], string, number)

Adds multiple tags to a definition.

function addDefinitionTags(tags: string[], project: string, definitionId: number): Promise<string[]>

Parameters

tags

string[]

The tags to add.

project

string

Project ID or project name

definitionId

number

The ID of the definition.

Returns

Promise<string[]>

addRetentionLeases(NewRetentionLease[], string)

Adds new leases for pipeline runs.

function addRetentionLeases(newLeases: NewRetentionLease[], project: string): Promise<RetentionLease[]>

Parameters

newLeases

NewRetentionLease[]

project

string

Project ID or project name

Returns

Promise<RetentionLease[]>

authorizeDefinitionResources(DefinitionResourceReference[], string, number)

function authorizeDefinitionResources(resources: DefinitionResourceReference[], project: string, definitionId: number): Promise<DefinitionResourceReference[]>

Parameters

project

string

Project ID or project name

definitionId

number

Returns

authorizeProjectResources(DefinitionResourceReference[], string)

function authorizeProjectResources(resources: DefinitionResourceReference[], project: string): Promise<DefinitionResourceReference[]>

Parameters

project

string

Project ID or project name

Returns

createArtifact(BuildArtifact, string, number)

Associates an artifact with a build.

function createArtifact(artifact: BuildArtifact, project: string, buildId: number): Promise<BuildArtifact>

Parameters

artifact
BuildArtifact

The artifact.

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<BuildArtifact>

createDefinition(BuildDefinition, string, number, number)

Creates a new definition.

function createDefinition(definition: BuildDefinition, project: string, definitionToCloneId?: number, definitionToCloneRevision?: number): Promise<BuildDefinition>

Parameters

definition
BuildDefinition

The definition.

project

string

Project ID or project name

definitionToCloneId

number

definitionToCloneRevision

number

Returns

Promise<BuildDefinition>

createFolder(Folder, string, string)

Creates a new folder.

function createFolder(folder: Folder, project: string, path: string): Promise<Folder>

Parameters

folder
Folder

The folder.

project

string

Project ID or project name

path

string

The full path of the folder.

Returns

Promise<Folder>

deleteBuild(string, number)

Deletes a build.

function deleteBuild(project: string, buildId: number): Promise<void>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<void>

deleteBuildTag(string, number, string)

Removes a tag from a build. NOTE: This API will not work for tags with special characters. To remove tags with special characters, use the PATCH method instead (in 6.0+)

function deleteBuildTag(project: string, buildId: number, tag: string): Promise<string[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

tag

string

The tag to remove.

Returns

Promise<string[]>

deleteDefinition(string, number)

Deletes a definition and all associated builds.

function deleteDefinition(project: string, definitionId: number): Promise<void>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

Returns

Promise<void>

deleteDefinitionTag(string, number, string)

Removes a tag from a definition. NOTE: This API will not work for tags with special characters. To remove tags with special characters, use the PATCH method instead (in 6.0+)

function deleteDefinitionTag(project: string, definitionId: number, tag: string): Promise<string[]>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

tag

string

The tag to remove.

Returns

Promise<string[]>

deleteFolder(string, string)

Deletes a definition folder. Definitions and their corresponding builds will also be deleted.

function deleteFolder(project: string, path: string): Promise<void>

Parameters

project

string

Project ID or project name

path

string

The full path to the folder.

Returns

Promise<void>

deleteRetentionLeasesById(string, number[])

Removes specific retention leases.

function deleteRetentionLeasesById(project: string, ids: number[]): Promise<void>

Parameters

project

string

Project ID or project name

ids

number[]

Returns

Promise<void>

deleteTag(string, string)

Removes a tag from builds, definitions, and from the tag store

function deleteTag(project: string, tag: string): Promise<string[]>

Parameters

project

string

Project ID or project name

tag

string

The tag to remove.

Returns

Promise<string[]>

deleteTemplate(string, string)

Deletes a build definition template.

function deleteTemplate(project: string, templateId: string): Promise<void>

Parameters

project

string

Project ID or project name

templateId

string

The ID of the template.

Returns

Promise<void>

getArtifact(string, number, string)

Gets a specific artifact for a build.

function getArtifact(project: string, buildId: number, artifactName: string): Promise<BuildArtifact>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

artifactName

string

The name of the artifact.

Returns

Promise<BuildArtifact>

getArtifactContentZip(string, number, string)

Gets a specific artifact for a build.

function getArtifactContentZip(project: string, buildId: number, artifactName: string): Promise<ArrayBuffer>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

artifactName

string

The name of the artifact.

Returns

Promise<ArrayBuffer>

getArtifacts(string, number)

Gets all artifacts for a build.

function getArtifacts(project: string, buildId: number): Promise<BuildArtifact[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<BuildArtifact[]>

getAttachment(string, number, string, string, string, string)

Gets a specific attachment.

function getAttachment(project: string, buildId: number, timelineId: string, recordId: string, type: string, name: string): Promise<ArrayBuffer>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

timelineId

string

The ID of the timeline.

recordId

string

The ID of the timeline record.

type

string

The type of the attachment.

name

string

The name of the attachment.

Returns

Promise<ArrayBuffer>

getAttachments(string, number, string)

Gets the list of attachments of a specific type that are associated with a build.

function getAttachments(project: string, buildId: number, type: string): Promise<Attachment[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

type

string

The type of attachment.

Returns

Promise<Attachment[]>

getBadge(string, number, string)

Gets a badge that indicates the status of the most recent build for a definition. Note that this API is deprecated. Prefer StatusBadgeController.GetStatusBadge.

function getBadge(project: string, definitionId: number, branchName?: string): Promise<string>

Parameters

project

string

The project ID or name.

definitionId

number

The ID of the definition.

branchName

string

The name of the branch.

Returns

Promise<string>

getBuild(string, number, string)

Gets a build

function getBuild(project: string, buildId: number, propertyFilters?: string): Promise<Build>

Parameters

project

string

Project ID or project name

buildId

number

propertyFilters

string

Returns

Promise<Build>

getBuildBadge(string, string, string, string)

Gets a badge that indicates the status of the most recent build for the specified branch.

function getBuildBadge(project: string, repoType: string, repoId?: string, branchName?: string): Promise<BuildBadge>

Parameters

project

string

Project ID or project name

repoType

string

The repository type.

repoId

string

The repository ID.

branchName

string

The branch name.

Returns

Promise<BuildBadge>

getBuildBadgeData(string, string, string, string)

Gets a badge that indicates the status of the most recent build for the specified branch.

function getBuildBadgeData(project: string, repoType: string, repoId?: string, branchName?: string): Promise<string>

Parameters

project

string

Project ID or project name

repoType

string

The repository type.

repoId

string

The repository ID.

branchName

string

The branch name.

Returns

Promise<string>

getBuildChanges(string, number, string, number, boolean)

Gets the changes associated with a build

function getBuildChanges(project: string, buildId: number, continuationToken?: string, top?: number, includeSourceChange?: boolean): Promise<PagedList<Change>>

Parameters

project

string

Project ID or project name

buildId

number

continuationToken

string

top

number

The maximum number of changes to return

includeSourceChange

boolean

Returns

Promise<PagedList<Change>>

getBuildController(number)

Gets a controller

function getBuildController(controllerId: number): Promise<BuildController>

Parameters

controllerId

number

Returns

Promise<BuildController>

getBuildControllers(string)

Gets controller, optionally filtered by name

function getBuildControllers(name?: string): Promise<BuildController[]>

Parameters

name

string

Returns

Promise<BuildController[]>

getBuildGeneralSettings(string)

Gets pipeline general settings.

function getBuildGeneralSettings(project: string): Promise<PipelineGeneralSettings>

Parameters

project

string

Project ID or project name

Returns

getBuildLog(string, number, number, number, number)

Gets an individual log file for a build.

function getBuildLog(project: string, buildId: number, logId: number, startLine?: number, endLine?: number): Promise<string>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

logId

number

The ID of the log file.

startLine

number

The start line.

endLine

number

The end line.

Returns

Promise<string>

getBuildLogLines(string, number, number, number, number)

Gets an individual log file for a build.

function getBuildLogLines(project: string, buildId: number, logId: number, startLine?: number, endLine?: number): Promise<string[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

logId

number

The ID of the log file.

startLine

number

The start line.

endLine

number

The end line.

Returns

Promise<string[]>

getBuildLogs(string, number)

Gets the logs for a build.

function getBuildLogs(project: string, buildId: number): Promise<BuildLog[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<BuildLog[]>

getBuildLogsZip(string, number)

Gets the logs for a build.

function getBuildLogsZip(project: string, buildId: number): Promise<ArrayBuffer>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<ArrayBuffer>

getBuildLogZip(string, number, number, number, number)

Gets an individual log file for a build.

function getBuildLogZip(project: string, buildId: number, logId: number, startLine?: number, endLine?: number): Promise<ArrayBuffer>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

logId

number

The ID of the log file.

startLine

number

The start line.

endLine

number

The end line.

Returns

Promise<ArrayBuffer>

getBuildOptionDefinitions(string)

Gets all build definition options supported by the system.

function getBuildOptionDefinitions(project?: string): Promise<BuildOptionDefinition[]>

Parameters

project

string

Project ID or project name

Returns

getBuildProperties(string, number, string[])

Gets properties for a build.

function getBuildProperties(project: string, buildId: number, filter?: string[]): Promise<any>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

filter

string[]

A comma-delimited list of properties. If specified, filters to these specific properties.

Returns

Promise<any>

getBuildReport(string, number, string)

Gets a build report.

function getBuildReport(project: string, buildId: number, type?: string): Promise<BuildReportMetadata>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

type

string

Returns

getBuildReportHtmlContent(string, number, string)

Gets a build report.

function getBuildReportHtmlContent(project: string, buildId: number, type?: string): Promise<any>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

type

string

Returns

Promise<any>

getBuilds(string, number[], number[], string, Date, Date, string, BuildReason, BuildStatus, BuildResult, string[], string[], number, string, number, QueryDeletedOption, BuildQueryOrder, string, number[], string, string)

Gets a list of builds.

function getBuilds(project: string, definitions?: number[], queues?: number[], buildNumber?: string, minTime?: Date, maxTime?: Date, requestedFor?: string, reasonFilter?: BuildReason, statusFilter?: BuildStatus, resultFilter?: BuildResult, tagFilters?: string[], properties?: string[], top?: number, continuationToken?: string, maxBuildsPerDefinition?: number, deletedFilter?: QueryDeletedOption, queryOrder?: BuildQueryOrder, branchName?: string, buildIds?: number[], repositoryId?: string, repositoryType?: string): Promise<PagedList<Build>>

Parameters

project

string

Project ID or project name

definitions

number[]

A comma-delimited list of definition IDs. If specified, filters to builds for these definitions.

queues

number[]

A comma-delimited list of queue IDs. If specified, filters to builds that ran against these queues.

buildNumber

string

If specified, filters to builds that match this build number. Append * to do a prefix search.

minTime

Date

If specified, filters to builds that finished/started/queued after this date based on the queryOrder specified.

maxTime

Date

If specified, filters to builds that finished/started/queued before this date based on the queryOrder specified.

requestedFor

string

If specified, filters to builds requested for the specified user.

reasonFilter
BuildReason

If specified, filters to builds that match this reason.

statusFilter
BuildStatus

If specified, filters to builds that match this status.

resultFilter
BuildResult

If specified, filters to builds that match this result.

tagFilters

string[]

A comma-delimited list of tags. If specified, filters to builds that have the specified tags.

properties

string[]

A comma-delimited list of properties to retrieve.

top

number

The maximum number of builds to return.

continuationToken

string

A continuation token, returned by a previous call to this method, that can be used to return the next set of builds.

maxBuildsPerDefinition

number

The maximum number of builds to return per definition.

deletedFilter
QueryDeletedOption

Indicates whether to exclude, include, or only return deleted builds.

queryOrder
BuildQueryOrder

The order in which builds should be returned.

branchName

string

If specified, filters to builds that built branches that built this branch.

buildIds

number[]

A comma-delimited list that specifies the IDs of builds to retrieve.

repositoryId

string

If specified, filters to builds that built from this repository.

repositoryType

string

If specified, filters to builds that built from repositories of this type.

Returns

Promise<PagedList<Build>>

getBuildSettings(string)

Gets the build settings.

function getBuildSettings(project?: string): Promise<BuildSettings>

Parameters

project

string

Project ID or project name

Returns

Promise<BuildSettings>

getBuildTags(string, number)

Gets the tags for a build.

function getBuildTags(project: string, buildId: number): Promise<string[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<string[]>

getBuildTimeline(string, number, string, number, string)

Gets details for a build

function getBuildTimeline(project: string, buildId: number, timelineId?: string, changeId?: number, planId?: string): Promise<Timeline>

Parameters

project

string

Project ID or project name

buildId

number

timelineId

string

changeId

number

planId

string

Returns

Promise<Timeline>

getBuildWorkItemsRefs(string, number, number)

Gets the work items associated with a build. Only work items in the same project are returned.

function getBuildWorkItemsRefs(project: string, buildId: number, top?: number): Promise<ResourceRef[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

top

number

The maximum number of work items to return.

Returns

Promise<ResourceRef[]>

getBuildWorkItemsRefsFromCommits(string[], string, number, number)

Gets the work items associated with a build, filtered to specific commits.

function getBuildWorkItemsRefsFromCommits(commitIds: string[], project: string, buildId: number, top?: number): Promise<ResourceRef[]>

Parameters

commitIds

string[]

A comma-delimited list of commit IDs.

project

string

Project ID or project name

buildId

number

The ID of the build.

top

number

The maximum number of work items to return, or the number of commits to consider if no commit IDs are specified.

Returns

Promise<ResourceRef[]>

getChangesBetweenBuilds(string, number, number, number)

Gets the changes made to the repository between two given builds.

function getChangesBetweenBuilds(project: string, fromBuildId?: number, toBuildId?: number, top?: number): Promise<Change[]>

Parameters

project

string

Project ID or project name

fromBuildId

number

The ID of the first build.

toBuildId

number

The ID of the last build.

top

number

The maximum number of changes to return.

Returns

Promise<Change[]>

getDefinition(string, number, number, Date, string[], boolean)

Gets a definition, optionally at a specific revision.

function getDefinition(project: string, definitionId: number, revision?: number, minMetricsTime?: Date, propertyFilters?: string[], includeLatestBuilds?: boolean): Promise<BuildDefinition>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

revision

number

The revision number to retrieve. If this is not specified, the latest version will be returned.

minMetricsTime

Date

If specified, indicates the date from which metrics should be included.

propertyFilters

string[]

A comma-delimited list of properties to include in the results.

includeLatestBuilds

boolean

Returns

Promise<BuildDefinition>

getDefinitionMetrics(string, number, Date)

Gets build metrics for a definition.

function getDefinitionMetrics(project: string, definitionId: number, minMetricsTime?: Date): Promise<BuildMetric[]>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

minMetricsTime

Date

The date from which to calculate metrics.

Returns

Promise<BuildMetric[]>

getDefinitionProperties(string, number, string[])

Gets properties for a definition.

function getDefinitionProperties(project: string, definitionId: number, filter?: string[]): Promise<any>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

filter

string[]

A comma-delimited list of properties. If specified, filters to these specific properties.

Returns

Promise<any>

getDefinitionResources(string, number)

function getDefinitionResources(project: string, definitionId: number): Promise<DefinitionResourceReference[]>

Parameters

project

string

Project ID or project name

definitionId

number

Returns

getDefinitionRevisions(string, number)

Gets all revisions of a definition.

function getDefinitionRevisions(project: string, definitionId: number): Promise<BuildDefinitionRevision[]>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

Returns

getDefinitions(string, string, string, string, DefinitionQueryOrder, number, string, Date, number[], string, Date, Date, boolean, boolean, string, number, string)

Gets a list of definitions.

function getDefinitions(project: string, name?: string, repositoryId?: string, repositoryType?: string, queryOrder?: DefinitionQueryOrder, top?: number, continuationToken?: string, minMetricsTime?: Date, definitionIds?: number[], path?: string, builtAfter?: Date, notBuiltAfter?: Date, includeAllProperties?: boolean, includeLatestBuilds?: boolean, taskIdFilter?: string, processType?: number, yamlFilename?: string): Promise<PagedList<BuildDefinitionReference>>

Parameters

project

string

Project ID or project name

name

string

If specified, filters to definitions whose names match this pattern.

repositoryId

string

A repository ID. If specified, filters to definitions that use this repository.

repositoryType

string

If specified, filters to definitions that have a repository of this type.

queryOrder
DefinitionQueryOrder

Indicates the order in which definitions should be returned.

top

number

The maximum number of definitions to return.

continuationToken

string

A continuation token, returned by a previous call to this method, that can be used to return the next set of definitions.

minMetricsTime

Date

If specified, indicates the date from which metrics should be included.

definitionIds

number[]

A comma-delimited list that specifies the IDs of definitions to retrieve.

path

string

If specified, filters to definitions under this folder.

builtAfter

Date

If specified, filters to definitions that have builds after this date.

notBuiltAfter

Date

If specified, filters to definitions that do not have builds after this date.

includeAllProperties

boolean

Indicates whether the full definitions should be returned. By default, shallow representations of the definitions are returned.

includeLatestBuilds

boolean

Indicates whether to return the latest and latest completed builds for this definition.

taskIdFilter

string

If specified, filters to definitions that use the specified task.

processType

number

If specified, filters to definitions with the given process type.

yamlFilename

string

If specified, filters to YAML definitions that match the given filename. To use this filter includeAllProperties should be set to true

Returns

getDefinitionTags(string, number, number)

Gets the tags for a definition.

function getDefinitionTags(project: string, definitionId: number, revision?: number): Promise<string[]>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

revision

number

The definition revision number. If not specified, uses the latest revision of the definition.

Returns

Promise<string[]>

getDefinitionYaml(string, number, number, Date, string[], boolean)

Converts a definition to YAML, optionally at a specific revision.

function getDefinitionYaml(project: string, definitionId: number, revision?: number, minMetricsTime?: Date, propertyFilters?: string[], includeLatestBuilds?: boolean): Promise<YamlBuild>

Parameters

project

string

Project ID or project name

definitionId

number

The ID of the definition.

revision

number

The revision number to retrieve. If this is not specified, the latest version will be returned.

minMetricsTime

Date

If specified, indicates the date from which metrics should be included.

propertyFilters

string[]

A comma-delimited list of properties to include in the results.

includeLatestBuilds

boolean

Returns

Promise<YamlBuild>

getFile(string, number, string, string, string)

Gets a file from the build.

function getFile(project: string, buildId: number, artifactName: string, fileId: string, fileName: string): Promise<ArrayBuffer>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

artifactName

string

The name of the artifact.

fileId

string

The primary key for the file.

fileName

string

The name that the file will be set to.

Returns

Promise<ArrayBuffer>

getFileContents(string, string, string, string, string, string)

Gets the contents of a file in the given source code repository.

function getFileContents(project: string, providerName: string, serviceEndpointId?: string, repository?: string, commitOrBranch?: string, path?: string): Promise<string>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

If specified, the vendor-specific identifier or the name of the repository to get branches. Can only be omitted for providers that do not support multiple repositories.

commitOrBranch

string

The identifier of the commit or branch from which a file's contents are retrieved.

path

string

The path to the file to retrieve, relative to the root of the repository.

Returns

Promise<string>

getFolders(string, string, FolderQueryOrder)

Gets a list of build definition folders.

function getFolders(project: string, path?: string, queryOrder?: FolderQueryOrder): Promise<Folder[]>

Parameters

project

string

Project ID or project name

path

string

The path to start with.

queryOrder
FolderQueryOrder

The order in which folders should be returned.

Returns

Promise<Folder[]>

getLatestBuild(string, string, string)

Gets the latest build for a definition, optionally scoped to a specific branch.

function getLatestBuild(project: string, definition: string, branchName?: string): Promise<Build>

Parameters

project

string

Project ID or project name

definition

string

definition name with optional leading folder path, or the definition id

branchName

string

optional parameter that indicates the specific branch to use. If not specified, the default branch is used.

Returns

Promise<Build>

getPathContents(string, string, string, string, string, string)

Gets the contents of a directory in the given source code repository.

function getPathContents(project: string, providerName: string, serviceEndpointId?: string, repository?: string, commitOrBranch?: string, path?: string): Promise<SourceRepositoryItem[]>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

If specified, the vendor-specific identifier or the name of the repository to get branches. Can only be omitted for providers that do not support multiple repositories.

commitOrBranch

string

The identifier of the commit or branch from which a file's contents are retrieved.

path

string

The path contents to list, relative to the root of the repository.

Returns

getProjectMetrics(string, string, Date)

Gets build metrics for a project.

function getProjectMetrics(project: string, metricAggregationType?: string, minMetricsTime?: Date): Promise<BuildMetric[]>

Parameters

project

string

Project ID or project name

metricAggregationType

string

The aggregation type to use (hourly, daily).

minMetricsTime

Date

The date from which to calculate metrics.

Returns

Promise<BuildMetric[]>

getProjectResources(string, string, string)

function getProjectResources(project: string, type?: string, id?: string): Promise<DefinitionResourceReference[]>

Parameters

project

string

Project ID or project name

type

string

id

string

Returns

getPullRequest(string, string, string, string, string)

Gets a pull request object from source provider.

function getPullRequest(project: string, providerName: string, pullRequestId: string, repositoryId?: string, serviceEndpointId?: string): Promise<PullRequest>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

pullRequestId

string

Vendor-specific id of the pull request.

repositoryId

string

Vendor-specific identifier or the name of the repository that contains the pull request.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

Returns

Promise<PullRequest>

getResourceUsage()

Gets information about build resources in the system.

function getResourceUsage(): Promise<BuildResourceUsage>

Returns

getRetentionHistory(number)

Returns the retention history for the project collection. This includes pipelines that have custom retention rules that may prevent the retention job from cleaning them up, runs per pipeline with retention type, files associated with pipelines owned by the collection with retention type, and the number of files per pipeline.

function getRetentionHistory(daysToLookback?: number): Promise<BuildRetentionHistory>

Parameters

daysToLookback

number

Returns

getRetentionLease(string, number)

Returns the details of the retention lease given a lease id.

function getRetentionLease(project: string, leaseId: number): Promise<RetentionLease>

Parameters

project

string

Project ID or project name

leaseId

number

Returns

Promise<RetentionLease>

getRetentionLeasesByMinimalRetentionLeases(string, MinimalRetentionLease[])

Returns any leases matching the specified MinimalRetentionLeases

function getRetentionLeasesByMinimalRetentionLeases(project: string, leasesToFetch: MinimalRetentionLease[]): Promise<RetentionLease[]>

Parameters

project

string

Project ID or project name

leasesToFetch

MinimalRetentionLease[]

List of JSON-serialized MinimalRetentionLeases separated by '|'

Returns

Promise<RetentionLease[]>

getRetentionLeasesByOwnerId(string, string, number, number)

Returns any leases owned by the specified entity, optionally scoped to a single pipeline definition and run.

function getRetentionLeasesByOwnerId(project: string, ownerId?: string, definitionId?: number, runId?: number): Promise<RetentionLease[]>

Parameters

project

string

Project ID or project name

ownerId

string

definitionId

number

An optional parameter to limit the search to a specific pipeline definition.

runId

number

An optional parameter to limit the search to a single pipeline run. Requires definitionId.

Returns

Promise<RetentionLease[]>

getRetentionLeasesByUserId(string, string, number, number)

Returns any leases owned by the specified user, optionally scoped to a single pipeline definition and run.

function getRetentionLeasesByUserId(project: string, userOwnerId: string, definitionId?: number, runId?: number): Promise<RetentionLease[]>

Parameters

project

string

Project ID or project name

userOwnerId

string

The user id to search for.

definitionId

number

An optional parameter to limit the search to a specific pipeline definition.

runId

number

An optional parameter to limit the search to a single pipeline run. Requires definitionId.

Returns

Promise<RetentionLease[]>

getRetentionLeasesForBuild(string, number)

Gets all retention leases that apply to a specific build.

function getRetentionLeasesForBuild(project: string, buildId: number): Promise<RetentionLease[]>

Parameters

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<RetentionLease[]>

getRetentionSettings(string)

Gets the project's retention settings.

function getRetentionSettings(project: string): Promise<ProjectRetentionSetting>

Parameters

project

string

Project ID or project name

Returns

getStatusBadge(string, string, string, string, string, string, string)

<p>Gets the build status for a definition, optionally scoped to a specific branch, stage, job, and configuration.</p> <p>If there are more than one, then it is required to pass in a stageName value when specifying a jobName, and the same rule then applies for both if passing a configuration parameter.</p>

function getStatusBadge(project: string, definition: string, branchName?: string, stageName?: string, jobName?: string, configuration?: string, label?: string): Promise<string>

Parameters

project

string

Project ID or project name

definition

string

Either the definition name with optional leading folder path, or the definition id.

branchName

string

Only consider the most recent build for this branch. If not specified, the default branch is used.

stageName

string

Use this stage within the pipeline to render the status.

jobName

string

Use this job within a stage of the pipeline to render the status.

configuration

string

Use this job configuration to render the status

label

string

Replaces the default text on the left side of the badge.

Returns

Promise<string>

getTags(string)

Gets a list of all build tags in the project.

function getTags(project: string): Promise<string[]>

Parameters

project

string

Project ID or project name

Returns

Promise<string[]>

getTemplate(string, string)

Gets a specific build definition template.

function getTemplate(project: string, templateId: string): Promise<BuildDefinitionTemplate>

Parameters

project

string

Project ID or project name

templateId

string

The ID of the requested template.

Returns

getTemplates(string)

Gets all definition templates.

function getTemplates(project: string): Promise<BuildDefinitionTemplate[]>

Parameters

project

string

Project ID or project name

Returns

getWorkItemsBetweenBuilds(string, number, number, number)

Gets all the work items between two builds.

function getWorkItemsBetweenBuilds(project: string, fromBuildId: number, toBuildId: number, top?: number): Promise<ResourceRef[]>

Parameters

project

string

Project ID or project name

fromBuildId

number

The ID of the first build.

toBuildId

number

The ID of the last build.

top

number

The maximum number of work items to return.

Returns

Promise<ResourceRef[]>

listBranches(string, string, string, string, string)

Gets a list of branches for the given source code repository.

function listBranches(project: string, providerName: string, serviceEndpointId?: string, repository?: string, branchName?: string): Promise<string[]>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

The vendor-specific identifier or the name of the repository to get branches. Can only be omitted for providers that do not support multiple repositories.

branchName

string

If supplied, the name of the branch to check for specifically.

Returns

Promise<string[]>

listRepositories(string, string, string, string, ResultSet, boolean, string)

Gets a list of source code repositories.

function listRepositories(project: string, providerName: string, serviceEndpointId?: string, repository?: string, resultSet?: ResultSet, pageResults?: boolean, continuationToken?: string): Promise<SourceRepositories>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

If specified, the vendor-specific identifier or the name of a single repository to get.

resultSet
ResultSet

'top' for the repositories most relevant for the endpoint. If not set, all repositories are returned. Ignored if 'repository' is set.

pageResults

boolean

If set to true, this will limit the set of results and will return a continuation token to continue the query.

continuationToken

string

When paging results, this is a continuation token, returned by a previous call to this method, that can be used to return the next set of repositories.

Returns

listSourceProviders(string)

Get a list of source providers and their capabilities.

function listSourceProviders(project: string): Promise<SourceProviderAttributes[]>

Parameters

project

string

Project ID or project name

Returns

listWebhooks(string, string, string, string)

Gets a list of webhooks installed in the given source code repository.

function listWebhooks(project: string, providerName: string, serviceEndpointId?: string, repository?: string): Promise<RepositoryWebhook[]>

Parameters

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

If specified, the vendor-specific identifier or the name of the repository to get webhooks. Can only be omitted for providers that do not support multiple repositories.

Returns

Promise<RepositoryWebhook[]>

queueBuild(Build, string, boolean, string, number, number)

Queues a build

function queueBuild(build: Build, project: string, ignoreWarnings?: boolean, checkInTicket?: string, sourceBuildId?: number, definitionId?: number): Promise<Build>

Parameters

build
Build
project

string

Project ID or project name

ignoreWarnings

boolean

checkInTicket

string

sourceBuildId

number

definitionId

number

Optional definition id to queue a build without a body. Ignored if there's a valid body

Returns

Promise<Build>

restoreDefinition(string, number, boolean)

Restores a deleted definition

function restoreDefinition(project: string, definitionId: number, deleted: boolean): Promise<BuildDefinition>

Parameters

project

string

Project ID or project name

definitionId

number

The identifier of the definition to restore.

deleted

boolean

When false, restores a deleted definition.

Returns

Promise<BuildDefinition>

restoreWebhooks(DefinitionTriggerType[], string, string, string, string)

Recreates the webhooks for the specified triggers in the given source code repository.

function restoreWebhooks(triggerTypes: DefinitionTriggerType[], project: string, providerName: string, serviceEndpointId?: string, repository?: string): Promise<void>

Parameters

triggerTypes

DefinitionTriggerType[]

The types of triggers to restore webhooks for.

project

string

Project ID or project name

providerName

string

The name of the source provider.

serviceEndpointId

string

If specified, the ID of the service endpoint to query. Can only be omitted for providers that do not use service endpoints, e.g. TFVC or TFGit.

repository

string

If specified, the vendor-specific identifier or the name of the repository to get webhooks. Can only be omitted for providers that do not support multiple repositories.

Returns

Promise<void>

saveTemplate(BuildDefinitionTemplate, string, string)

Updates an existing build definition template.

function saveTemplate(template: BuildDefinitionTemplate, project: string, templateId: string): Promise<BuildDefinitionTemplate>

Parameters

template
BuildDefinitionTemplate

The new version of the template.

project

string

Project ID or project name

templateId

string

The ID of the template.

Returns

updateBuild(Build, string, number, boolean)

Updates a build.

function updateBuild(build: Build, project: string, buildId: number, retry?: boolean): Promise<Build>

Parameters

build
Build

The build.

project

string

Project ID or project name

buildId

number

The ID of the build.

retry

boolean

Returns

Promise<Build>

updateBuildGeneralSettings(PipelineGeneralSettings, string)

Updates pipeline general settings.

function updateBuildGeneralSettings(newSettings: PipelineGeneralSettings, project: string): Promise<PipelineGeneralSettings>

Parameters

project

string

Project ID or project name

Returns

updateBuildProperties(JsonPatchDocument, string, number)

Updates properties for a build.

function updateBuildProperties(document: JsonPatchDocument, project: string, buildId: number): Promise<any>

Parameters

document
JsonPatchDocument

A json-patch document describing the properties to update.

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<any>

updateBuilds(Build[], string)

Updates multiple builds.

function updateBuilds(builds: Build[], project: string): Promise<Build[]>

Parameters

builds

Build[]

The builds to update.

project

string

Project ID or project name

Returns

Promise<Build[]>

updateBuildSettings(BuildSettings, string)

Updates the build settings.

function updateBuildSettings(settings: BuildSettings, project?: string): Promise<BuildSettings>

Parameters

settings
BuildSettings

The new settings.

project

string

Project ID or project name

Returns

Promise<BuildSettings>

updateBuildTags(UpdateTagParameters, string, number)

Adds/Removes tags from a build.

function updateBuildTags(updateParameters: UpdateTagParameters, project: string, buildId: number): Promise<string[]>

Parameters

updateParameters
UpdateTagParameters

The tags to add/remove.

project

string

Project ID or project name

buildId

number

The ID of the build.

Returns

Promise<string[]>

updateDefinition(BuildDefinition, string, number, number, number)

Updates an existing build definition. In order for this operation to succeed, the value of the "Revision" property of the request body must match the existing build definition's. It is recommended that you obtain the existing build definition by using GET, modify the build definition as necessary, and then submit the modified definition with PUT.

function updateDefinition(definition: BuildDefinition, project: string, definitionId: number, secretsSourceDefinitionId?: number, secretsSourceDefinitionRevision?: number): Promise<BuildDefinition>

Parameters

definition
BuildDefinition

The new version of the definition. Its "Revision" property must match the existing definition for the update to be accepted.

project

string

Project ID or project name

definitionId

number

The ID of the definition.

secretsSourceDefinitionId

number

secretsSourceDefinitionRevision

number

Returns

Promise<BuildDefinition>

updateDefinitionProperties(JsonPatchDocument, string, number)

Updates properties for a definition.

function updateDefinitionProperties(document: JsonPatchDocument, project: string, definitionId: number): Promise<any>

Parameters

document
JsonPatchDocument

A json-patch document describing the properties to update.

project

string

Project ID or project name

definitionId

number

The ID of the definition.

Returns

Promise<any>

updateDefinitionTags(UpdateTagParameters, string, number)

Adds/Removes tags from a definition.

function updateDefinitionTags(updateParameters: UpdateTagParameters, project: string, definitionId: number): Promise<string[]>

Parameters

updateParameters
UpdateTagParameters

The tags to add/remove.

project

string

Project ID or project name

definitionId

number

The ID of the definition.

Returns

Promise<string[]>

updateFolder(Folder, string, string)

Updates an existing folder at given existing path

function updateFolder(folder: Folder, project: string, path: string): Promise<Folder>

Parameters

folder
Folder

The new version of the folder.

project

string

Project ID or project name

path

string

The full path to the folder.

Returns

Promise<Folder>

updateRetentionLease(RetentionLeaseUpdate, string, number)

Updates the duration or pipeline protection status of a retention lease.

function updateRetentionLease(leaseUpdate: RetentionLeaseUpdate, project: string, leaseId: number): Promise<RetentionLease>

Parameters

leaseUpdate
RetentionLeaseUpdate

The new data for the retention lease.

project

string

Project ID or project name

leaseId

number

The ID of the lease to update.

Returns

Promise<RetentionLease>

updateRetentionSettings(UpdateProjectRetentionSettingModel, string)

Updates the project's retention settings.

function updateRetentionSettings(updateModel: UpdateProjectRetentionSettingModel, project: string): Promise<ProjectRetentionSetting>

Parameters

project

string

Project ID or project name

Returns

updateStage(UpdateStageParameters, number, string, string)

Update a build stage

function updateStage(updateParameters: UpdateStageParameters, buildId: number, stageRefName: string, project?: string): Promise<void>

Parameters

updateParameters
UpdateStageParameters
buildId

number

stageRefName

string

project

string

Project ID or project name

Returns

Promise<void>