🚀 [Feature]: Introduce GitHubEnvironment Class and Improve Handling of Special Characters in Environment Names (#326)

MariusStorhaug · github-actions[bot] · web-flow · commit 02c0de498f44 · 2025-03-19T22:01:51.000+01:00
## Description This pull request introduces a new `GitHubEnvironment` class and updates several functions to use this class for better type safety and consistency. Additionally, it includes enhancements to handle environment names with special characters and updates to the test cases to cover these changes. ### Introduction of `GitHubEnvironment` class: * Added a new `GitHubEnvironment` class with properties such as `Name`, `Repository`, `Owner`, `DatabaseID`, `NodeID`, `Url`, `CreatedAt`, `UpdatedAt`, `CanAdminsBypass`, `ProtectionRules`, and `DeploymentBranchPolicy`. This class includes constructors for initialization from a hashtable or a PSCustomObject. ### Updates to functions: * Updated `Get-GitHubEnvironmentByName`, `Get-GitHubEnvironmentList`, and `Set-GitHubEnvironment` functions to use the new `GitHubEnvironment` class instead of `PSCustomObject` for output type. [[1]](diffhunk://#diff-281ec1cdd72ba78fe2f547115ac26085efe035f4c30b748e579a7b71c3de9882L37-R45) [[2]](diffhunk://#diff-b7e6a0698de85126a8c0bf19e78924ae225511ad39ea20b05b2fcf6d262e82efL34-R42) [[3]](diffhunk://#diff-0d4fc874a278df0f48aba7cc73b05f002c068d4006e2acb0bdd24ab3eb6574e2L46-R58) * Modified `Get-GitHubEnvironmentByName`, `Get-GitHubEnvironmentList`, `Set-GitHubEnvironment`, and `Remove-GitHubEnvironment` functions to handle environment names with special characters using URL encoding. [[1]](diffhunk://#diff-281ec1cdd72ba78fe2f547115ac26085efe035f4c30b748e579a7b71c3de9882R83-R105) [[2]](diffhunk://#diff-b7e6a0698de85126a8c0bf19e78924ae225511ad39ea20b05b2fcf6d262e82efL90-R104) [[3]](diffhunk://#diff-0d4fc874a278df0f48aba7cc73b05f002c068d4006e2acb0bdd24ab3eb6574e2R218-R242) [[4]](diffhunk://#diff-7318eee8b888e260d6170db2abcae8cba8146173a0a7036f2756777ebc9fd5e8R60-R63) ### Enhancements to `Get-GitHubEnvironment`: * Simplified the `Get-GitHubEnvironment` function by removing the parameter set logic and using wildcard support for the `Name` parameter, allowing for more flexible environment name matching. [[1]](diffhunk://#diff-4ce9e4defaf029427d3215c1a0688b6bf11a705532e17295851e80b2e8948b0fL66-R66) [[2]](diffhunk://#diff-4ce9e4defaf029427d3215c1a0688b6bf11a705532e17295851e80b2e8948b0fL84-R89) [[3]](diffhunk://#diff-4ce9e4defaf029427d3215c1a0688b6bf11a705532e17295851e80b2e8948b0fL110-R108) ### Test case updates: * Added test cases to cover scenarios where environment names contain slashes and other special characters, ensuring that these names are correctly handled by the `Set-GitHubEnvironment` and `Remove-GitHubEnvironment` functions. [[1]](diffhunk://#diff-ca54665720a68eba32ad311ca6499070fd8435bd09671198175cf2f7e1d76073L46-R61) [[2]](diffhunk://#diff-ca54665720a68eba32ad311ca6499070fd8435bd09671198175cf2f7e1d76073L98-R126) [[3]](diffhunk://#diff-ca54665720a68eba32ad311ca6499070fd8435bd09671198175cf2f7e1d76073L155-R197) [[4]](diffhunk://#diff-ca54665720a68eba32ad311ca6499070fd8435bd09671198175cf2f7e1d76073L208-R264) These changes improve the robustness and flexibility of the environment management functions and ensure that they handle special cases more gracefully. ## Type of change  - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [ ] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [x] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist  - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas --------- Co-authored-by: github-actions <41898282+github-actions@users.noreply.github.com>
diff --git a/src/classes/public/Environment/GitHubEnvironment.ps1 b/src/classes/public/Environment/GitHubEnvironment.ps1
@@ -0,0 +1,51 @@
+﻿class GitHubEnvironment {
+    # The name of the environment.
+    [string] $Name
+
+    # The repository where the environment is.
+    [string] $Repository
+
+    # The owner of the environment.
+    [string] $Owner
+
+    # The ID of the environment.
+    [UInt64] $DatabaseID
+
+    # The Node ID of the environment.
+    [string] $NodeID
+
+    # URL of the environment.
+    [string] $Url
+
+    # The date and time the environment was created.
+    [datetime] $CreatedAt
+
+    # The date and time the environment was last updated.
+    [datetime] $UpdatedAt
+
+    # Whether admins can bypass protection rules.
+    [bool] $CanAdminsBypass
+
+    # Protection rules associated with the environment.
+    [object[]] $ProtectionRules
+
+    # Deployment branch policy details.
+    [object] $DeploymentBranchPolicy
+
+    # Simple parameterless constructor
+    GitHubEnvironment() {}
+
+    # Constructor that initializes the class from a hashtable
+    GitHubEnvironment([hashtable]$Properties) {
+        foreach ($Property in $Properties.Keys) {
+            $this.$Property = $Properties.$Property
+        }
+    }
+
+    # Constructor that initializes the class from a PSCustomObject
+    GitHubEnvironment([PSCustomObject]$Object) {
+        $Object.PSObject.Properties | ForEach-Object {
+            $this.($_.Name) = $_.Value
+        }
+    }
+}
diff --git a/src/functions/private/Environments/Get-GitHubEnvironmentByName.ps1 b/src/functions/private/Environments/Get-GitHubEnvironmentByName.ps1
@@ -34,15 +34,15 @@ filter Get-GitHubEnvironmentByName {
         Retrieves details of the "test" environment in the specified repository.
 
         .OUTPUTS
-        PSCustomObject
+        GitHubEnvironment
 
         .NOTES
         Contains environment details, including name, URL, and protection settings.
 
         .LINK
         https://psmodule.io/GitHub/Functions/Get-GitHubEnvironmentByName/
     #>
-    [OutputType([pscustomobject])]
+    [OutputType([GitHubEnvironment])]
     [CmdletBinding()]
     param(
         # The account owner of the repository. The name is not case sensitive.
@@ -80,14 +80,29 @@ filter Get-GitHubEnvironmentByName {
     }
 
     process {
+        $encodedName = [System.Uri]::EscapeDataString($Name)
         $inputObject = @{
-            Method      = 'GET'
-            APIEndpoint = "/repos/$Owner/$Repository/environments/$Name"
-            Context     = $Context
+            Method  = 'GET'
+            Uri     = $Context.ApiBaseUri + "/repos/$Owner/$Repository/environments/$encodedName"
+            Context = $Context
         }
 
         Invoke-GitHubAPI @inputObject | ForEach-Object {
-            Write-Output $_.Response
+            Write-Output $_.Response | ForEach-Object {
+                [GitHubEnvironment]@{
+                    Name                   = $_.name
+                    DatabaseID             = $_.id
+                    NodeID                 = $_.node_id
+                    Url                    = $_.html_url
+                    Owner                  = $Owner
+                    Repository             = $Repository
+                    CreatedAt              = $_.created_at
+                    UpdatedAt              = $_.updated_at
+                    CanAdminsBypass        = $_.can_admins_bypass
+                    ProtectionRules        = $_.protection_rules
+                    DeploymentBranchPolicy = $_.deployment_branch_policy
+                }
+            }
         }
     }
 
diff --git a/src/functions/private/Environments/Get-GitHubEnvironmentList.ps1 b/src/functions/private/Environments/Get-GitHubEnvironmentList.ps1
@@ -31,15 +31,15 @@ filter Get-GitHubEnvironmentList {
         Lists all environments available in the "EnvironmentTest" repository owned by "PSModule".
 
         .OUTPUTS
-        PSCustomObject
+        GitHubEnvironment
 
         .NOTES
         Contains details of each environment in the repository, including its name and protection settings.
 
         .LINK
         [List environments](https://docs.github.com/rest/deployments/environments#list-environments)
     #>
-    [OutputType([pscustomobject])]
+    [OutputType([GitHubEnvironment])]
     [CmdletBinding()]
     param(
         # The account owner of the repository. The name is not case sensitive.
@@ -87,7 +87,21 @@ filter Get-GitHubEnvironmentList {
         }
 
         Invoke-GitHubAPI @inputObject | ForEach-Object {
-            Write-Output $_.Response.environments
+            Write-Output $_.Response.environments | ForEach-Object {
+                [GitHubEnvironment]@{
+                    Name                   = $_.name
+                    Repository             = $Repository
+                    Owner                  = $Owner
+                    DatabaseID             = $_.id
+                    NodeID                 = $_.node_id
+                    Url                    = $_.html_url
+                    CreatedAt              = $_.created_at
+                    UpdatedAt              = $_.updated_at
+                    CanAdminsBypass        = $_.can_admins_bypass
+                    ProtectionRules        = $_.protection_rules
+                    DeploymentBranchPolicy = $_.deployment_branch_policy
+                }
+            }
         }
     }
 
diff --git a/src/functions/public/Environments/Get-GitHubEnvironment.ps1 b/src/functions/public/Environments/Get-GitHubEnvironment.ps1
@@ -63,7 +63,7 @@ filter Get-GitHubEnvironment {
         https://psmodule.io/GitHub/Functions/Environments/Get-GitHubEnvironment/
     #>
     [OutputType([pscustomobject])]
-    [CmdletBinding(DefaultParameterSetName = 'List')]
+    [CmdletBinding()]
     param(
         # The name of the organization.
         [Parameter(
@@ -81,15 +81,12 @@ filter Get-GitHubEnvironment {
         [string] $Repository,
 
         # The name of the environment.
-        [Parameter(
-            Mandatory,
-            ParameterSetName = 'ByName',
-            ValueFromPipelineByPropertyName
-        )]
-        [string] $Name,
+        [Parameter(ValueFromPipelineByPropertyName)]
+        [SupportsWildcards()]
+        [string] $Name = '*',
 
         # The maximum number of environments to return per request.
-        [Parameter(ParameterSetName = 'List')]
+        [Parameter()]
         [ValidateRange(0, 100)]
         [int] $PerPage,
 
@@ -107,14 +104,8 @@ filter Get-GitHubEnvironment {
     }
 
     process {
-        switch ($PSCmdlet.ParameterSetName) {
-            'ByName' {
-                Get-GitHubEnvironmentByName -Owner $Owner -Repository $Repository -Name $Name -Context $Context
-            }
-            'List' {
-                Get-GitHubEnvironmentList -Owner $Owner -Repository $Repository -PerPage $PerPage -Context $Context
-            }
-        }
+        Get-GitHubEnvironmentList -Owner $Owner -Repository $Repository -PerPage $PerPage -Context $Context |
+            Where-Object { $_.Name -like $Name }
     }
 
     end {
diff --git a/src/functions/public/Environments/Remove-GitHubEnvironment.ps1 b/src/functions/public/Environments/Remove-GitHubEnvironment.ps1
@@ -57,10 +57,11 @@ filter Remove-GitHubEnvironment {
     }
 
     process {
+        $encodedName = [System.Uri]::EscapeDataString($Name)
         $inputObject = @{
-            Method      = 'DELETE'
-            APIEndpoint = "/repos/$Owner/$Repository/environments/$Name"
-            Context     = $Context
+            Method  = 'DELETE'
+            Uri     = $Context.ApiBaseUri + "/repos/$Owner/$Repository/environments/$encodedName"
+            Context = $Context
         }
 
         if ($PSCmdlet.ShouldProcess("Environment [$Owner/$Repository/$Name]", 'Delete')) {
diff --git a/src/functions/public/Environments/Set-GitHubEnvironment.ps1 b/src/functions/public/Environments/Set-GitHubEnvironment.ps1
@@ -22,6 +22,7 @@ filter Set-GitHubEnvironment {
             WaitTimer              = 30
             Reviewers              = @{ type = $user.Type; id = $user.id }, @{ type = 'team'; id = $team.DatabaseID }
             DeploymentBranchPolicy = 'CustomBranchPolicies'
+        }
         Set-GitHubEnvironment @params
 
         Output:
@@ -43,15 +44,18 @@ filter Set-GitHubEnvironment {
         Creates or updates the "staging" environment with a 30-minute wait timer.
 
         .OUTPUTS
-        PSCustomObject
+        GitHubEnvironment
 
         .NOTES
         Returns the response object from the GitHub API call.
 
         .LINK
         https://psmodule.io/GitHub/Functions/Environments/Set-GitHubEnvironment/
+
+        .LINK
+        [Create or update an environment](https://docs.github.com/rest/deployments/environments#create-or-update-an-environment)
     #>
-    [OutputType([pscustomobject])]
+    [OutputType([GitHubEnvironment])]
     [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Default')]
     param(
         # The name of the organization.
@@ -211,16 +215,31 @@ filter Set-GitHubEnvironment {
             $body['prevent_self_review'] = [bool]$PreventSelfReview
         }
 
+        $encodedName = [System.Uri]::EscapeDataString($Name)
         $inputObject = @{
-            Method      = 'PUT'
-            APIEndpoint = "/repos/$Owner/$Repository/environments/$Name"
-            Body        = $body
-            Context     = $Context
+            Method  = 'PUT'
+            Uri     = $Context.ApiBaseUri + "/repos/$Owner/$Repository/environments/$encodedName"
+            Body    = $body
+            Context = $Context
         }
 
         if ($PSCmdlet.ShouldProcess("Environment [$Owner/$Repository/$Name]", 'Set')) {
             Invoke-GitHubAPI @inputObject | ForEach-Object {
-                Write-Output $_.Response
+                Write-Output $_.Response | ForEach-Object {
+                    [GitHubEnvironment]@{
+                        Name                   = $_.name
+                        DatabaseID             = $_.id
+                        NodeID                 = $_.node_id
+                        Url                    = $_.html_url
+                        Owner                  = $Owner
+                        Repository             = $Repository
+                        CreatedAt              = $_.created_at
+                        UpdatedAt              = $_.updated_at
+                        CanAdminsBypass        = $_.can_admins_bypass
+                        ProtectionRules        = $_.protection_rules
+                        DeploymentBranchPolicy = $_.deployment_branch_policy
+                    }
+                }
             }
         }
     }
diff --git a/tests/Environments.Tests.ps1 b/tests/Environments.Tests.ps1
@@ -14,6 +14,7 @@ param()
 BeforeAll {
     $repoSuffix = 'EnvironmentTest'
     $environmentName = 'production'
+    $os = $env:RUNNER_OS
 }
 
 Describe 'As a user - Fine-grained PAT token - user account access (USER_FG_PAT)' {
@@ -43,7 +44,21 @@ Describe 'As a user - Fine-grained PAT token - user account access (USER_FG_PAT)
             $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name $environmentName -WaitTimer 10
             $result | Should -Not -BeNullOrEmpty
             $result.Name | Should -Be $environmentName
-            $result.protection_rules.wait_timer | Should -Be 10
+            $result.ProtectionRules.wait_timer | Should -Be 10
+        }
+
+        It 'Set-GitHubEnvironment - creates an environment with a slash in the name' {
+            $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os"
+            $result | Should -Not -BeNullOrEmpty
+            $result.Name | Should -Be "$environmentName/$os"
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -Not -BeNullOrEmpty
+        }
+
+        It 'Remove-GitHubEnvironment - deletes an environment with a slash in the name' {
+            {
+                Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Remove-GitHubEnvironment -Confirm:$false
+            } | Should -Not -Throw
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -BeNullOrEmpty
         }
 
         It 'Get-GitHubEnvironment - retrieves a specific environment' {
@@ -95,7 +110,20 @@ Describe 'As a user - Fine-grained PAT token - organization account access (ORG_
             $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name $environmentName -WaitTimer 10
             $result | Should -Not -BeNullOrEmpty
             $result.Name | Should -Be $environmentName
-            $result.protection_rules.wait_timer | Should -Be 10
+            $result.ProtectionRules.wait_timer | Should -Be 10
+        }
+
+        It 'Set-GitHubEnvironment - creates an environment with a slash in the name' {
+            $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os"
+            $result | Should -Not -BeNullOrEmpty
+            $result.Name | Should -Be "$environmentName/$os"
+        }
+
+        It 'Remove-GitHubEnvironment - deletes an environment with a slash in the name' {
+            {
+                Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Remove-GitHubEnvironment -Confirm:$false
+            } | Should -Not -Throw
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -BeNullOrEmpty
         }
 
         It 'Get-GitHubEnvironment - retrieves a specific environment' {
@@ -152,7 +180,21 @@ Describe 'As a GitHub App - Enterprise (APP_ENT)' {
             $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name $environmentName -WaitTimer 10
             $result | Should -Not -BeNullOrEmpty
             $result.Name | Should -Be $environmentName
-            $result.protection_rules.wait_timer | Should -Be 10
+            $result.ProtectionRules.wait_timer | Should -Be 10
+        }
+
+        It 'Set-GitHubEnvironment - creates an environment with a slash in the name' {
+            $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os"
+            $result | Should -Not -BeNullOrEmpty
+            $result.Name | Should -Be "$environmentName/$os"
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -Not -BeNullOrEmpty
+        }
+
+        It 'Remove-GitHubEnvironment - deletes an environment with a slash in the name' {
+            {
+                Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Remove-GitHubEnvironment -Confirm:$false
+            } | Should -Not -Throw
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -BeNullOrEmpty
         }
 
         It 'Get-GitHubEnvironment - retrieves a specific environment' {
@@ -205,7 +247,21 @@ Describe 'As a GitHub App - Organization (APP_ORG)' {
             $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name $environmentName -WaitTimer 10
             $result | Should -Not -BeNullOrEmpty
             $result.Name | Should -Be $environmentName
-            $result.protection_rules.wait_timer | Should -Be 10
+            $result.ProtectionRules.wait_timer | Should -Be 10
+        }
+
+        It 'Set-GitHubEnvironment - creates an environment with a slash in the name' {
+            $result = Set-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os"
+            $result | Should -Not -BeNullOrEmpty
+            $result.Name | Should -Be "$environmentName/$os"
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -Not -BeNullOrEmpty
+        }
+
+        It 'Remove-GitHubEnvironment - deletes an environment with a slash in the name' {
+            {
+                Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Remove-GitHubEnvironment -Confirm:$false
+            } | Should -Not -Throw
+            Get-GitHubEnvironment -Owner $owner -Repository $repo -Name "$environmentName/$os" | Should -BeNullOrEmpty
         }
 
         It 'Get-GitHubEnvironment - retrieves a specific environment' {

Original file line number	Diff line number	Diff line change
`@@ -57,10 +57,11 @@ filter Remove-GitHubEnvironment {`
`57`	`57`	`}`
`58`	`58`
`59`	`59`	`process {`
	`60`	`+ $encodedName = [System.Uri]::EscapeDataString($Name)`
`60`	`61`	`$inputObject = @{`
`61`		`- Method = 'DELETE'`
`62`		`- APIEndpoint = "/repos/$Owner/$Repository/environments/$Name"`
`63`		`- Context = $Context`
	`62`	`+ Method = 'DELETE'`
	`63`	`+ Uri = $Context.ApiBaseUri + "/repos/$Owner/$Repository/environments/$encodedName"`
	`64`	`+ Context = $Context`
`64`	`65`	`}`
`65`	`66`
`66`	`67`	`if ($PSCmdlet.ShouldProcess("Environment [$Owner/$Repository/$Name]", 'Delete')) {`