Merge a branch of a repository

GitHubReferences.ps1

@@ -0,0 +1,219 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+function Get-GitHubReference
+{
+<#
+    .SYNOPSIS
+        Retrieve a reference of a given GitHub repository.
+
+    .DESCRIPTION
+        Retrieve a reference of a given GitHub repository.
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER Reference
+        Name of the reference, for example: "heads/<branch name>" for branches and "tags/<tag name>" for tags
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        Get-GitHubReference -OwnerName Powershell -RepositoryName PowerShellForGitHub -Reference heads/master
+#>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [Parameter(Mandatory)]
+        [string] $Reference,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters -DisableValidation
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    if ($OwnerName -xor $RepositoryName)
+    {
+        $message = 'You must specify both Owner Name and Repository Name.'
+        Write-Log -Message $message -Level Error
+        throw $message
+    }
+    $uriFragment = "/repos/$OwnerName/$RepositoryName/git/refs/$Reference"
+    $description =  "Getting Reference $Reference for $RepositoryName"
+
+    $params = @{
+        'UriFragment' = $uriFragment
+        'Method' = 'Get'
+        'Description' =  $description
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    try
+    {
+        return Invoke-GHRestMethod @params
+    }
+    catch
+    {
+        Write-InteractiveHost "No reference named $Reference exists in repository $RepositoryName" -NoNewline -f Red
+        Write-Log -Level Error "No reference named $Reference exists in repository $RepositoryName"
+        return $null
+    }
+
+}
+
+function New-GitHubReference
+{
+    <#
+    .SYNOPSIS
+        Create a reference in a given GitHub repository.
+
+    .DESCRIPTION
+        Create a reference in a given GitHub repository.
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER Reference
+        The name of the fully qualified reference to be created (eg: refs/heads/master)
+
+    .PARAMETER Sha
+        The SHA1 value for the reference to be created
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .EXAMPLE
+        -GitHubReference -OwnerName Powershell -RepositoryName PowerShellForGitHub -Reference refs/heads/master -Sha aa218f56b14c9653891f9e74264a383fa43fefbd
+    #>
+    [CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [Parameter(Mandatory)]
+        [string] $Reference,
+
+        [Parameter(Mandatory)]
+        [string] $Sha,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters -DisableValidation
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    if ($OwnerName -xor $RepositoryName)
+    {
+        $message = 'You must specify both Owner Name and Repository Name.'
+        Write-Log -Message $message -Level Error
+        throw $message
+    }
+
+    $uriFragment = "/repos/$OwnerName/$RepositoryName/git/refs"
+    $description =  "Creating Reference $Reference for $RepositoryName from SHA $Sha"
+
+    $hashBody = @{
+        'ref' = $Reference
+        'sha' = $Sha
+    }
+
+    $params = @{
+        'UriFragment' = $uriFragment
+        'Method' = 'Post'
+        'Body' = (ConvertTo-Json -InputObject $hashBody)
+        'Description' =  $description
+        'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethod @params
+}

GitHubRepositoryMerge.ps1

@@ -0,0 +1,131 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+function Merge-GitHubRepositoryBranch
+{
+<#
+    .SYNOPSIS
+        Merge the specified branch into another branch
+
+    .DESCRIPTION
+        Merge the specified branch into another branch
+
+        The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
+
+    .PARAMETER OwnerName
+        Owner of the repository.
+        If not supplied here, the DefaultOwnerName configuration property value will be used.
+
+    .PARAMETER RepositoryName
+        Name of the repository.
+        If not supplied here, the DefaultRepositoryName configuration property value will be used.
+
+    .PARAMETER Uri
+        Uri for the repository.
+        The OwnerName and RepositoryName will be extracted from here instead of needing to provide
+        them individually.
+
+    .PARAMETER State
+        The state of the pull requests that should be returned back.
+
+    .PARAMETER Base
+        The name of the base branch that the head will be merged into.
+
+    .PARAMETER Head
+        The head to merge. This can be a branch name or a commit SHA1.
+
+    .PARAMETER CommitMessage
+        Commit message to use for the merge commit. If omitted, a default message will be used.
+
+    .PARAMETER AccessToken
+        If provided, this will be used as the AccessToken for authentication with the
+        REST Api.  Otherwise, will attempt to use the configured value or will run unauthenticated.
+
+    .PARAMETER NoStatus
+        If this switch is specified, long-running commands will run on the main thread
+        with no commandline status update.  When not specified, those commands run in
+        the background, enabling the command prompt to provide status information.
+        If not supplied here, the DefaultNoStatus configuration property value will be used.
+
+    .OUTPUTS
+        PSCustomObject
+
+    .EXAMPLE
+        Merge-GitHubRepositoryBranch -OwnerName PowerShell -RepositoryName PowerShellForGitHub -Base 'master' -Head 'new_feature' -CommitMessage 'Merging branch new_feature into master'
+#>
+
+[CmdletBinding(
+        SupportsShouldProcess,
+        DefaultParametersetName='Elements')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    param(
+        [Parameter(ParameterSetName='Elements')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [string] $Uri,
+
+        [Parameter(Mandatory)]
+        [string] $Base,
+
+        [Parameter(Mandatory)]
+        [string] $Head,
+
+        [string] $CommitMessage,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog
+
+    $elements = Resolve-RepositoryElements -DisableValidation
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $hashBody = @{
+        'base'= $Base
+        'head' = $Head
+    }
+
+    if(-not $CommitMessage -eq $null)
+    {
+        $hashBody['commit_message'] = $CommitMessage
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/merges"
+        'Body' = (ConvertTo-Json -InputObject $hashBody)
+        'Method' = 'Post'
+        'Description' =  "Merging branch $Head to $Base in $RepositoryName"
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    try {
+        $result = Invoke-GHRestMethod @params -ExtendedResult
+        if ($result.statusCode -eq 204)
+        {
+            Write-Log -Message "Nothing to merge. The branch $Base already contains changes from $Head" -Level Warning
+        }
+        return $result.result
+    }
+    catch {
+        #TODO: Read the error message and find out the kind of issue
+        Write-Error $_.Exception
+        Write-Log -Message "Unable to merge. Either the branch $Base or branch $Head does not exist or there is a conflict" -Level Warning
+    }
+}

PowerShellForGitHub.psd1

@@ -32,8 +32,10 @@
         'GitHubMiscellaneous.ps1',
         'GitHubOrganizations.ps1',
         'GitHubPullRequests.ps1',
+        'GitHubReferences.ps1',
         'GitHubRepositories.ps1',
         'GitHubRepositoryForks.ps1',
+        'GitHubRepositoryMerge.ps1',
         'GitHubRepositoryTraffic.ps1',
         'GitHubTeams.ps1',
         'GitHubUsers.ps1',
@@ -85,6 +87,7 @@
         'Invoke-GHRestMethod',
         'Invoke-GHRestMethodMultipleResult',
         'Lock-GitHubIssue',
+        'Merge-GitHubRepositoryBranch',
         'Move-GitHubRepositoryOwnership',
         'New-GithubAssignee',
         'New-GitHubComment',
@@ -115,7 +118,9 @@
         'Update-GitHubCurrentUser',
         'Update-GitHubIssue',
         'Update-GitHubLabel',
-        'Update-GitHubRepository'
+        'Update-GitHubRepository',
+        'Get-GitHubReference',
+        'New-GithubReference'
     )
 
     AliasesToExport = @(