BuildRestClient class

Reference

Package:: azure-devops-extension-api

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

Extends: RestClientBase

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

options: IVssRestClientOptions

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

resources: DefinitionResourceReference[]

project: string

Project ID or project name

definitionId: number

Returns

Promise<DefinitionResourceReference[]>

authorizeProjectResources(DefinitionResourceReference[], string)

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

Parameters

resources: DefinitionResourceReference[]

project: string

Project ID or project name

Returns

Promise<DefinitionResourceReference[]>

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

Promise<PipelineGeneralSettings>

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

Promise<BuildOptionDefinition[]>

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

Promise<BuildReportMetadata>

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

Promise<DefinitionResourceReference[]>

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

Promise<BuildDefinitionRevision[]>

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

Promise<PagedList<BuildDefinitionReference>>

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

Promise<SourceRepositoryItem[]>

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

Promise<DefinitionResourceReference[]>

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

Promise<BuildResourceUsage>

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

Promise<BuildRetentionHistory>

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

Promise<ProjectRetentionSetting>

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

Promise<BuildDefinitionTemplate>

getTemplates(string)

Gets all definition templates.

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

Parameters

project: string

Project ID or project name

Returns

Promise<BuildDefinitionTemplate[]>

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

Promise<SourceRepositories>

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

Promise<SourceProviderAttributes[]>

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

Promise<BuildDefinitionTemplate>

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

newSettings: PipelineGeneralSettings

project: string

Project ID or project name

Returns

Promise<PipelineGeneralSettings>

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

updateModel: UpdateProjectRetentionSettingModel

project: string

Project ID or project name

Returns

Promise<ProjectRetentionSetting>

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>