🩹 [Patch]: Add more workflow command functions (#169)

## Description This pull request includes several new functions and improvements to existing ones in the `src/functions/public/Commands` directory. The most important changes include the addition of new functions for GitHub Actions, updates to existing functions to enhance their capabilities, and renaming of functions for better clarity. - Fixes #110 ### Additions: * [`Add-GitHubSystemPath.ps1`](diffhunk://#diff-2a74a803071ff3d970b09b642b61fbae322410170600e08a5d7173ed09254492R1-R26): Adds a new function to prepend a directory to the system PATH variable. * [`Disable-GitHubCommand.ps1`](diffhunk://#diff-20a12a93ae6e4995d9fdbd1fff85500126e81035eb06f606158e80eb65d320dfR1-R42): Introduces a function to stop processing workflow commands. * [`Enable-GitHubCommand.ps1`](diffhunk://#diff-e1b44a432ca1bb83209ab898c1d82cf92016800aa1b055e1e817457af149ec6bR1-R41): Adds a function to resume processing workflow commands. * [`Set-GitHubStepSummary.ps1`](diffhunk://#diff-c61e80066627b1dda0dc3fcf76fba52207ce7bfc17fd55f9fc6cc58dc0f813b8R1-R54): Adds a function to set a summary for the step in GitHub Actions. * [`Write-GitHubDebug.ps1`](diffhunk://#diff-7120cbbd63dbf6bb75dcdc1354b1d5399073aac2927cf5a6b4c33e1f53410024R1-R43): Introduces a function to write a debug message in GitHub Actions. ### Updates: * [`Add-GitHubMask.ps1`](diffhunk://#diff-5b741777f60d6634c48131045c92c294ac5d0cd9bbbba20d3210597721ce848aL4-R4): Updates the description to clarify that it masks a value in a log. * [`Set-GitHubEnvironmentVariable.ps1`](diffhunk://#diff-20d01d8a16531c894ad99b9f5b31eaf5495d487ca767996774ade7f08fba7953L29-R45): Enhances the function to support multiline strings and adds verbose logging. * [`Set-GitHubOutput.ps1`](diffhunk://#diff-e3aad576b04b558ce2a70ebd0dcc703418e81431e3c0f0ed63a3736ae35de2efR38-R58): Updates the function to support SecureString and multiline strings, and adds verbose logging. ### Renaming to align with GitHub prefix: * `Add-Mask.ps1` to `Add-GitHubMask.ps1` (Added Add-Mask as alias). * `Set-LogGroup.ps1` to `Set-GitHubLogGroup.ps1` * `Start-LogGroup.ps1` to `Start-GitHubLogGroup.ps1` * `Stop-LogGroup.ps1` to `Stop-GitHubLogGroup.ps1` ## Type of change  - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [x] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [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
PSModule · Nov 27, 2024 · 464ba46 · 464ba46
1 parent 68be42c
commit 464ba46
Show file tree

Hide file tree

Showing 16 changed files with 508 additions and 25 deletions.
diff --git a/src/functions/public/Auth/Disconnect-GitHubAccount.ps1 b/src/functions/public/Auth/Disconnect-GitHubAccount.ps1
@@ -39,6 +39,7 @@
         [string] $Context = (Get-GitHubConfig -Name 'DefaultContext'),
 
         # Silently disconnects from GitHub.
+        [Parameter()]
         [switch] $Silent
     )
 

diff --git a/src/functions/public/Commands/Add-Mask.ps1 → ...ctions/public/Commands/Add-GitHubMask.ps1 b/src/functions/public/Commands/Add-Mask.ps1 → ...ctions/public/Commands/Add-GitHubMask.ps1
@@ -1,7 +1,7 @@
-filter Add-Mask {
+filter Add-GitHubMask {
     <#
         .SYNOPSIS
-        Mask a value in GitHub Actions
+        Masks a value in a log
 
         .DESCRIPTION
         Masking a value prevents a string or variable from being printed in the log. Each masked word separated by whitespace is
@@ -20,9 +20,9 @@
         Masks the value of $SecretValue1 and $SecretValue2 so that its printed like ***, using the pipeline
 
         .NOTES
-        [Masking a value in a log | GitHub Docs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log)
+        [Masking a value in a log](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log)
     #>
-    [Alias('Mask')]
+    [Alias('Mask', 'Add-Mask')]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSAvoidLongLines', '', Scope = 'Function',
         Justification = 'Long documentation URL'

diff --git a/src/functions/public/Commands/Add-GitHubSystemPath.ps1 b/src/functions/public/Commands/Add-GitHubSystemPath.ps1
@@ -0,0 +1,31 @@
+function Add-GitHubSystemPath {
+    <#
+        .SYNOPSIS
+        Adds a system path to the GitHub Actions environment
+
+        .DESCRIPTION
+        Prepends a directory to the system PATH variable and automatically makes it available to all subsequent actions in the current job;
+        the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can use
+        echo "$env:PATH" in a step or an action.
+
+        .EXAMPLE
+        Add-GitHubSystemPath -Path '$HOME/.local/bin'
+
+        .NOTES
+        [Adding a system path](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path)
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long documentation URL'
+    )]
+    [OutputType([void])]
+    [CmdletBinding()]
+    param (
+        [string]$Path
+    )
+
+    Write-Verbose "Current PATH: $env:PATH"
+    Write-Verbose "Adding system path: $Path"
+
+    $Path | Out-File -FilePath $env:GITHUB_PATH -Append
+}
diff --git a/src/functions/public/Commands/Disable-GitHubCommand.ps1 b/src/functions/public/Commands/Disable-GitHubCommand.ps1
@@ -0,0 +1,42 @@
+function Disable-GitHubCommand {
+    <#
+        .SYNOPSIS
+        Stops workflow commands
+
+        .DESCRIPTION
+        Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command.
+        For example, you could stop logging to output an entire script that has comments.
+
+        To stop the processing of workflow commands, pass a unique string to the function. To resume processing workflow commands, pass the same string
+        that you used to stop workflow commands to the Enable-GitHubCommand.
+
+        .EXAMPLE
+        Disable-GitHubCommand "123"
+
+        Stops processing any workflow commands.
+
+        .NOTES
+        [Stopping and starting workflow commands](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#stopping-and-starting-workflow-commands)
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingWriteHost', '', Scope = 'Function',
+        Justification = 'Intended for logging in Github Runners which does support Write-Host'
+    )]
+    [OutputType([void])]
+    [CmdletBinding()]
+    param (
+        # The unique string to stop the processing of workflow commands
+        [Parameter(Mandatory)]
+        [string] $String
+    )
+
+    $String = $String.ToLower()
+
+    if ($env:GITHUB_ACTIONS -eq 'true') {
+        Write-Host "::stop-commands::$String"
+    }
+}
diff --git a/src/functions/public/Commands/Enable-GitHubCommand.ps1 b/src/functions/public/Commands/Enable-GitHubCommand.ps1
@@ -0,0 +1,41 @@
+function Enable-GitHubCommand {
+    <#
+        .SYNOPSIS
+        Resumes workflow commands
+
+        .DESCRIPTION
+        Resumes processing any workflow commands.
+
+        To stop the processing of workflow commands, pass a unique string to the function. To resume processing workflow commands, pass the same string
+        that you used to stop workflow commands to the Enable-GitHubCommand.
+
+        .EXAMPLE
+        Enable-GitHubCommand "123"
+
+        Resumes processing any workflow commands.
+
+        .NOTES
+        [Stopping and starting workflow commands](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#stopping-and-starting-workflow-commands)
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingWriteHost', '', Scope = 'Function',
+        Justification = 'Intended for logging in Github Runners which does support Write-Host'
+    )]
+    [OutputType([void])]
+    [CmdletBinding()]
+    param (
+        # The unique string to resume the processing of workflow commands
+        [Parameter(Mandatory)]
+        [string] $String
+    )
+
+    $String = $String.ToLower()
+
+    if ($env:GITHUB_ACTIONS -eq 'true') {
+        Write-Host "::$String::"
+    }
+}
diff --git a/src/functions/public/Commands/Set-GitHubEnvironmentVariable.ps1 b/src/functions/public/Commands/Set-GitHubEnvironmentVariable.ps1
@@ -1,20 +1,27 @@
 function Set-GitHubEnvironmentVariable {
     <#
         .SYNOPSIS
-        Set a GitHub environment variable
+        Setting an environment variable
 
         .DESCRIPTION
         Set a GitHub environment variable
 
         .EXAMPLE
         Set-GitHubEnv -Name 'MyVariable' -Value 'MyValue'
+
+        .NOTES
+        [Setting an environment variable](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable)
     #>
-    [OutputType([void])]
-    [Alias('Set-GitHubEnv')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
         Justification = 'Does not change system state significantly'
     )]
+    [OutputType([void])]
+    [Alias('Set-GitHubEnv')]
     [CmdletBinding()]
     param (
         # Name of the variable
@@ -26,6 +33,14 @@
         [AllowNull()]
         [string] $Value
     )
-    Write-Verbose "[$Name] = [$Value]"
-    "$Name=$Value" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+    Write-Verbose "Env: [$Name] = [$Value]"
+
+    $Value = $Value.Split([System.Environment]::NewLine)
+    $guid = [guid]::NewGuid().Guid
+    "$Name<<$guid" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+    $Value | ForEach-Object {
+        $_ | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+    }
+    "$guid" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 }
diff --git a/...unctions/public/Commands/Set-LogGroup.ps1 → ...ns/public/Commands/Set-GitHubLogGroup.ps1 b/...unctions/public/Commands/Set-LogGroup.ps1 → ...ns/public/Commands/Set-GitHubLogGroup.ps1
@@ -1,4 +1,4 @@
-function Set-LogGroup {
+function Set-GitHubLogGroup {
     <#
         .SYNOPSIS
         Encapsulates commands with a log group in GitHub Actions
@@ -8,7 +8,7 @@
         Allows for colapsing of code in IDE for code that belong together.
 
         .EXAMPLE
-        Set-LogGroup -Name 'MyGroup' -ScriptBlock {
+        Set-GitHubLogGroup -Name 'MyGroup' -ScriptBlock {
             Write-Host 'Hello, World!'
         }
 
@@ -40,7 +40,7 @@
         [scriptblock] $ScriptBlock
     )
 
-    Start-LogGroup -Name $Name
+    Start-GitHubLogGroup -Name $Name
     . $ScriptBlock
-    Stop-LogGroup
+    Stop-GitHubLogGroup
 }
diff --git a/src/functions/public/Commands/Set-GitHubNoCommandGroup.ps1 b/src/functions/public/Commands/Set-GitHubNoCommandGroup.ps1
@@ -0,0 +1,50 @@
+function Set-GitHubNoCommandGroup {
+    <#
+        .SYNOPSIS
+        Disables workflow commands for a block of code.
+
+        .DESCRIPTION
+        DSL approach for GitHub Action commands.
+        Allows for colapsing of code in IDE for code that belong together.
+
+        .EXAMPLE
+        Set-GitHubNoCommandGroup {
+            Write-Host 'Hello, World!'
+            Write-GithubError 'This is an error'
+        }
+
+        Groups commands where no workflow commands are run.
+
+        .EXAMPLE
+        NoLogGroup 'MyGroup' {
+            Write-Host 'Hello, World!'
+            Write-GithubError 'This is an error'
+        }
+
+        Groups commands where no workflow commands are run, using an alias and DSL approach.
+
+        .NOTES
+        [Stopping and starting workflow commands](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#stopping-and-starting-workflow-commands)
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
+        Justification = 'Does not change state'
+    )]
+    [CmdletBinding()]
+    [Alias('NoLogGroup')]
+    param(
+        # The script block to execute
+        [Parameter(Mandatory)]
+        [scriptblock] $ScriptBlock
+    )
+
+    $guid = [string][guid]::NewGuid().Guid
+
+    Disable-GitHubCommand -String $guid
+    . $ScriptBlock
+    Enable-GitHubCommand -String $guid
+}
diff --git a/src/functions/public/Commands/Set-GitHubOutput.ps1 b/src/functions/public/Commands/Set-GitHubOutput.ps1
@@ -4,19 +4,26 @@
         Set a output variable in GitHub Actions
 
         .DESCRIPTION
-        Set a output variable in GitHub Actions. If the variable is a SecureString, it will be converted to plain text and masked.
+        Supports SecureString and multiline strings.
 
         .EXAMPLE
         Set-GitHubOutput -Name 'MyOutput' -Value 'Hello, World!'
 
         Creates a new output variable named 'MyOutput' with the value 'Hello, World!'.
+
+        .NOTES
+        [Setting an output parameter](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter)
     #>
-    [OutputType([void])]
-    [Alias('Output')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
         Justification = 'Does not change system state significantly'
     )]
+    [OutputType([void])]
+    [Alias('Output')]
     [CmdletBinding()]
     param (
         # Name of the variable
@@ -28,15 +35,25 @@
         [AllowNull()]
         [object] $Value
     )
+
     if ($Value -Is [securestring]) {
         $Value = $Value | ConvertFrom-SecureString -AsPlainText -Force
         Add-Mask -Value $Value
     }
-    Write-Verbose (@{ $Name = $Value } | Format-Table -Wrap -AutoSize | Out-String)
-    "$Name=$Value" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
     if ([string]::IsNullOrEmpty($env:GITHUB_ACTION)) {
-        Write-Warning "Cannot create output as the step has no ID."
-    } else {
-        Write-Verbose "Output: [$Name] avaiable as `${{ steps.$env:GITHUB_ACTION.outputs.$Name }}'"
+        Write-Warning 'Cannot create output as the step has no ID.'
+    }
+
+    Write-Verbose "Output: [$Name] = [$Value]"
+
+    $Value = $Value.Split([System.Environment]::NewLine)
+    $guid = [guid]::NewGuid().Guid
+    "$Name<<$guid" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+    $Value | ForEach-Object {
+        $_ | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
     }
+    "$guid" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+    Write-Verbose "Output: [$Name] avaiable as `${{ steps.$env:GITHUB_ACTION.outputs.$Name }}'"
 }
diff --git a/src/functions/public/Commands/Set-GitHubStepSummary.ps1 b/src/functions/public/Commands/Set-GitHubStepSummary.ps1
@@ -0,0 +1,54 @@
+function Set-GitHubStepSummary {
+    <#
+        .SYNOPSIS
+        Set a summary for the step in GitHub Actions
+
+        .DESCRIPTION
+        You can set some custom Markdown for each job so that it will be displayed on the summary page of a workflow run.
+        You can use job summaries to display and group unique content, such as test result summaries, so that someone viewing
+        the result of a workflow run doesn't need to go into the logs to see important information related to the run, such as failures.
+
+        Job summaries support GitHub flavored Markdown, and you can add your Markdown content for a step to the `GITHUB_STEP_SUMMARY`
+        environment file. `GITHUB_STEP_SUMMARY` is unique for each step in a job. For more information about the per-step file that
+        `GITHUB_STEP_SUMMARY` references, see [Environment files](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions?utm_source=chatgpt.com#environment-files).
+
+        When a job finishes, the summaries for all steps in a job are grouped together into a single job summary and are shown on the
+        workflow run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time.
+
+        .EXAMPLE
+        Set-GitHubStepSummary -Summary 'Hello, World!'
+
+        .NOTES
+        [Adding a job summary](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions?utm_source=chatgpt.com#adding-a-job-summary)
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidLongLines', '', Scope = 'Function',
+        Justification = 'Long doc links'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
+        Justification = 'Does not change system state significantly'
+    )]
+    [OutputType([void])]
+    [Alias('Summary')]
+    [CmdletBinding()]
+    param (
+        # Summary of the step
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [string] $Summary,
+
+        # Whether to overwrite the existing summary
+        [switch] $Overwrite
+    )
+
+    Write-Verbose "Step summary:"
+    Write-Verbose $Summary
+
+    $Append = -not $Overwrite
+
+    $Summary = $Summary.Split([System.Environment]::NewLine)
+    $Summary | ForEach-Object {
+        $_ | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append:$Append
+    }
+}