DevOps.Repos.ps1

<#
    .SYNOPSIS
    Get all repos from Azure DevOps project

    .DESCRIPTION
    Get all repos from Azure DevOps project using Azure DevOps Rest API

    .PARAMETER Project
    Project name for Azure DevOps

    .EXAMPLE
    Get-AzDevOpsRepos -Project $Project
#>
Function Get-AzDevOpsRepos {
    [CmdletBinding()]
    [OutputType([System.Object[]])]
    param (
        [Parameter(Mandatory)]
        [string]
        $Project,
        [Parameter(Mandatory=$false)]
        [switch]
        $IncludeDisabled
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $header = $script:connection.GetHeader()
    Write-Verbose "Getting repos for project $Project"
    $uri = "https://dev.azure.com/$Organization/$Project/_apis/git/repositories?api-version=6.0"
    Write-Verbose "URI: $uri"
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header
        # If the response is a string and not an object, throw an exception for authentication failure or project not found
        if ($response -is [string]) {
            throw "Authentication failed or project not found"
        }
    }
    catch {
        throw $_.Exception.Message
    }
    # If the IncludeDisabled switch is set, return all repos including disabled ones
    if ($IncludeDisabled -eq $true) {
        return @($response.value)
    }
    return @($response.value | Where-Object { $_.isDisabled -eq $false })
}
Export-ModuleMember -Function Get-AzDevOpsRepos
# End of Function Get-AzDevOpsRepos

<#
    .SYNOPSIS
    Get Azure DevOps branches for a repo

    .DESCRIPTION
    Get Azure DevOps branches for a repo using Azure DevOps Rest API

    .PARAMETER Project
    Project name for Azure DevOps

    .PARAMETER Repository
    Repository name for Azure DevOps

    .EXAMPLE
    Get-AzDevOpsBranches -Project $Project -Repository $Repository
#>
Function Get-AzDevOpsBranches {
    [CmdletBinding()]
    [OutputType([System.Object[]])]
    param (
        [Parameter(Mandatory)]
        [string]
        $Project,
        [Parameter(Mandatory)]
        [string]
        $Repository
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $header = $script:connection.GetHeader()
    Write-Verbose "Getting branches for repo $Repository in project $Project"
    $uri = "https://dev.azure.com/$Organization/_apis/git/repositories/$Repository/refs?filter=heads&includeStatuses=true&latestStatusesOnly=true&api-version=7.2-preview.2"
    $statsUri = "https://dev.azure.com/$Organization/$Project/_apis/git/repositories/$Repository/stats/branches?api-version=7.2-preview.2"
    Write-Verbose "URI: $uri"
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header
        # If the response is a string and not an object, throw an exception for authentication failure or project not found
        if ($response -is [string]) {
            throw "Authentication failed or project not found"
        }
    }
    catch {
        throw $_.Exception.Message
    }
    try {
        $statsResponse = Invoke-RestMethod -Uri $statsUri -Method Get -Headers $header
    }
    catch {
        $statsResponse = $null
    }
    $result = @($response.value | ForEach-Object {
        $branch = $_
        If($null -eq $statsResponse) {
            $branchStats = $null
        } else {
            $branchStats = $statsResponse.value | Where-Object {$_.name -eq ($branch.name -replace "refs/heads/","")}
        }
        $branch | Add-Member -MemberType NoteProperty -Name Stats -Value $branchStats
        $branch
    })
    return @($result)
}
Export-ModuleMember -Function Get-AzDevOpsBranches

<#
    .SYNOPSIS
    Get Azure DevOps branch policy for a branch in a repo

    .DESCRIPTION
    Get Azure DevOps branch policy for a branch in a repo using Azure DevOps Rest API

    .PARAMETER Project
    Project name for Azure DevOps

    .PARAMETER Repository
    Repository name for Azure DevOps

    .PARAMETER Branch
    Branch name for Azure DevOps as a git ref. Example: refs/heads/main

    .EXAMPLE
    Get-AzDevOpsBranchPolicy -Project $Project -Repository $Repository -Branch $Branch

    .NOTES
    This function returns an empty object if no branch policy is found for the branch
#>
Function Get-AzDevOpsBranchPolicy {
    [CmdletBinding()]
    [OutputType([object[]])]
    param (
        [Parameter(Mandatory)]
        [string]
        $Project,
        [Parameter(Mandatory)]
        [string]
        $Repository,
        [Parameter(Mandatory)]
        [string]
        $Branch
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $header = $script:connection.GetHeader()
    Write-Verbose "Getting branch policy for branch $Branch in repo $Repository in project $Project"
    $uri = "https://dev.azure.com/$Organization/$Project/_apis/policy/configurations?api-version=6.0"
    Write-Verbose "URI: $uri"
    # Try to get the branch policy, return an empty object if no branch policy is found for the branch
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header
        # If the response is a string and not an object, throw an exception for authentication failure or project not found
        if ($response -is [string]) {
            throw "Authentication failed or project not found"
        }
    }
    catch {
        throw $_.Exception.Message
    }
    $branchPolicy = @($response.value | Where-Object {$_.settings.scope.refName -eq $Branch -and $_.settings.scope.repositoryId -eq $Repository})

    return $branchPolicy
}
Export-ModuleMember -Function Get-AzDevOpsBranchPolicy
# End of Function Get-AzDevOpsBranchPolicy

<#
    .SYNOPSIS
    Get Repository pipeline permissions for a repo

    .DESCRIPTION
    Get Repository pipeline permissions for a repo using Azure DevOps Rest API

    .PARAMETER ProjectId
    Project ID for Azure DevOps project

    .PARAMETER RepositoryId
    Repository ID for Azure DevOps

    .EXAMPLE
    Get-AzDevOpsRepositoryPipelinePermissions -ProjectId $ProjectId -RepositoryId $RepositoryId
#>
Function Get-AzDevOpsRepositoryPipelinePermissions {
    [CmdletBinding()]
    [OutputType([object[]])]
    param (
        [Parameter(Mandatory)]
        [string]
        $ProjectId,
        [Parameter(Mandatory)]
        [string]
        $RepositoryId
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $header = $script:connection.GetHeader()
    $uri = "https://dev.azure.com/{0}/{1}/_apis/pipelines/pipelinePermissions/repository/{2}.{3}" -f $Organization, $ProjectId, $ProjectId, $RepositoryId
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header -ContentType "application/json"
        # If the response is a string and not an object, throw an exception for authentication failure or project not found
        if ($response -is [string]) {
            throw "Authentication failed or project not found"
        }
    }
    catch {
        throw $_.Exception.Message
    }
    return $response
}
Export-ModuleMember -Function Get-AzDevOpsRepositoryPipelinePermissions
# End of Function Get-AzDevOpsRepositoryPipelinePermissions

<#
    .SYNOPSIS
    Get Azure DevOps repos ACLs

    .DESCRIPTION
    Get Azure DevOps repos ACLs using Azure DevOps Rest API

    .PARAMETER ProjectId
    Project ID for Azure DevOps project

    .PARAMETER RepositoryId
    Repository ID for Azure DevOps

    .EXAMPLE
    Get-AzDevOpsRepositoryAcls -ProjectId $ProjectId -RepositoryId $RepositoryId
#>
Function Get-AzDevOpsRepositoryAcls {
    [CmdletBinding()]
    [OutputType([object[]])]
    param (
        [Parameter(Mandatory)]
        [string]
        $ProjectId,
        [Parameter(Mandatory)]
        [string]
        $RepositoryId
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $TokenType = $script:connection.TokenType
    # If the token type is ReadOnly, write a warning and return null
    if ($TokenType -eq "ReadOnly") {
        Write-Warning "The ReadOnly token type does not have access to the Repositories ACLs API, returning null"
        return $null
    } else {
        $header = $script:connection.GetHeader()
        $uri = "https://dev.azure.com/{0}/_apis/accesscontrollists/2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87?api-version=7.2-preview.1&token=repoV2/{1}/{2}" -f $Organization, $ProjectId, $RepositoryId
        try {
            $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header -ContentType "application/json"
            # If the response is a string and not an object, throw an exception for authentication failure or project not found
            if ($response -is [string]) {
                throw "Authentication failed or project not found"
            }
            $thisRepoPerms = $response.value
        }
        catch {
            throw $_.Exception.Message
        }
        return $thisRepoPerms
    }
}
Export-ModuleMember -Function Get-AzDevOpsRepositoryAcls
# End of Function Get-AzDevOpsRepositoryAcls

<#
    .SYNOPSIS
    Check the existance of a file in an Azure DevOps repo

    .DESCRIPTION
    Check the existance of a file in an Azure DevOps repo using Azure DevOps Rest API

    .PARAMETER Project
    Project name for Azure DevOps

    .PARAMETER Repository
    Repository name for Azure DevOps

    .PARAMETER Path
    Path to file in repository

    .EXAMPLE
    Test-AzDevOpsFileExists -Project $Project -Repository $Repository -Path $Path

    .NOTES
    This function return $true if the file exists and $false if it does not
#>
function Test-AzDevOpsFileExists {
    [CmdletBinding()]
    [OutputType([bool])]
    param (
        [Parameter(Mandatory)]
        [string]
        $Project,
        [Parameter(Mandatory)]
        [string]
        $Repository,
        [Parameter(Mandatory)]
        [string]
        $Path
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $header = $script:connection.GetHeader()
    Write-Verbose "Checking if file $Path exists in repo $Repository in project $Project"
    $uri = "https://dev.azure.com/$Organization/$Project/_apis/git/repositories/$Repository/items?path=$Path&api-version=6.0"
    Write-Verbose "URI: $uri"
    try {
        $response = Invoke-RestMethod -Uri $uri -Method Get -Headers $header
    }
    catch {
        return $false
    }
    return $true
}
Export-ModuleMember -Function Test-AzDevOpsFileExists
# End of Function Test-AzDevOpsFileExists

<#
    .SYNOPSIS
    Get GitHub Advanced Security (GHAS) data for a repository

    .DESCRIPTION
    Get GitHub Advanced Security (GHAS) data for a repository using Azure DevOps Rest API

    .PARAMETER ProjectId
    Project ID for Azure DevOps

    .PARAMETER Repository
    Repository name for Azure DevOps

    .EXAMPLE
    Get-AzDevOpsRepositoryGhas -Project $Project -Repository $Repository
#>
Function Get-AzDevOpsRepositoryGhas {
    [CmdletBinding()]
    [OutputType([object])]
    param (
        [Parameter(Mandatory)]
        [string]
        $ProjectId,
        [Parameter(Mandatory)]
        [string]
        $RepositoryId
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $TokenType = $script:connection.TokenType
    $Organization = $script:connection.Organization
    # token is not FullAccess, write a warning and return null
    if ($TokenType -ne "FullAccess") {
        Write-Warning "The $TokenType token type does not have access to the Repositories API, returning null"
        return $null
    } else {
        $header = $script:connection.GetHeader()
        $payload = @{
            contributionIds = @(
                "ms.vss-features.my-organizations-data-provider"
                "ms.vss-advsec.advanced-security-enablement-data-provider"
            )
            dataProviderContext = @{
                properties = @{
                    givenProjectId = $ProjectId
                    givenRepoId = $RepositoryId
                }
            }
        }
        $url = "https://dev.azure.com/$Organization/_apis/Contribution/HierarchyQuery?api-version=5.0-preview.1"
        try {
            $response = Invoke-RestMethod -Uri $url -Method Post -Headers $header -Body ($payload | ConvertTo-Json) -ContentType "application/json"
            # If the response is a string and not an object, throw an exception for authentication failure or project not found
            if ($response -is [string]) {
                throw "Authentication failed or project not found"
            }
        }
        catch {
            throw $_.Exception.Message
        }
        return $response.dataProviders.'ms.vss-advsec.advanced-security-enablement-data-provider'
    }
}
Export-ModuleMember -Function Get-AzDevOpsRepositoryGhas
# End of Function Get-AzDevOpsRepositoryGhas

<#
    .SYNOPSIS
    Get and export all Azure DevOps repos in a project with default, main and master branches and branch policies and export to JSON with 1 file per repo

    .DESCRIPTION
    Get and export all Azure DevOps repos in a project with default, main and master branches and branch policies and export to JSON using Azure DevOps Rest API and this modules functions

    .PARAMETER Project
    Project name for Azure DevOps

    .PARAMETER OutputPath
    Output path for JSON file

    .PARAMETER PassThru
    Return the exported repos as objects to the pipeline instead of writing to a file

    .EXAMPLE
    Export-AzDevOpsReposAndBranchPolicies -Project $Project -OutputPath $OutputPath

    .NOTES
    This function returns an empty object if no branch policy is found for the branch
#>
function Export-AzDevOpsReposAndBranchPolicies {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [string]
        $Project,
        [Parameter(ParameterSetName = 'JsonFile')]
        [string]
        $OutputPath,
        [Parameter(ParameterSetName = 'PassThru')]
        [switch]
        $PassThru
    )
    if ($null -eq $script:connection) {
        throw "Not connected to Azure DevOps. Run Connect-AzDevOps first"
    }
    $Organization = $script:connection.Organization
    $TokenType = $script:connection.TokenType    
    $repos = Get-AzDevOpsRepos -Project $Project
    $repos | ForEach-Object {
        if ($null -ne $_) {
            $repo = $_
            # Add ObjectType Azure.DevOps.Repo to repo object
            $repo | Add-Member -MemberType NoteProperty -Name ObjectType -Value "Azure.DevOps.Repo"
            # Add ObjectName to repo object
            $repo | Add-Member -MemberType NoteProperty -Name ObjectName -Value ("{0}.{1}.{2}" -f $Organization,$Project,$repo.name)
            Write-Verbose "Getting branch policy for repo $($repo.name)"
            If($repo.defaultBranch) {
                $branchPolicy = Get-AzDevOpsBranchPolicy -Project $Project -Repository $repo.id -Branch $repo.defaultBranch
            }
            $repo | Add-Member -MemberType NoteProperty -Name MainBranchPolicy -Value $branchPolicy
            # Add a property indicating if a file named README.md or README exists in the repo
            $readmeExists = ((Test-AzDevOpsFileExists -Project $Project -Repository $repo.id -Path "README.md") -or (Test-AzDevOpsFileExists -Project $Project -Repository $repo.id -Path "README"))
            $repo | Add-Member -MemberType NoteProperty -Name ReadmeExists -Value $readmeExists

            # Get all branches for the repo
            $branches = @()
            $branches += Get-AzDevOpsBranches -Project $Project -Repository $repo.id
            # add branch policies for each branch to the branches object
            $branches = @($branches | ForEach-Object {
                $branch = $_
                $branchPolicy = @(Get-AzDevOpsBranchPolicy -Project $Project -Repository $repo.id -Branch $branch.name)
                $branch | Add-Member -MemberType NoteProperty -Name BranchPolicy -Value $branchPolicy
                $branch
            })
            # Add an ObjectType Azure.DevOps.Repo.Branch to each branch object
            $branches = @($branches | ForEach-Object {
                $branch = $_
                $branch | Add-Member -MemberType NoteProperty -Name ObjectType -Value "Azure.DevOps.Repo.Branch"
                # Add ObjectName to branch object
                $branch | Add-Member -MemberType NoteProperty -Name ObjectName -Value ("{0}.{1}.{2}.{3}" -f $Organization,$Project,$repo.name,$branch.name)
                $id = @{ 
                    originalId      = $branch.objectId;
                    resourceName    = "$($repo.name)/$($branch.name)"
                    project         = $Project;
                    organization    = $Organization
                } | ConvertTo-Json -Depth 100
                $branch | Add-Member -MemberType NoteProperty -Name id -Value $id
                $branch
            })



            # Add a property indicating if a file named LICENSE or LICENSE.md exists in the repo
            $licenseExists = ((Test-AzDevOpsFileExists -Project $Project -Repository $repo.id -Path "LICENSE") -or (Test-AzDevOpsFileExists -Project $Project -Repository $repo.id -Path "LICENSE.md"))
            $repo | Add-Member -MemberType NoteProperty -Name LicenseExists -Value $licenseExists

            # Add a property for GitHub Advanced Security (GHAS) data if the token type is FullAccess
            if ($TokenType -eq "FullAccess") {
                $ghas = Get-AzDevOpsRepositoryGhas -ProjectId $repo.project.id -RepositoryId $repo.id
                $repo | Add-Member -MemberType NoteProperty -Name Ghas -Value $ghas
            } else {
                Write-Warning "The $TokenType token type does not have access to the GHAS API, returning null"
            }
            
            # Add a property with pipeline permissions
            $pipelinePermissions = Get-AzDevOpsRepositoryPipelinePermissions -ProjectId $repo.project.id -RepositoryId $repo.id
            $repo | Add-Member -MemberType NoteProperty -Name PipelinePermissions -Value $pipelinePermissions
            $repoId = $repo.id
            # Set the id property to a hash table with the original id, organization and project name
            $repo.id = @{ 
                originalId      = $repo.id;
                resourceName    = $repo.name;
                project         = $Project;
                organization    = $Organization
            } | ConvertTo-Json -Depth 100
            # Add a property with repo ACLs if the token type is not ReadOnly
            if ($TokenType -ne "ReadOnly") {
                $repoAcls = Get-AzDevOpsRepositoryAcls -ProjectId $repo.project.id -RepositoryId $repoId
                $repo | Add-Member -MemberType NoteProperty -Name Acls -Value $repoAcls
            }
            $branches += $repo
            # If the PassThru switch is set, return the repo object
            if ($PassThru) {
                Write-Output $branches
            } else {
                # Export repo object to JSON file
                Write-Verbose "Exporting repo $($repo.name) and its branches to JSON as file $($repo.name).ado.repo.json"
                $branches | ConvertTo-Json -Depth 100 | Out-File -FilePath "$OutputPath\$($repo.name).ado.repo.json"
            }
        }
    }
}
Export-ModuleMember -Function Export-AzDevOpsReposAndBranchPolicies
# End of Function Export-AzDevOpsReposAndBranchPolicies