From b7f5b02462fd82bb91912e21a635df991a33a117 Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 7 Feb 2025 16:48:17 +0100 Subject: [PATCH 1/7] updated Get-AzDoPull~ and Set-AzDoPull~ --- .gitignore | 3 + .../AzureDevOpsPowerShell.psd1 | 2 +- .../AzureDevOpsPowerShell.psm1 | 10 +- .../Private/Invoke-AzDoRestMethod.ps1 | 3 + .../Private/New-AzDoAuthHeader.ps1 | 2 +- .../Git/PullRequests/Get-AzDoPullRequest.ps1 | 141 +++++++++++++ .../Git/PullRequests/Set-AzDoPullRequest.ps1 | 199 ++++++++++++++++++ 7 files changed, 353 insertions(+), 7 deletions(-) create mode 100644 AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 create mode 100644 AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 diff --git a/.gitignore b/.gitignore index 78a4fbb7..f0bb716c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ # Don't check in the Output dir Output/ site/ +baswijdenes/ +test.ps1 +.vs diff --git a/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psd1 b/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psd1 index 1f0dd4de..6b27807d 100644 --- a/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psd1 +++ b/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psd1 @@ -126,7 +126,7 @@ } # End of PrivateData hashtable # HelpInfo URI of this module - # HelpInfoURI = '' + HelpInfoURI = 'https://github.com/WeAreInSpark/AzureDevOpsPowerShellAPI' # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. # DefaultCommandPrefix = '' diff --git a/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psm1 b/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psm1 index c5dec8e7..ee9dfcfd 100644 --- a/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psm1 +++ b/AzureDevOpsPowerShell/AzureDevOpsPowerShell.psm1 @@ -2,11 +2,11 @@ $public = @(Get-ChildItem -Path (Join-Path -Path $PSScriptRoot -ChildPath 'Public/*.ps1') -Recurse -ErrorAction Stop) $private = @(Get-ChildItem -Path (Join-Path -Path $PSScriptRoot -ChildPath 'Private/*.ps1') -Recurse -ErrorAction Stop) foreach ($import in @($private + $public)) { - try { - . $import.FullName - } catch { - throw "Unable to dot source [$($import.FullName)]" - } + try { + . $import.FullName + } catch { + throw "Unable to dot source [$($import.FullName)]" + } } Export-ModuleMember -Function $public.Basename diff --git a/AzureDevOpsPowerShell/Private/Invoke-AzDoRestMethod.ps1 b/AzureDevOpsPowerShell/Private/Invoke-AzDoRestMethod.ps1 index a2dd1750..a36790aa 100644 --- a/AzureDevOpsPowerShell/Private/Invoke-AzDoRestMethod.ps1 +++ b/AzureDevOpsPowerShell/Private/Invoke-AzDoRestMethod.ps1 @@ -82,6 +82,9 @@ function Invoke-AzDoRestMethod { } if ($QueryParameters) { + if ($QueryParameters -notlike "?*") { + $QueryParameters = "?$QueryParameters" + } $params.Uri = "$($Uri)?$($QueryParameters)&api-version=$($Version)" } else { $params.Uri = "$($Uri)?api-version=$($Version)" diff --git a/AzureDevOpsPowerShell/Private/New-AzDoAuthHeader.ps1 b/AzureDevOpsPowerShell/Private/New-AzDoAuthHeader.ps1 index 537a363d..f2048e26 100644 --- a/AzureDevOpsPowerShell/Private/New-AzDoAuthHeader.ps1 +++ b/AzureDevOpsPowerShell/Private/New-AzDoAuthHeader.ps1 @@ -8,7 +8,7 @@ function New-AzDoAuthHeader { ) if ($PSCmdlet.ShouldProcess("Creating new authentication header")) { Write-Verbose "Function: New-AzDoAuthHeader" - if ($Pat -eq '') { + if ([string]::IsNullOrEmpty($Pat)) { # validate if user is logged in to Azure PowerShell Write-Verbose "Using Access Token" try { diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 new file mode 100644 index 00000000..26e79a8c --- /dev/null +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 @@ -0,0 +1,141 @@ +function Get-AzDoPullRequest { + <# +.SYNOPSIS + Retrieves pull request information from Azure DevOps. + +.DESCRIPTION + This function fetches pull request details using Azure DevOps REST API. + +.PARAMETER CollectionUri + The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org). + +.PARAMETER ProjectName + The name of the Azure DevOps project. + +.PARAMETER RepositoryName + The name of the repository (optional for project-wide pull request queries). + +.PARAMETER PullRequestId + The ID of a specific pull request (optional for listing all pull requests). + +.PARAMETER Query + A query string to filter the results (optional). + Can only be used without PullRequestId: + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests?view=azure-devops-rest-7.2&tabs=HTTP#uri-parameters + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests-by-project?view=azure-devops-rest-7.2&tabs=HTTP#uri-parameters + +.EXAMPLE + Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" + +.EXAMPLE + Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" + +.EXAMPLE + Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" -Query "searchCriteria.status=completed" + +.EXAMPLE + Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" -PullRequestId "6789" + +.EXAMPLE + Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -PullRequestId "6789" + +.OUTPUTS + PSCustomObject with pull request details. + +.NOTES + Requires authentication with Azure DevOps REST API. + +.LINK + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-request?view=azure-devops-rest-7.2 + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-request-by-id?view=azure-devops-rest-7.2 + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests?view=azure-devops-rest-7.2 + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests-by-project?view=azure-devops-rest-7.2 +#> + [CmdletBinding(DefaultParameterSetName = "AllProjectPullRequests", SupportsShouldProcess)] + param ( + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "RepoSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "ProjectSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllProjectPullRequests")] + [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] + [string] + $CollectionUri, + + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "RepoSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "ProjectSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllProjectPullRequests")] + [string] + $ProjectName, + + [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "RepoSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "AllRepoPullRequests")] + [string] + $RepoName, + + [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "RepoSpecificPullRequest")] + [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "ProjectSpecificPullRequest")] + [string] + $PullRequestId, + + [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] + [string] + $Query + ) + + + begin { + $result = @() + Write-Verbose "Starting function: Get-AzDoPullRequest" + } + + process { + $uriBase = "$CollectionUri/$ProjectName/_apis/git" + $apiVersion = "7.2-preview.2" + $uri = "" + + switch ($PSCmdlet.ParameterSetName) { + "RepoSpecificPullRequest" { + $uri = "$uriBase/repositories/$RepoName/pullrequests/$PullRequestId" + } + "ProjectSpecificPullRequest" { + $uri = "$uriBase/pullrequests/$PullRequestId" + } + "AllRepoPullRequests" { + $uri = "$uriBase/repositories/$RepoName/pullrequests" + } + "AllProjectPullRequests" { + $uri = "$uriBase/pullrequests" + } + } + + if ($PSCmdlet.ShouldProcess($CollectionUri, "Get Pull Request from: $ProjectName")) { + Write-Verbose "Calling API: $uri" + + $InvokeAzDoRestMethodSplat = @{ + Uri = $uri + Method = "GET" + Version = $apiVersion + } + if (-not([string]::IsNullOrEmpty($Query))) { + $InvokeAzDoRestMethodSplat.QueryParameters = $Query + } + $response = Invoke-AzDoRestMethod @InvokeAzDoRestMethodSplat + if ($response.value) { + $result += $response.value + } else { + $result += $response + } + if ($result) { + $result | ForEach-Object { + [PSCustomObject]@{ + CollectionUri = $CollectionUri + ProjectName = $ProjectName + RepoName = $RepoName + PullRequest = $PSItem + } + } + } + } + } +} diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 new file mode 100644 index 00000000..5f612b09 --- /dev/null +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 @@ -0,0 +1,199 @@ +function Set-AzDoPullRequest { + <# +.SYNOPSIS + Retrieves pull request information from Azure DevOps. + +.DESCRIPTION + This function fetches pull request details using Azure DevOps REST API. + +.PARAMETER CollectionUri + The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org). + +.PARAMETER ProjectName + The name of the Azure DevOps project. + +.PARAMETER RepositoryName + The name of the repository (optional for project-wide pull request queries). + +.PARAMETER PullRequestId + The ID of a specific pull request (optional for listing all pull requests). + +.PARAMETER Status + The new status of the pull request. Allowed values: active, abandoned, completed. + +.PARAMETER Title + The new title for the pull request (max 256 characters). + +.PARAMETER Description + The new description for the pull request (max 4000 characters). + +.PARAMETER CompletionOptions + Specifies how the PR should be completed. Example: @{ deleteSourceBranch = $true; mergeCommitMessage = "Merged PR" } + +.PARAMETER MergeOptions + Specifies how the PR should be merged. Allowed values: noMerge, squash, rebase, rebaseMerge. + +.PARAMETER AutoCompleteSetBy + The Azure DevOps user ID who sets the PR to auto-complete. + +.PARAMETER TargetRefName + The new target branch for the pull request. Example: "main" (automatically prefixed with "refs/heads/"). + Retargeting a pull request means changing the destination branch where the pull request will be merged. + +.EXAMPLE + # Update only the title and description of a pull request + Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -Title "Updated PR Title" -Description "New description" + +.EXAMPLE + # Set auto-complete with completion options + $completionOptions = @{ + deleteSourceBranch = $true + mergeCommitMessage = "Auto-merging PR" + } + Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -AutoCompleteSetBy "user-id-123" -CompletionOptions $completionOptions + +.EXAMPLE + # Change the merge strategy to squash and complete the PR + Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -MergeOptions "squash" -Status "completed" + +.EXAMPLE + # Retarget a pull request to a different branch + Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -TargetRefName "develop" + +.EXAMPLE + # Set auto-complete for a pull request with a transition work item option + $completionOptions = @{ + transitionWorkItems = $true + deleteSourceBranch = $true + } + Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -AutoCompleteSetBy "user-id-123" -CompletionOptions $completionOptions + + +.OUTPUTS + PSCustomObject with pull request details. + +.NOTES + Requires authentication with Azure DevOps REST API. + + I have currently added the 'extra parameters' to the function, that are registered in the first paragraph on this page: + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/update?view=azure-devops-rest-7.2&tabs=HTTP#request-body + + With the text currently being: + These are the properties that can be updated with the API: + Status + Title + Description (up to 4000 characters) + CompletionOptions + MergeOptions + AutoCompleteSetBy.Id + TargetRefName (when the PR retargeting feature is enabled) Attempting to update other properties outside of this list will either cause the server to throw an InvalidArgumentValueException, or to silently ignore the update. + +.LINK + https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/update?view=azure-devops-rest-7.2&tabs=HTTP#request-body +#> + [CmdletBinding(SupportsShouldProcess)] + param ( + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] + [string] + $CollectionUri, + + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $ProjectName, + + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $RepositoryName, + + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $PullRequestId, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [ValidateSet('active', 'abandoned', 'completed', 'all')] + [string] + $Status, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [ValidateLength(0, 256)] + [string] + $Title, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [ValidateLength(0, 4000)] + [string] + $Description, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [ValidateSet('setAutoComplete', 'setAutoCompleteSetBy')] + [string] + $CompletionOptions, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [ValidateSet('noMerge', 'squash', 'rebase', 'rebaseMerge')] + [string] + $MergeOptions, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $AutoCompleteSetBy, + + [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $TargetRefName + ) + + begin { + $result = @() + Write-Verbose "Starting function: Set-AzDoPullRequest" + } + + process { + $uriBase = "$CollectionUri/$ProjectName/_apis/git" + $apiVersion = "7.2-preview.2" + + $body = @{} + + if ($Status) { $body["status"] = $Status } + if ($Title) { $body["title"] = $Title } + if ($Description) { $body["description"] = $Description } + if ($MergeOptions) { $body["mergeOptions"] = $MergeOptions } + if ($TargetRefName) { $body["targetRefName"] = "refs/heads/$TargetRefName" } + + if ($CompletionOptions -and $CompletionOptions.Count -gt 0) { + $body["completionOptions"] = $CompletionOptions + } + + if ($AutoCompleteSetBy) { + $body["autoCompleteSetBy"] = @{ id = $AutoCompleteSetBy } + } + + if ($PSCmdlet.ShouldProcess($CollectionUri, "Get Pull Request from: $ProjectName")) { + Write-Verbose "Calling API: $uri" + + $InvokeAzDoRestMethodSplat = @{ + Uri = "$uriBase/repositories/$RepositoryName/pullrequests/$PullRequestId" + Method = "PATCH" + Version = $apiVersion + Body = $Body + } + $response = Invoke-AzDoRestMethod @InvokeAzDoRestMethodSplat + if ($response.value) { + $result += $response.value + } else { + $result += $response + } + if ($result) { + $result | ForEach-Object { + [PSCustomObject]@{ + CollectionUri = $CollectionUri + ProjectName = $ProjectName + RepoName = $RepoName + PullRequest = $PSItem + } + } + } + } + } +} From a0fcf9e801dc499e81728389f9f0eab1c5741833 Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Feb 2025 14:47:14 +0100 Subject: [PATCH 2/7] feat: Add Get-AzDoProjectProperties and Remove-AzDoEnvironment functions --- .../Projects/Get-AzDoProjectProperties.ps1 | 78 ++++++++++++++++++ .../Environments/Remove-AzDoEnvironment.ps1 | 82 +++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 create mode 100644 AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 diff --git a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 new file mode 100644 index 00000000..6d70ebec --- /dev/null +++ b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 @@ -0,0 +1,78 @@ +function Get-AzDoProjectProperties { + <# +.SYNOPSIS + +.DESCRIPTION + +.EXAMPLE + +.EXAMPLE + +.EXAMPLE + +.EXAMPLE + +.OUTPUTS +#> + [CmdletBinding(SupportsShouldProcess)] + param ( + # Collection Uri of the organization + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] + [string] + $CollectionUri, + + # Project where the Repos are contained + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string[]] + $ProjectName + ) + + begin { + Write-Verbose "Starting function: Get-AzDoProject" + } + + process { + $Results = foreach ($Project in $ProjectName) { + $ProjectId = (Get-AzDoProject -CollectionUri $CollectionUri -ProjectName $Project).ProjectID + + $params = @{ + uri = "$CollectionUri/_apis/projects/$ProjectId/Properties" + version = "7.2-preview.1" + method = 'GET' + } + + if ($PSCmdlet.ShouldProcess($CollectionUri, "Get project $Project properties")) { + $result = Invoke-AzDoRestMethod @params + # $ResultsList.Add($result) + [PSCustomObject]@{ + CollectionURI = $CollectionUri + ProjectName = $Project + Properties = $Result + } + } else { + Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)" + } + } + if ($Results) { + $Results | ForEach-Object { + [PSCustomObject]@{ + CollectionURI = $CollectionUri + ProjectName = $_.ProjectName + Properties = $_.Properties + } + } + } + } + # end { + # if ($ResultsList) { + # $ResultsList | ForEach-Object { + # [PSCustomObject]@{ + # CollectionURI = $CollectionUri + # ProjectName = $_.name + # Properties = $Result + # } + # } + # } + # } +} diff --git a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 new file mode 100644 index 00000000..660a3353 --- /dev/null +++ b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 @@ -0,0 +1,82 @@ +function Remove-AzDoEnvironment { + <# + .SYNOPSIS + Remove Environment from Azure DevOps. + + .DESCRIPTION + This function removes an environment from Azure DevOps. + + .EXAMPLE + Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1" + + .EXAMPLE + Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1", "Environment 2" + + .EXAMPLE + Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName 1 + + .EXAMPLE + Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName 1, 2 + + .EXAMPLE + Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1", 2 + #> + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] + [OutputType([System.Collections.ArrayList])] + param ( + # Collection URI. e.g. https://dev.azure.com/contoso. + # Azure Pipelines has a predefined variable for this. + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] + [string] + $CollectionUri, + + # Name of the project. + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $ProjectName, + + # Id or name of the environment. + # this is a string because a name can be used as well and will do a Get-AzDoEnvironment to get the ID. + [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string[]] + $EnvironmentName + ) + + begin { + $result = @() + Write-Verbose "Starting function: Remove-AzDoEnvironment" + } + + Process { + + foreach ($Environment in $EnvironmentName) { + if ($Environment -ne [int]) { + $EnvironmentId = (Get-AzDoEnvironment -CollectionUri $CollectionUri -ProjectName $ProjectName -EnvironmentName $Environment).EnvironmentId + + } else { + $EnvironmentId = $Environment + } + + $params = @{ + uri = "$CollectionUri/$ProjectName/_apis/pipelines/environments/$EnvironmentId" + version = "7.2-preview.1" + method = 'DELETE' + } + + if ($PSCmdlet.ShouldProcess($CollectionUri, "Remove environment id: $($PSStyle.Bold)$EnvironmentId$($PSStyle.Reset)")) { + $result += Invoke-AzDoRestMethod @params + } else { + Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)" + } + } + if ($result) { + $result | ForEach-Object { + [PSCustomObject]@{ + CollectionUri = $CollectionUri + ProjectName = $ProjectName + } + } + } + } +} From db8e50065b18b7a72d99fd4c73a5916316a85a7a Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Mar 2025 09:06:40 +0100 Subject: [PATCH 3/7] =?UTF-8?q?feat:=20=E2=9C=A8=20Add=20Get-AzDoPipelineB?= =?UTF-8?q?ranchControl=20function?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Introduced `Get-AzDoPipelineBranchControl` to retrieve branch policy configurations for Azure DevOps projects. - Enhanced `Get-AzDoProjectProperties` with improved handling of project names and properties retrieval. - Supports pipeline input for project names and collection URI. --- .../Projects/Get-AzDoProjectProperties.ps1 | 75 ++++++------- .../Get-AzDoPipelineBranchControl.ps1 | 101 ++++++++++++++++++ 2 files changed, 131 insertions(+), 45 deletions(-) create mode 100644 AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 diff --git a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 index 6d70ebec..7d6db413 100644 --- a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 @@ -1,19 +1,21 @@ -function Get-AzDoProjectProperties { - <# +<# .SYNOPSIS +Retrieves properties of specified Azure DevOps projects. .DESCRIPTION +The Get-AzDoProjectProperties function retrieves properties of specified Azure DevOps projects within a given collection URI. It supports pipeline input for project names and collection URI. .EXAMPLE +PS> Get-AzDoProjectProperties -CollectionUri "https://dev.azure.com/organization" -ProjectName "Project1" .EXAMPLE +PS> "Project1", "Project2" | Get-AzDoProjectProperties -CollectionUri "https://dev.azure.com/organization" -.EXAMPLE - -.EXAMPLE - -.OUTPUTS +.NOTES +This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. #> +function Get-AzDoProjectProperties { + [CmdletBinding(SupportsShouldProcess)] param ( # Collection Uri of the organization @@ -24,55 +26,38 @@ function Get-AzDoProjectProperties { # Project where the Repos are contained [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] - [string[]] + [string] $ProjectName ) begin { - Write-Verbose "Starting function: Get-AzDoProject" + Write-Verbose "Starting function: Get-AzDoProjectProperties" } process { - $Results = foreach ($Project in $ProjectName) { - $ProjectId = (Get-AzDoProject -CollectionUri $CollectionUri -ProjectName $Project).ProjectID + # somehow it will not work on project name, but will work like this: + $ProjectId = (Get-AzDoProject -CollectionUri $CollectionUri -ProjectName $ProjectName).ProjectID + $params = @{ + uri = "$CollectionUri/_apis/projects/$ProjectId/Properties" + version = "7.2-preview.1" + method = 'GET' + } - $params = @{ - uri = "$CollectionUri/_apis/projects/$ProjectId/Properties" - version = "7.2-preview.1" - method = 'GET' - } + if ($PSCmdlet.ShouldProcess($CollectionUri, "Get project $ProjectName properties")) { + $result = Invoke-AzDoRestMethod @params + } else { + Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)" + } - if ($PSCmdlet.ShouldProcess($CollectionUri, "Get project $Project properties")) { - $result = Invoke-AzDoRestMethod @params - # $ResultsList.Add($result) - [PSCustomObject]@{ - CollectionURI = $CollectionUri - ProjectName = $Project - Properties = $Result - } - } else { - Write-Verbose "Calling Invoke-AzDoRestMethod with $($params| ConvertTo-Json -Depth 10)" + if ($result) { + $HashTable = @{ + CollectionURI = $CollectionUri + ProjectName = $ProjectName } - } - if ($Results) { - $Results | ForEach-Object { - [PSCustomObject]@{ - CollectionURI = $CollectionUri - ProjectName = $_.ProjectName - Properties = $_.Properties - } + foreach ($property in $result.value) { + $HashTable[$property.Name] = $property.Value } + [PSCustomObject]$HashTable } } - # end { - # if ($ResultsList) { - # $ResultsList | ForEach-Object { - # [PSCustomObject]@{ - # CollectionURI = $CollectionUri - # ProjectName = $_.name - # Properties = $Result - # } - # } - # } - # } } diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 new file mode 100644 index 00000000..2d7bfa02 --- /dev/null +++ b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 @@ -0,0 +1,101 @@ +<# +.SYNOPSIS +Retrieves branch policy configurations of specified Azure DevOps projects. + +.DESCRIPTION +The Get-AzDoPipelineBranchControl function retrieves branch policy configurations of specified Azure DevOps projects within a given collection URI. +It supports pipeline input for project names and collection URI. + +.EXAMPLE +PS> Get-AzDoPipelineBranchControl -CollectionUri "https://dev.azure.com/organization" -ProjectName "Project1" + +.EXAMPLE +PS> "Project1", "Project2" | Get-AzDoPipelineBranchControl -CollectionUri "https://dev.azure.com/organization" + +.NOTES +This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. +#> +function Get-AzDoPipelineBranchControl { + + [CmdletBinding(SupportsShouldProcess)] + param ( + # Collection URI of the organization + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] + [string] + $CollectionUri, + + # Project where the policies are defined + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] + [string] + $ProjectName, + + # Repository ID (optional) + [Parameter(ValueFromPipelineByPropertyName)] + [string] + $RepositoryId, + + # Ref name (branch) to filter policies (optional) + [Parameter(ValueFromPipelineByPropertyName)] + [string] + $RefName, + + # Policy type to filter results (optional) + [Parameter(ValueFromPipelineByPropertyName)] + [string] + $PolicyType + ) + + begin { + Write-Verbose "Starting function: Get-AzDoPipelineBranchControl" + } + + process { + # somehow it will not work on project name, but will work like this: + $ProjectId = (Get-AzDoProject -CollectionUri $CollectionUri -ProjectName $ProjectName).ProjectID + + $queryParams = @() + if ($RepositoryId) { + $queryParams += "repositoryId=$RepositoryId" + } + if ($RefName) { + $queryParams += "refName=$RefName" + } + if ($PolicyType) { + $queryParams += "policyType=$PolicyType" + } + $queryString = $queryParams -join "&" + + $params = @{ + Uri = "$CollectionUri/$ProjectId/_apis/git/policy/configurations" + Version = "5.0-preview.1" + Method = 'GET' + } + if (-not([string]::IsNullOrEmpty(($queryString)))) { + $params.QueryParameters = $queryString + } + if ($PSCmdlet.ShouldProcess($CollectionUri, "Get branch policies for project $ProjectName")) { + $response = Invoke-AzDoRestMethod @params + } else { + Write-Verbose "Calling Invoke-AzDoRestMethod with $($params | ConvertTo-Json -Depth 10)" + } + if ($response) { + $List = [System.Collections.Generic.List[Object]]::new() + foreach ($property in $response.Value) { + $Property | Add-Member -MemberType NoteProperty -Name "ProjectName" -Value $ProjectName + $Property | Add-Member -MemberType NoteProperty -Name "CollectionURI" -Value $CollectionUri + if ($RepositoryId) { + $Property | Add-Member -MemberType NoteProperty -Name "RepositoryId" -Value $RepositoryId + } + if ($RefName) { + $Property | Add-Member -MemberType NoteProperty -Name "RefName" -Value $RefName + } + if ($PolicyType) { + $Property | Add-Member -MemberType NoteProperty -Name "PolicyType" -Value $PolicyType + } + $List.Add($Property) + } + $List + } + } +} From cd2bf91487298ace07f0f7b616961665f4473d4d Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Mar 2025 09:14:55 +0100 Subject: [PATCH 4/7] =?UTF-8?q?docs:=20=F0=9F=93=9A=20Add=20.LINK=20sectio?= =?UTF-8?q?ns=20to=20Get-AzDoProjectProperties,=20Remove-AzDoEnvironment,?= =?UTF-8?q?=20and=20Get-AzDoPipelineBranchControl=20functions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added documentation links to relevant Azure DevOps REST API references for better guidance. --- .../Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 | 3 +++ .../Api/Environments/Environments/Remove-AzDoEnvironment.ps1 | 4 ++++ .../PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 | 3 +++ 3 files changed, 10 insertions(+) diff --git a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 index 7d6db413..26fc4025 100644 --- a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 @@ -13,6 +13,9 @@ PS> "Project1", "Project2" | Get-AzDoProjectProperties -CollectionUri "https://d .NOTES This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. + +.LINK +https://learn.microsoft.com/en-us/rest/api/azure/devops/core/projects/get-project-properties?view=azure-devops-rest-7.1&tabs=HTTP #> function Get-AzDoProjectProperties { diff --git a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 index 660a3353..fa37105e 100644 --- a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 @@ -20,6 +20,9 @@ function Remove-AzDoEnvironment { .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1", 2 + + .LINK + https://learn.microsoft.com/en-us/rest/api/azure/devops/environments/environments/delete?view=azure-devops-rest-7.2 #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] [OutputType([System.Collections.ArrayList])] @@ -75,6 +78,7 @@ function Remove-AzDoEnvironment { [PSCustomObject]@{ CollectionUri = $CollectionUri ProjectName = $ProjectName + Response = $_ } } } diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 index 2d7bfa02..3aa41aad 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 @@ -14,6 +14,9 @@ PS> "Project1", "Project2" | Get-AzDoPipelineBranchControl -CollectionUri "https .NOTES This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. + +.LINK +https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/list?view=azure-devops-rest-5.0#policyconfiguration #> function Get-AzDoPipelineBranchControl { From 4703b87f619679485e8ad8122fac7748848a1fd5 Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Mar 2025 09:41:57 +0100 Subject: [PATCH 5/7] =?UTF-8?q?docs:=20=F0=9F=93=9A=20Add=20.LINK=20sectio?= =?UTF-8?q?ns=20to=20Get-AzDoPullRequest=20function?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added multiple .LINK sections to provide direct references to Azure DevOps REST API documentation for pull requests. --- .../Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 index 26e79a8c..24104880 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 @@ -47,8 +47,14 @@ function Get-AzDoPullRequest { .LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-request?view=azure-devops-rest-7.2 + +.LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-request-by-id?view=azure-devops-rest-7.2 + +.LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests?view=azure-devops-rest-7.2 + +.LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests-by-project?view=azure-devops-rest-7.2 #> [CmdletBinding(DefaultParameterSetName = "AllProjectPullRequests", SupportsShouldProcess)] From c7e2d981ea7c163619b66337b7c030085575e4af Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Mar 2025 10:28:30 +0100 Subject: [PATCH 6/7] =?UTF-8?q?docs:=20=F0=9F=93=9A=20Update=20examples=20?= =?UTF-8?q?in=20`Remove-AzDoEnvironment`,=20`Get-AzDoProjectProperties`,?= =?UTF-8?q?=20`Get-AzDoEnvironment`,=20and=20`Get-AzDoPipelineBranchContro?= =?UTF-8?q?l`=20functions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enhanced documentation with additional examples for clarity. - Provided detailed usage scenarios for removing environments and retrieving project properties. - Improved consistency across function documentation. --- .../Projects/Get-AzDoProjectProperties.ps1 | 20 ++- .../Environments/Get-AzDoEnvironment.ps1 | 33 ++-- .../Environments/Remove-AzDoEnvironment.ps1 | 10 ++ .../Get-AzDoPipelineBranchControl.ps1 | 32 +++- .../Git/PullRequests/Get-AzDoPullRequest.ps1 | 66 +++++--- .../Git/PullRequests/Set-AzDoPullRequest.ps1 | 155 +++++++++--------- 6 files changed, 198 insertions(+), 118 deletions(-) diff --git a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 index 26fc4025..87c8462b 100644 --- a/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Core/Projects/Get-AzDoProjectProperties.ps1 @@ -1,4 +1,5 @@ -<# +function Get-AzDoProjectProperties { + <# .SYNOPSIS Retrieves properties of specified Azure DevOps projects. @@ -6,10 +7,21 @@ Retrieves properties of specified Azure DevOps projects. The Get-AzDoProjectProperties function retrieves properties of specified Azure DevOps projects within a given collection URI. It supports pipeline input for project names and collection URI. .EXAMPLE -PS> Get-AzDoProjectProperties -CollectionUri "https://dev.azure.com/organization" -ProjectName "Project1" +$Params = @{ + CollectionUri = "https://dev.azure.com/organization" + ProjectName = "Project1" +} +Get-AzDoProjectProperties @Params + +This example retrieves properties of the project named "Project1" in the specified Azure DevOps organization. .EXAMPLE -PS> "Project1", "Project2" | Get-AzDoProjectProperties -CollectionUri "https://dev.azure.com/organization" +$Params = @{ + CollectionUri = "https://dev.azure.com/organization" +} +"Project1", "Project2" | Get-AzDoProjectProperties @Params + +This example retrieves properties of multiple projects ("Project1" and "Project2") in the specified Azure DevOps organization. .NOTES This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. @@ -17,8 +29,6 @@ This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod help .LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/core/projects/get-project-properties?view=azure-devops-rest-7.1&tabs=HTTP #> -function Get-AzDoProjectProperties { - [CmdletBinding(SupportsShouldProcess)] param ( # Collection Uri of the organization diff --git a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Get-AzDoEnvironment.ps1 b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Get-AzDoEnvironment.ps1 index b29b2002..4f646f9e 100644 --- a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Get-AzDoEnvironment.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Get-AzDoEnvironment.ps1 @@ -4,24 +4,35 @@ function Get-AzDoEnvironment { Creates a Build Validation policy on a branch .DESCRIPTION Creates a Build Validation policy on a branch + .EXAMPLE - $params = @{ + $Params = @{ CollectionUri = "https://dev.azure.com/contoso" - Name = "Policy 1" - RepoName = "Repo 1" - ProjectName = "Project 1" - Id = 1 + ProjectName = "Project 1" } - Set-AzDoBranchPolicyBuildValidation @params + Get-AzDoEnvironment @Params - This example creates a policy with splatting parameters + This example retrieves all environments in the specified project ("Project 1") in Azure DevOps. .EXAMPLE - $env:SYSTEM_ACCESSTOKEN = '***' - New-AzDoPipeline -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -Name "Pipeline 1" -RepoName "Repo 1" -Path "main.yml" - | Set-AzDoBranchPolicyBuildValidation + $Params = @{ + CollectionUri = "https://dev.azure.com/contoso" + ProjectName = "Project 1" + EnvironmentName = "Environment 1" + } + Get-AzDoEnvironment @Params + + This example retrieves details of the environment named "Environment 1" in the specified project ("Project 1") in Azure DevOps. + +.EXAMPLE + $Params = @{ + CollectionUri = "https://dev.azure.com/contoso" + ProjectName = "Project 1" + EnvironmentName = @("Environment 1", "Environment 2") + } + Get-AzDoEnvironment @Params - This example creates a new Azure Pipeline and sets this pipeline as Build Validation policy on the main branch + This example retrieves details of multiple environments ("Environment 1" and "Environment 2") in the specified project ("Project 1") in Azure DevOps. .OUTPUTS [PSCustomObject]@{ diff --git a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 index fa37105e..9cd8ccc9 100644 --- a/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Environments/Environments/Remove-AzDoEnvironment.ps1 @@ -9,18 +9,28 @@ function Remove-AzDoEnvironment { .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1" + This example removes the environment named "Environment 1" from the specified project in Azure DevOps. + .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1", "Environment 2" + This example removes multiple environments ("Environment 1" and "Environment 2") from the specified project in Azure DevOps. + .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName 1 + This example removes the environment with the ID 1 from the specified project in Azure DevOps. + .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName 1, 2 + This example removes multiple environments with IDs 1 and 2 from the specified project in Azure DevOps. + .EXAMPLE Remove-AzDoEnvironment -CollectionUri "https://dev.azure.com/contoso" -ProjectName "Project 1" -EnvironmentName "Environment 1", 2 + This example removes a mix of environments by name ("Environment 1") and ID (2) from the specified project in Azure DevOps. + .LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/environments/environments/delete?view=azure-devops-rest-7.2 #> diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 index 3aa41aad..1ea174b8 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PolicyConfigurations/Get-AzDoPipelineBranchControl.ps1 @@ -1,4 +1,5 @@ -<# +function Get-AzDoPipelineBranchControl { + <# .SYNOPSIS Retrieves branch policy configurations of specified Azure DevOps projects. @@ -7,10 +8,33 @@ The Get-AzDoPipelineBranchControl function retrieves branch policy configuration It supports pipeline input for project names and collection URI. .EXAMPLE -PS> Get-AzDoPipelineBranchControl -CollectionUri "https://dev.azure.com/organization" -ProjectName "Project1" +$Params = @{ + CollectionUri = "https://dev.azure.com/organization" + ProjectName = "Project1" +} +Get-AzDoPipelineBranchControl @Params + +This example retrieves branch policy configurations for the project named "Project1" in the specified Azure DevOps organization. .EXAMPLE -PS> "Project1", "Project2" | Get-AzDoPipelineBranchControl -CollectionUri "https://dev.azure.com/organization" +$Params = @{ + CollectionUri = "https://dev.azure.com/organization" +} +"Project1", "Project2" | Get-AzDoPipelineBranchControl @Params + +This example retrieves branch policy configurations for multiple projects ("Project1" and "Project2") in the specified Azure DevOps organization. + +.EXAMPLE +$Params = @{ + CollectionUri = "https://dev.azure.com/organization" + ProjectName = "Project1" + RepositoryId = "12345" + RefName = "refs/heads/main" + PolicyType = "Build" +} +Get-AzDoPipelineBranchControl @Params + +This example retrieves branch policy configurations for the "main" branch in the repository with ID "12345" in the project "Project1" in the specified Azure DevOps organization, filtered by the "Build" policy type. .NOTES This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod helper functions to be defined in the scope. @@ -18,8 +42,6 @@ This function requires the Validate-CollectionUri and Invoke-AzDoRestMethod help .LINK https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/list?view=azure-devops-rest-5.0#policyconfiguration #> -function Get-AzDoPipelineBranchControl { - [CmdletBinding(SupportsShouldProcess)] param ( # Collection URI of the organization diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 index 24104880..a8220cf1 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Get-AzDoPullRequest.ps1 @@ -6,38 +6,56 @@ function Get-AzDoPullRequest { .DESCRIPTION This function fetches pull request details using Azure DevOps REST API. -.PARAMETER CollectionUri - The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org). - -.PARAMETER ProjectName - The name of the Azure DevOps project. +.EXAMPLE + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + } + Get-AzDoPullRequest @Params -.PARAMETER RepositoryName - The name of the repository (optional for project-wide pull request queries). + This example retrieves all pull requests for the specified project. -.PARAMETER PullRequestId - The ID of a specific pull request (optional for listing all pull requests). +.EXAMPLE + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "RepositoryName" + } + Get-AzDoPullRequest @Params -.PARAMETER Query - A query string to filter the results (optional). - Can only be used without PullRequestId: - https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests?view=azure-devops-rest-7.2&tabs=HTTP#uri-parameters - https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/get-pull-requests-by-project?view=azure-devops-rest-7.2&tabs=HTTP#uri-parameters + This example retrieves all pull requests for the specified repository in the project. .EXAMPLE - Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "RepositoryName" + Query = "searchCriteria.status=completed" + } + Get-AzDoPullRequest @Params -.EXAMPLE - Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" + This example retrieves all completed pull requests for the specified repository in the project. .EXAMPLE - Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" -Query "searchCriteria.status=completed" + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "RepositoryName" + PullRequestId = "6789" + } + Get-AzDoPullRequest @Params -.EXAMPLE - Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "RepositoryName" -PullRequestId "6789" + This example retrieves details of a specific pull request by its ID for the specified repository in the project. .EXAMPLE - Get-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -PullRequestId "6789" + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + PullRequestId = "6789" + } + Get-AzDoPullRequest @Params + + This example retrieves details of a specific pull request by its ID for the specified project. .OUTPUTS PSCustomObject with pull request details. @@ -59,6 +77,7 @@ function Get-AzDoPullRequest { #> [CmdletBinding(DefaultParameterSetName = "AllProjectPullRequests", SupportsShouldProcess)] param ( + # The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org) [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "RepoSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "ProjectSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] @@ -67,6 +86,7 @@ function Get-AzDoPullRequest { [string] $CollectionUri, + # The name of the Azure DevOps project. [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "RepoSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "ProjectSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] @@ -74,22 +94,24 @@ function Get-AzDoPullRequest { [string] $ProjectName, + # The name of the repository (optional for project-wide pull request queries). [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "RepoSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "AllRepoPullRequests")] [string] $RepoName, + # The ID of a specific pull request (optional for listing all pull requests). [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "RepoSpecificPullRequest")] [Parameter(Mandatory, ValueFromPipeline, ParameterSetName = "ProjectSpecificPullRequest")] [string] $PullRequestId, + # A query string to filter the results (optional). [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = "AllRepoPullRequests")] [string] $Query ) - begin { $result = @() Write-Verbose "Starting function: Get-AzDoPullRequest" diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 index 5f612b09..f5f31510 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 @@ -1,145 +1,150 @@ function Set-AzDoPullRequest { <# .SYNOPSIS - Retrieves pull request information from Azure DevOps. + Updates pull request details in Azure DevOps. .DESCRIPTION - This function fetches pull request details using Azure DevOps REST API. + This function updates pull request details using Azure DevOps REST API. -.PARAMETER CollectionUri - The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org). - -.PARAMETER ProjectName - The name of the Azure DevOps project. - -.PARAMETER RepositoryName - The name of the repository (optional for project-wide pull request queries). - -.PARAMETER PullRequestId - The ID of a specific pull request (optional for listing all pull requests). - -.PARAMETER Status - The new status of the pull request. Allowed values: active, abandoned, completed. - -.PARAMETER Title - The new title for the pull request (max 256 characters). - -.PARAMETER Description - The new description for the pull request (max 4000 characters). - -.PARAMETER CompletionOptions - Specifies how the PR should be completed. Example: @{ deleteSourceBranch = $true; mergeCommitMessage = "Merged PR" } +.EXAMPLE + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "Repo" + PullRequestId = "123" + Title = "Updated PR Title" + Description = "New description" + } + Set-AzDoPullRequest @Params -.PARAMETER MergeOptions - Specifies how the PR should be merged. Allowed values: noMerge, squash, rebase, rebaseMerge. + This example updates only the title and description of a pull request. -.PARAMETER AutoCompleteSetBy - The Azure DevOps user ID who sets the PR to auto-complete. +.EXAMPLE + $completionOptions = @{ + deleteSourceBranch = $true + mergeCommitMessage = "Auto-merging PR" + } + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "Repo" + PullRequestId = "123" + AutoCompleteSetBy = "user-id-123" + CompletionOptions = $completionOptions + } + Set-AzDoPullRequest @Params -.PARAMETER TargetRefName - The new target branch for the pull request. Example: "main" (automatically prefixed with "refs/heads/"). - Retargeting a pull request means changing the destination branch where the pull request will be merged. + This example sets auto-complete for a pull request with completion options. .EXAMPLE - # Update only the title and description of a pull request - Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -Title "Updated PR Title" -Description "New description" + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "Repo" + PullRequestId = "123" + MergeOptions = "squash" + Status = "completed" + } + Set-AzDoPullRequest @Params -.EXAMPLE - # Set auto-complete with completion options - $completionOptions = @{ - deleteSourceBranch = $true - mergeCommitMessage = "Auto-merging PR" - } - Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -AutoCompleteSetBy "user-id-123" -CompletionOptions $completionOptions + This example changes the merge strategy to squash and completes the pull request. .EXAMPLE - # Change the merge strategy to squash and complete the PR - Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -MergeOptions "squash" -Status "completed" + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "Repo" + PullRequestId = "123" + TargetRefName = "develop" + } + Set-AzDoPullRequest @Params -.EXAMPLE - # Retarget a pull request to a different branch - Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -TargetRefName "develop" + This example retargets a pull request to a different branch. .EXAMPLE - # Set auto-complete for a pull request with a transition work item option - $completionOptions = @{ - transitionWorkItems = $true - deleteSourceBranch = $true - } - Set-AzDoPullRequest -CollectionUri "https://dev.azure.com/my-org" -ProjectName "MyProject" -RepositoryName "Repo" -PullRequestId "123" -AutoCompleteSetBy "user-id-123" -CompletionOptions $completionOptions + $completionOptions = @{ + transitionWorkItems = $true + deleteSourceBranch = $true + } + $Params = @{ + CollectionUri = "https://dev.azure.com/my-org" + ProjectName = "MyProject" + RepositoryName = "Repo" + PullRequestId = "123" + AutoCompleteSetBy = "user-id-123" + CompletionOptions = $completionOptions + } + Set-AzDoPullRequest @Params + This example sets auto-complete for a pull request with a transition work item option. .OUTPUTS PSCustomObject with pull request details. .NOTES Requires authentication with Azure DevOps REST API. - - I have currently added the 'extra parameters' to the function, that are registered in the first paragraph on this page: - https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/update?view=azure-devops-rest-7.2&tabs=HTTP#request-body - - With the text currently being: - These are the properties that can be updated with the API: - Status - Title - Description (up to 4000 characters) - CompletionOptions - MergeOptions - AutoCompleteSetBy.Id - TargetRefName (when the PR retargeting feature is enabled) Attempting to update other properties outside of this list will either cause the server to throw an InvalidArgumentValueException, or to silently ignore the update. - -.LINK - https://learn.microsoft.com/en-us/rest/api/azure/devops/git/pull-requests/update?view=azure-devops-rest-7.2&tabs=HTTP#request-body #> [CmdletBinding(SupportsShouldProcess)] param ( + # The base URL of the Azure DevOps organization (e.g., https://dev.azure.com/my-org). [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateScript({ Validate-CollectionUri -CollectionUri $_ })] [string] $CollectionUri, + # The name of the Azure DevOps project. [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] $ProjectName, + # The name of the repository (optional for project-wide pull request queries). [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] $RepositoryName, + # The ID of a specific pull request (optional for listing all pull requests). [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] $PullRequestId, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # The new status of the pull request. Allowed values: active, abandoned, completed. + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [ValidateSet('active', 'abandoned', 'completed', 'all')] [string] $Status, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # The new title for the pull request (max 256 characters). + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [ValidateLength(0, 256)] [string] $Title, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # The new description for the pull request (max 4000 characters). + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [ValidateLength(0, 4000)] [string] $Description, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # Specifies how the PR should be completed. Example: @{ deleteSourceBranch = $true; mergeCommitMessage = "Merged PR" } + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [ValidateSet('setAutoComplete', 'setAutoCompleteSetBy')] [string] $CompletionOptions, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # Specifies how the PR should be merged. Allowed values: noMerge, squash, rebase, rebaseMerge. + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [ValidateSet('noMerge', 'squash', 'rebase', 'rebaseMerge')] [string] $MergeOptions, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # The Azure DevOps user ID who sets the PR to auto-complete. + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] $AutoCompleteSetBy, - [Parameter( ValueFromPipelineByPropertyName, ValueFromPipeline)] + # The new target branch for the pull request. Example: "main" (automatically prefixed with "refs/heads/"). + # Retargeting a pull request means changing the destination branch where the pull request will be merged. + [Parameter(ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] $TargetRefName ) From fcdc92266c2e7ba43d5fadb8fd5be3d439b1e0bf Mon Sep 17 00:00:00 2001 From: Bas Wijdenes Date: Fri, 28 Mar 2025 10:36:08 +0100 Subject: [PATCH 7/7] =?UTF-8?q?fix(pull-request):=20=F0=9F=90=9B=20Rename?= =?UTF-8?q?=20parameter=20`$RepositoryName`=20to=20`$RepoName`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Improved parameter naming for clarity in the `Set-AzDoPullRequest` function. * This change enhances consistency with other function parameters. --- .../Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 index f5f31510..37c8c8fe 100644 --- a/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 +++ b/AzureDevOpsPowerShell/Public/Api/Git/PullRequests/Set-AzDoPullRequest.ps1 @@ -100,7 +100,7 @@ function Set-AzDoPullRequest { # The name of the repository (optional for project-wide pull request queries). [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)] [string] - $RepositoryName, + $RepoName, # The ID of a specific pull request (optional for listing all pull requests). [Parameter(Mandatory, ValueFromPipelineByPropertyName, ValueFromPipeline)]