Add New-GitHubPullRequest command (#111)

Adds a command for creating new pull requests.

Resolves #30

Author: rjmholt

GitHubPullRequests.ps1

@@ -163,3 +163,229 @@ function Get-GitHubPullRequest
 
     return Invoke-GHRestMethodMultipleResult @params
 }
+
+function New-GitHubPullRequest
+{
+    <#
+    .SYNOPSIS
+        Create a new pull request in the specified repository.
+
+    .DESCRIPTION
+        Opens a new pull request from the given branch into the given branch in the specified 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 Title
+        The title of the pull request to be created.
+
+    .PARAMETER Body
+        The text description of the pull request.
+
+    .PARAMETER Issue
+        The GitHub issue number to open the pull request to address.
+
+    .PARAMETER Head
+        The name of the head branch (the branch containing the changes to be merged).
+
+        May also include the name of the owner fork, in the form "${fork}:${branch}".
+
+    .PARAMETER Base
+        The name of the target branch of the pull request
+        (where the changes in the head will be merged to).
+
+    .PARAMETER HeadOwner
+        The name of fork that the change is coming from.
+
+        Used as the prefix of $Head parameter in the form "${HeadOwner}:${Head}".
+
+        If unspecified, the unprefixed branch name is used,
+        creating a pull request from the $OwnerName fork of the repository.
+
+    .PARAMETER MaintainerCanModify
+        If set, allows repository maintainers to commit changes to the
+        head branch of this pull request.
+
+    .PARAMETER Draft
+        If set, opens the pull request as a draft.
+
+    .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] An object describing the created pull request.
+
+    .EXAMPLE
+        $prParams = @{
+            OwnerName = 'Microsoft'
+            Repository = 'PowerShellForGitHub'
+            Title = 'Add simple file to root'
+            Head = 'octocat:simple-file'
+            Base = 'master'
+            Body = "Adds a simple text file to the repository root.`n`nThis is an automated PR!"
+            MaintainerCanModify = $true
+        }
+        $pr = New-GitHubPullRequest @prParams
+
+    .EXAMPLE
+        New-GitHubPullRequest -Uri 'https://github.com/PowerShell/PSScriptAnalyzer' -Title 'Add test' -Head simple-test -HeadOwner octocat -Base development -Draft -MaintainerCanModify
+
+    .EXAMPLE
+        New-GitHubPullRequest -Uri 'https://github.com/PowerShell/PSScriptAnalyzer' -Issue 642 -Head simple-test -HeadOwner octocat -Base development -Draft
+    #>
+
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification="Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")]
+    [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName='Elements_Title')]
+    param(
+        [Parameter(ParameterSetName='Elements_Title')]
+        [Parameter(ParameterSetName='Elements_Issue')]
+        [string] $OwnerName,
+
+        [Parameter(ParameterSetName='Elements_Title')]
+        [Parameter(ParameterSetName='Elements_Issue')]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri_Title')]
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri_Issue')]
+        [string] $Uri,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Elements_Title')]
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri_Title')]
+        [ValidateNotNullOrEmpty()]
+        [string] $Title,
+
+        [Parameter(ParameterSetName='Elements_Title')]
+        [Parameter(ParameterSetName='Uri_Title')]
+        [string] $Body,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Elements_Issue')]
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri_Issue')]
+        [int] $Issue,
+
+        [Parameter(Mandatory)]
+        [string] $Head,
+
+        [Parameter(Mandatory)]
+        [string] $Base,
+
+        [string] $HeadOwner,
+
+        [switch] $MaintainerCanModify,
+
+        [switch] $Draft,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog
+
+    if (-not [string]::IsNullOrWhiteSpace($HeadOwner))
+    {
+        if ($Head.Contains(':'))
+        {
+            $message = "`$Head ('$Head') was specified with an owner prefix, but `$HeadOwner ('$HeadOwner') was also specified." +
+                " Either specify `$Head in '<owner>:<branch>' format, or set `$Head = '<branch>' and `$HeadOwner = '<owner>'."
+
+            Write-Log -Message $message -Level Error
+            throw $message
+        }
+
+        # $Head does not contain ':' - add the owner fork prefix
+        $Head = "${HeadOwner}:${Head}"
+    }
+
+    $elements = Resolve-RepositoryElements
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+    }
+
+    $uriFragment = "/repos/$OwnerName/$RepositoryName/pulls"
+
+    $postBody = @{
+        'head' = $Head
+        'base' = $Base
+    }
+
+    if ($PSBoundParameters.ContainsKey('Title'))
+    {
+        $description = "Creating pull request $Title in $RepositoryName"
+        $postBody['title'] = $Title
+
+        # Body may be whitespace, although this might not be useful
+        if ($Body)
+        {
+            $postBody['body'] = $Body
+        }
+    }
+    else
+    {
+        $description = "Creating pull request for issue $Issue in $RepositoryName"
+        $postBody['issue'] = $Issue
+    }
+
+    if ($MaintainerCanModify)
+    {
+        $postBody['maintainer_can_modify'] = $true
+    }
+
+    if ($Draft)
+    {
+        $postBody['draft'] = $true
+        $acceptHeader = 'application/vnd.github.shadow-cat-preview+json'
+    }
+
+    $restParams = @{
+        'UriFragment' = $uriFragment
+        'Method' = 'Post'
+        'Description' = $description
+        'Body' = ConvertTo-Json -InputObject $postBody -Compress
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    if ($acceptHeader)
+    {
+        $restParams['AcceptHeader'] = $acceptHeader
+    }
+
+    return Invoke-GHRestMethod @restParams
+}

PowerShellForGitHub.psd1

@@ -93,6 +93,7 @@
         'New-GitHubIssue',
         'New-GitHubLabel',
         'New-GitHubMilestone',
+        'New-GitHubPullRequest',
         'New-GitHubRepository',
         'New-GitHubRepositoryFork',
         'Remove-GithubAssignee',