Adding Get-GitHubRelease (#125)

Similar to #110, I needed some functionality around releases. I didn't so much need functionality to publish a release, but I needed to retrieve the list of releases that we're published. So, this is just a function for Get-GitHubRelease.

GitHubReleases.ps1

@@ -0,0 +1,200 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+function Get-GitHubRelease
+{
+<#
+    .SYNOPSIS
+        Retrieves information about a release or list of releases on GitHub.
+
+    .DESCRIPTION
+        Retrieves information about a release or list of releases on GitHub.
+
+        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 ReleaseId
+        Specific releaseId of a release.
+        This is an optional parameter which can limit the results to a single release.
+
+    .PARAMETER Latest
+        Retrieve only the latest release.
+        This is an optional parameter which can limit the results to a single release.
+
+    .PARAMETER Tag
+        Retrieves a list of releases with the associated tag.
+        This is an optional parameter which can filter the list of releases.
+
+    .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-GitHubRelease
+
+        Gets all releases for the default configured owner/repository.
+
+    .EXAMPLE
+        Get-GitHubRelease -ReleaseId 12345
+
+        Get a specific release for the default configured owner/repository
+
+    .EXAMPLE
+        Get-GitHubRelease -OwnerName dotnet -RepositoryName core
+
+        Gets all releases from the dotnet\core repository.
+
+    .EXAMPLE
+        Get-GitHubRelease -Uri https://github.com/microsoft/PowerShellForGitHub
+
+        Gets all releases from the microsoft/PowerShellForGitHub repository.
+
+    .EXAMPLE
+        Get-GitHubRelease -OwnerName dotnet -RepositoryName core -Latest
+
+        Gets the latest release from the dotnet\core repository.
+
+    .EXAMPLE
+        Get-GitHubRelease -Uri https://github.com/microsoft/PowerShellForGitHub -Tag 0.8.0
+
+        Gets the release tagged with 0.8.0 from the microsoft/PowerShellForGitHub repository.
+
+    .NOTES
+        Information about published releases are available to everyone. Only users with push
+        access will receive listings for draft releases.
+#>
+    [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')]
+        [Parameter(
+            ParameterSetName="Elements-ReleaseId")]
+        [Parameter(
+            ParameterSetName="Elements-Latest")]
+        [Parameter(
+            ParameterSetName="Elements-Tag")]
+        [string] $OwnerName,
+
+        [Parameter(
+            ParameterSetName='Elements')]
+        [Parameter(
+            ParameterSetName="Elements-ReleaseId")]
+        [Parameter(
+            ParameterSetName="Elements-Latest")]
+        [Parameter(
+            ParameterSetName="Elements-Tag")]
+        [string] $RepositoryName,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName='Uri')]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-ReleaseId")]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-Latest")]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-Tag")]
+        [string] $Uri,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Elements-ReleaseId")]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-ReleaseId")]
+        [string] $ReleaseId,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Elements-Latest")]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-Latest")]
+        [switch] $Latest,
+
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Elements-Tag")]
+        [Parameter(
+            Mandatory,
+            ParameterSetName="Uri-Tag")]
+        [string] $Tag,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog -Invocation $MyInvocation
+
+    $elements = Resolve-RepositoryElements -BoundParameters $PSBoundParameters -DisableValidation
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{}
+
+    $telemetryProperties['OwnerName'] = Get-PiiSafeString -PlainText $OwnerName
+    $telemetryProperties['RepositoryName'] = Get-PiiSafeString -PlainText $RepositoryName
+
+    $uriFragment = "repos/$OwnerName/$RepositoryName/releases"
+    $description = "Getting releases for $OwnerName/$RepositoryName"
+
+    if(-not [String]::IsNullOrEmpty($ReleaseId))
+    {
+        $telemetryProperties['ProvidedReleaseId'] = $true
+
+        $uriFragment += "/$ReleaseId"
+        $description = "Getting release information for $ReleaseId from $OwnerName/$RepositoryName"
+    }
+
+    if($Latest)
+    {
+        $telemetryProperties['GetLatest'] = $true
+
+        $uriFragment += "/latest"
+        $description = "Getting latest release from $OwnerName/$RepositoryName"
+    }
+
+    if(-not [String]::IsNullOrEmpty($Tag))
+    {
+        $telemetryProperties['ProvidedTag'] = $true
+
+        $uriFragment += "/tags/$Tag"
+        $description = "Getting releases tagged with $Tag from $OwnerName/$RepositoryName"
+    }
+
+    $params = @{
+        'UriFragment' = $uriFragment
+        'Description' =  $description
+        'AccessToken' = $AccessToken
+        'TelemetryEventName' = $MyInvocation.MyCommand.Name
+        'TelemetryProperties' = $telemetryProperties
+        'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -BoundParameters $PSBoundParameters -Name NoStatus -ConfigValueName DefaultNoStatus)
+    }
+
+    return Invoke-GHRestMethodMultipleResult @params
+}

PowerShellForGitHub.psd1

@@ -32,6 +32,7 @@
         'GitHubMiscellaneous.ps1',
         'GitHubOrganizations.ps1',
         'GitHubPullRequests.ps1',
+        'GitHubReleases.ps1',
         'GitHubRepositories.ps1',
         'GitHubRepositoryForks.ps1',
         'GitHubRepositoryTraffic.ps1',
@@ -67,6 +68,7 @@
         'Get-GitHubPullRequest',
         'Get-GitHubRateLimit',
         'Get-GitHubReferrerTraffic',
+        'Get-GitHubRelease',
         'Get-GitHubRepository',
         'Get-GitHubRepositoryBranch',
         'Get-GitHubRepositoryCollaborator',

Tests/GitHubReleases.tests.ps1

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+<#
+.Synopsis
+   Tests for GitHubReleases.ps1 module
+#>
+
+# This is common test code setup logic for all Pester test files
+$moduleRootPath = Split-Path -Path $PSScriptRoot -Parent
+. (Join-Path -Path $moduleRootPath -ChildPath 'Tests\Common.ps1')
+
+try
+{
+    if ($accessTokenConfigured)
+    {
+        Describe 'Getting releases from repository' {
+            $ownerName = "dotnet"
+            $repositoryName = "core"
+            $releases = Get-GitHubRelease -OwnerName $ownerName -RepositoryName $repositoryName
+
+            Context 'When getting all releases' {
+                It 'Should return multiple releases' {
+                    $releases.Count | Should BeGreaterThan 1
+                }
+            }
+
+            Context 'When getting the latest releases' {
+                $latest = Get-GitHubRelease -OwnerName $ownerName -RepositoryName $repositoryName -Latest
+
+                It 'Should return one value' {
+                    @($latest).Count | Should Be 1
+                }
+
+                It 'Should return the first release from the full releases list' {
+                    $releases[0].url | Should Be $releases[0].url
+                    $releases[0].name | Should Be $releases[0].name
+                }
+            }
+
+            Context 'When getting a specific release' {
+                $specificIndex = 5
+                $specific = Get-GitHubRelease -OwnerName $ownerName -RepositoryName $repositoryName -ReleaseId $releases[$specificIndex].id
+
+                It 'Should return one value' {
+                    @($specific).Count | Should Be 1
+                }
+
+                It 'Should return the correct release' {
+                    $specific.name | Should Be $releases[$specificIndex].name
+                }
+            }
+
+            Context 'When getting a tagged release' {
+                $taggedIndex = 8
+                $tagged = Get-GitHubRelease -OwnerName $ownerName -RepositoryName $repositoryName -Tag $releases[$taggedIndex].tag_name
+
+                It 'Should return one value' {
+                    @($tagged).Count | Should Be 1
+                }
+
+                It 'Should return the correct release' {
+                    $tagged.name | Should Be $releases[$taggedIndex].name
+                }
+            }
+        }
+
+        Describe 'Getting releases from default owner/repository' {
+            $originalOwnerName = Get-GitHubConfiguration -Name DefaultOwnerName
+            $originalRepositoryName = Get-GitHubConfiguration -Name DefaultRepositoryName
+
+            try {
+                Set-GitHubConfiguration -DefaultOwnerName "dotnet"
+                Set-GitHubConfiguration -DefaultRepositoryName "core"
+                $releases = Get-GitHubRelease
+
+                Context 'When getting all releases' {
+                    It 'Should return multiple releases' {
+                        $releases.Count | Should BeGreaterThan 1
+                    }
+                }
+            } finally {
+                Set-GitHubConfiguration -DefaultOwnerName $originalOwnerName
+                Set-GitHubConfiguration -DefaultRepositoryName $originalRepositoryName
+            }
+        }
+    }
+}
+finally
+{
+    if (Test-Path -Path $script:originalConfigFile -PathType Leaf)
+    {
+        # Restore the user's configuration to its pre-test state
+        Restore-GitHubConfiguration -Path $script:originalConfigFile
+        $script:originalConfigFile = $null
+    }
+}