Add support for issue labels

GitHubLabels.ps1

@@ -29,6 +29,12 @@ function Get-GitHubLabel
         Name of the specific label to be retieved.  If not supplied, all labels will be retrieved.
         Emoji and codes are supported.  For more information, see here: https://www.webpagefx.com/tools/emoji-cheat-sheet/
 
+    .PARAMETER Issue
+        If provided, will return all of the labels for this particular issue.
+
+    .PARAMETER Milestone
+        If provided, will return all of the labels for this particular milestone.
+
     .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.
@@ -55,20 +61,37 @@ function Get-GitHubLabel
         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(Mandatory,ParameterSetName='Elements')]
+        [Parameter(Mandatory,ParameterSetName='NameElements')]
+        [Parameter(Mandatory,ParameterSetName='IssueElements')]
+        [Parameter(Mandatory, ParameterSetName='MilestoneElements')]
         [string] $OwnerName,
 
-        [Parameter(ParameterSetName='Elements')]
+        [Parameter(Mandatory, ParameterSetName='Elements')]
+        [Parameter(Mandatory, ParameterSetName='NameElements')]
+        [Parameter(Mandatory, ParameterSetName='IssueElements')]
+        [Parameter(Mandatory, ParameterSetName='MilestoneElements')]
         [string] $RepositoryName,
 
-        [Parameter(
-            Mandatory,
-            ParameterSetName='Uri')]
+        [Parameter(Mandatory, ParameterSetName='Uri')]
+        [Parameter(Mandatory, ParameterSetName='NameUri')]
+        [Parameter(Mandatory, ParameterSetName='IssueUri')]
+        [Parameter(Mandatory, ParameterSetName='MilestoneUri')]
         [string] $Uri,
 
+        [Parameter(Mandatory, ParameterSetName='NameUri')]
+        [Parameter(Mandatory, ParameterSetName='NameElements')]
         [Alias('LabelName')]
         [string] $Name,
 
+        [Parameter(Mandatory, ParameterSetName='IssueUri')]
+        [Parameter(Mandatory, ParameterSetName='IssueElements')]
+        [int] $Issue,
+
+        [Parameter(Mandatory, ParameterSetName='MilestoneUri')]
+        [Parameter(Mandatory, ParameterSetName='MilestoneElements')]
+        [int] $Milestone,
+
         [string] $AccessToken,
 
         [switch] $NoStatus
@@ -85,9 +108,33 @@ function Get-GitHubLabel
         'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
     }
 
+    if ($PSBoundParameters.ContainsKey('Issue'))
+    {
+        $uriFragment = "/repos/$OwnerName/$RepositoryName/issues/$Issue/labels"
+        $description = "Getting labels for Issue $Issue in $RepositoryName"
+    }
+    elseif ($PSBoundParameters.ContainsKey('Milestone'))
+    {
+        $uriFragment = "/repos/$OwnerName/$RepositoryName/milestones/$Milestone/labels"
+        $description = "Getting labels for Milestone $Milestone in $RepositoryName"
+    }
+    else
+    {
+        $uriFragment = "repos/$OwnerName/$RepositoryName/labels/$Name"
+
+        if ($PSBoundParameters.ContainsKey('Name'))
+        {
+            $description =  "Getting label $Name for $RepositoryName"
+        }
+        else
+        {
+            $description = "Getting labels for $RepositoryName"
+        }
+    }
+
     $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/labels/$Name"
-        'Description' =  "Getting all labels for $RepositoryName"
+        'UriFragment' = $uriFragment
+        'Description' =  $description
         'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
         'AccessToken' = $AccessToken
         'TelemetryEventName' = $MyInvocation.MyCommand.Name
@@ -251,6 +298,9 @@ function Remove-GitHubLabel
         Name of the label to be deleted.
         Emoji and codes are supported.  For more information, see here: https://www.webpagefx.com/tools/emoji-cheat-sheet/
 
+    .PARAMETER Issue
+        Issue number to delete the label from. If not provided the label will be deleted from the entire repository.
+
     .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.
@@ -287,6 +337,8 @@ function Remove-GitHubLabel
         [Alias('LabelName')]
         [string] $Name,
 
+        [int] $Issue,
+
         [string] $AccessToken,
 
         [switch] $NoStatus
@@ -303,10 +355,21 @@ function Remove-GitHubLabel
         'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
     }
 
+    if ($PSBoundParameters.ContainsKey('Issue'))
+    {
+        $uriFragment = "/repos/$OwnerName/$RepositoryName/issues/$Issue/labels/$Name"
+        $description = "Deleting label $Name from issue $Issue in $RepositoryName"
+    }
+    else
+    {
+        $uriFragment = "repos/$OwnerName/$RepositoryName/labels/$Name"
+        $description = "Deleting label $Name from $RepositoryName"
+    }
+
     $params = @{
-        'UriFragment' = "repos/$OwnerName/$RepositoryName/labels/$Name"
+        'UriFragment' = $uriFragment
         'Method' = 'Delete'
-        'Description' =  "Deleting label $Name from $RepositoryName"
+        'Description' =  $description
         'AcceptHeader' = 'application/vnd.github.symmetra-preview+json'
         'AccessToken' = $AccessToken
         'TelemetryEventName' = $MyInvocation.MyCommand.Name
@@ -565,6 +628,121 @@ function Set-GitHubLabel
     }
 }
 
+function Add-GitHubLabel
+{
+<#
+    .DESCRIPTION
+        Adds a label to an issue in the 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 Issue
+        Issue number to add the label to.
+
+    .PARAMETER LabelName
+        Array of label names to add to the issue
+
+    .PARAMETER Replace
+        If supplied, will replace all of the labels on the issue with the provided labels.
+
+    .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
+        Add-GitHubLabel -OwnerName PowerShell -RepositoryName PowerShellForGitHub -Issue 1 -LabelName $labels
+
+        Adds labels to an issue in the PowerShellForGitHub project.
+#>
+    [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)]
+        [int] $Issue,
+
+        [Parameter(Mandatory)]
+        [string[]] $LabelName,
+
+        [switch] $Replace,
+
+        [string] $AccessToken,
+
+        [switch] $NoStatus
+    )
+
+    Write-InvocationLog
+
+    $elements = Resolve-RepositoryElements
+    $OwnerName = $elements.ownerName
+    $RepositoryName = $elements.repositoryName
+
+    $telemetryProperties = @{
+        'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
+        'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
+        'labelCount' = $LabelName.Count
+    }
+
+    $hashBody = @{
+        'labels' = $LabelName
+    }
+
+    if ($Replace)
+    {
+        $method = 'Put'
+    }
+    else
+    {
+        $method = 'Post'
+    }
+
+    $params = @{
+        'UriFragment' = "repos/$OwnerName/$RepositoryName/issues/$Issue/labels"
+        'Body' = (ConvertTo-Json -InputObject $hashBody)
+        'Method' = $method
+        'Description' =  "Adding label $Name to issue $Issue in $RepositoryName"
+        '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
+}
+
+
 # A set of labels that a project might want to initially populate their repository with
 # Used by Set-GitHubLabel when no Label list is provided by the user.
 # This list exists to support v0.1.0 users.

PowerShellForGitHub.psd1

@@ -42,6 +42,7 @@
 
     # Functions to export from this module
     FunctionsToExport = @(
+        'Add-GitHubLabel',
         'Backup-GitHubConfiguration',
         'Clear-GitHubAuthentication',
         'ConvertFrom-Markdown',

Tests/GitHubLabels.tests.ps1

@@ -271,6 +271,61 @@ if ($script:accessTokenConfigured)
 
         $null = Remove-GitHubRepository -OwnerName $script:ownerName -RepositoryName $repositoryName
     }
+
+    Describe 'Adding and removing labels to an issue'{
+        $repositoryName = [Guid]::NewGuid().Guid
+        $null = New-GitHubRepository -RepositoryName $repositoryName
+        Set-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Label $script:defaultLabels
+
+        $issueName = [Guid]::NewGuid().Guid
+        $issue = New-GitHubIssue -OwnerName $script:ownerName -RepositoryName $repositoryName -Title $issueName
+
+        Context 'Adding labels to an issue' {
+            $labelsToAdd = @('pri:lowest', 'pri:low', 'pri:medium', 'pri:high', 'pri:highest', 'bug', 'duplicate',
+                'enhancement', 'up for grabs', 'question', 'discussion', 'wontfix', 'in progress', 'ready')
+            $addedLabels = @(Add-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue $issue.number -LabelName $labelsToAdd)
+
+            It 'Should return the expected number of labels' {
+                $addedLabels.Count | Should be $script:defaultLabels.Count
+            }
+
+            $labelIssues = Get-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue $issue.number
+
+            It 'Should have added the expected number of labels' {
+                $labelIssues.Count | Should be $script:defaultLabels.Count
+            }
+        }
+
+        Context 'Removing labels from an issue' {
+            Remove-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Name "discussion" -Issue $issue.number
+            Remove-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Name "question" -Issue $issue.number
+            Remove-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Name "bug" -Issue $issue.number
+            $labelIssues = Get-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue $issue.number
+
+            It 'Should have added the expected number of labels' {
+                $labelIssues.Count | Should be ($script:defaultLabels.Count - 3)
+            }
+        }
+
+        Context 'Replacing labels on an issue' {
+            $labelsToAdd = @('pri:lowest', 'pri:low', 'pri:medium', 'pri:high', 'pri:highest', 'bug', 'duplicate',
+            'enhancement', 'up for grabs', 'question', 'discussion', 'wontfix', 'in progress', 'ready')
+
+            $addedLabels = @(Add-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue $issue.number -LabelName $labelsToAdd -Replace)
+
+            It 'Should return the expected number of labels' {
+                $addedLabels.Count | Should be $script:defaultLabels.Count
+            }
+
+            $labelIssues = Get-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue $issue.number
+
+            It 'Should have added the expected number of labels' {
+                $labelIssues.Count | Should be $script:defaultLabels.Count
+            }
+        }
+
+        $null = Remove-GitHubRepository -OwnerName $script:ownerName -RepositoryName $repositoryName
+    }
 }
 
 # Restore the user's configuration to its pre-test state

USAGE.md

@@ -13,8 +13,12 @@
         *   [Quering Team and Organization Membership](#querying-team-and-organization-membership)
     *   [Labels](#labels)
         *   [Getting Labels for a Repository](#getting-labels-for-a-repository)
+        *   [Getting Labels for an issue](#getting-labels-for-an-issue)
+        *   [Getting Labels for a milestone](#getting-labels-for-a-milestone)
         *   [Adding a New Label to a Repository](#adding-a-new-label-to-a-repository)
         *   [Removing a Label From a Repository](#removing-a-label-from-a-repository)
+        *   [Adding Labels to an Issue](#adding-labels-to-an-issue)
+        *   [Removing a Label From an Issue](#removing-a-label-from-an-issue)
         *   [Updating a Label With a New Name and Color](#updating-a-label-with-a-new-name-and-color)
         *   [Bulk Updating Labels in a Repository](#bulk-updating-labels-in-a-repository)
     *   [Users](#users)
@@ -270,6 +274,16 @@ $teamMembers = Get-GitHubTeamMembers -OrganizationName 'OrganizationName' -TeamN
 $labels = Get-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration
 ```
 
+#### Getting Labels for an Issue
+```powershell
+$labels = Get-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration -Issue 1
+```
+
+#### Getting Labels for a Milestone
+```powershell
+$labels = Get-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration -Milestone 1
+```
+
 #### Adding a New Label to a Repository
 ```powershell
 New-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration -Name TestLabel -Color BBBBBB
@@ -280,6 +294,17 @@ New-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration
 Remove-GitHubLabel -OwnerName Powershell -RepositoryName desiredstateconfiguration -Name TestLabel
 ```
 
+#### Adding Labels to an Issue
+```powershell
+$labelNames = @{'bug', 'discussion')
+Add-GitHubLabel -OwnerName $script:ownerName -RepositoryName $repositoryName -Issue 1 -LabelName $labelNames
+```
+
+#### Removing a Label From an Issue
+```powershell
+Remove-GitHubLabel -OwnerName Powershell -RepositoryName desiredstateconfiguration -Name TestLabel -Issue 1
+```
+
 #### Updating a Label With a New Name and Color
 ```powershell
 Update-GitHubLabel -OwnerName Powershell -RepositoryName DesiredStateConfiguration -Name TestLabel -NewName NewTestLabel -Color BBBB00