🩹 [Patch]: Update Connect-GitHubApp to support installation ID parameter (#525)

## Description

This pull request adds support for connecting to a GitHub App
installation using an explicit installation ID, improving flexibility
and usability in authentication scenarios. The main changes involve
updating the `Connect-GitHubApp` function to accept installation IDs
directly and adding corresponding tests to ensure the new functionality
works as expected.

**Enhancements to authentication logic:**

* Updated the `Connect-GitHubApp.ps1` function to accept an `-ID`
parameter, allowing users to connect directly to installations by their
ID. This replaces the previous pipeline-based `Installation` parameter
with a more flexible approach.
* Added logic to process the new `InstallationID` parameter set,
including verbose logging and warnings when an installation ID is not
found.

**Testing improvements:**

* Added a new test case in `Apps.Tests.ps1` to verify that
`Connect-GitHubApp` successfully connects using the `-ID` parameter for
a single installation, checking key properties of the returned context
object.
* Updated test setup to retrieve the installation object for use in the
new test scenario.

**General improvements:**

* Refactored code to ensure installations are only retrieved when
necessary, improving efficiency and clarity.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

src/functions/public/Auth/Connect-GitHubApp.ps1

@@ -59,9 +59,15 @@
         [string[]] $Enterprise,
 
         # Installation objects from pipeline for parallel processing.
-        [Parameter(Mandatory, ParameterSetName = 'Installation', ValueFromPipeline)]
+        [Parameter(Mandatory, ParameterSetName = 'Installation object', ValueFromPipeline)]
         [GitHubAppInstallation[]] $Installation,
 
+        # The installation ID(s) to connect to directly.
+        # Accepts input from the pipeline by property name (e.g. objects with an ID property)
+        [Parameter(Mandatory, ParameterSetName = 'Installation ID', ValueFromPipelineByPropertyName)]
+        [Alias('InstallationID')]
+        [int[]] $ID,
+
         # Passes the context object to the pipeline.
         [Parameter()]
         [switch] $PassThru,
@@ -89,36 +95,58 @@
     }
 
     process {
-        $installations = Get-GitHubAppInstallation -Context $Context
-        $selectedInstallations = @()
-        Write-Verbose "Found [$($installations.Count)] installations."
+        $selectedInstallations = [System.Collections.ArrayList]::new()
         switch ($PSCmdlet.ParameterSetName) {
             'Filtered' {
+                $installations = Get-GitHubAppInstallation -Context $Context
+                Write-Verbose "Found [$($installations.Count)] installations."
                 $User | ForEach-Object {
                     $userItem = $_
                     Write-Verbose "User filter:         [$userItem]."
-                    $selectedInstallations += $installations | Where-Object {
-                        $_.Type -eq 'User' -and $_.Target.Name -like $userItem
+                    $installations | Where-Object { $_.Type -eq 'User' -and $_.Target.Name -like $userItem } | ForEach-Object {
+                        $null = $selectedInstallations.Add($_)
                     }
                 }
                 $Organization | ForEach-Object {
                     $organizationItem = $_
                     Write-Verbose "Organization filter: [$organizationItem]."
-                    $selectedInstallations += $installations | Where-Object {
-                        $_.Type -eq 'Organization' -and $_.Target.Name -like $organizationItem
+                    $installations | Where-Object { $_.Type -eq 'Organization' -and $_.Target.Name -like $organizationItem } | ForEach-Object {
+                        $null = $selectedInstallations.Add($_)
                     }
                 }
                 $Enterprise | ForEach-Object {
                     $enterpriseItem = $_
                     Write-Verbose "Enterprise filter:   [$enterpriseItem]."
-                    $selectedInstallations += $installations | Where-Object {
-                        $_.Type -eq 'Enterprise' -and $_.Target.Name -like $enterpriseItem
+                    $installations | Where-Object { $_.Type -eq 'Enterprise' -and $_.Target.Name -like $enterpriseItem } | ForEach-Object {
+                        $null = $selectedInstallations.Add($_)
+                    }
+                }
+                break
+            }
+            'Installation ID' {
+                Write-Verbose 'Selecting installations by explicit ID.'
+                foreach ($installationId in $ID) {
+                    Write-Verbose "Looking up installation ID [$installationId]"
+                    $found = Get-GitHubAppInstallation -ID $installationId -Context $Context
+                    if (-not $found) {
+                        Write-Warning "No installation found for ID [$installationId]."
+                        continue
                     }
+                    $null = $selectedInstallations.Add($found)
+                }
+                break
+            }
+            'Installation object' {
+                Write-Verbose 'Selecting installations from the pipeline.'
+                foreach ($installationObject in $Installation) {
+                    $null = $selectedInstallations.Add($installationObject)
                 }
+                break
             }
             default {
                 Write-Verbose 'No target specified. Connecting to all installations.'
-                $selectedInstallations = $installations
+                $selectedInstallations.AddRange((Get-GitHubAppInstallation -Context $Context))
+                Write-Verbose "Found [$($selectedInstallations.Count)] installations."
             }
         }