README.md

pwsh-script

GitHub Action to run PowerShell scripts that use the workflow run context - inspired by actions/github-script.

In order to use this action, script input is required. The value of that input should be the body of a PowerShell script. The following variables are initialized before your script is executed:

• $github is an object representing the workflow's github context
• $job is an object representing the workflow's job context
• $runner is an object representing the workflow's runner context
• $strategy is an object representing the workflow's strategy context
• $matrix is an object representing the workflow's matrix context

Demo

You can try out this action yourself by commenting on a demo issue. Instructions in the issue.

Reading step results

The return value of the script will be made available in the step's outputs under the result key.

- uses: Amadevus/pwsh-script@v2
  id: my-script
  with:
    script: '1 + 1'
- run: echo "${{ steps.my-script.outputs.result }}"
  # should print 2

Result encoding

If the script return value is a single string, it'll be set as the value of the result output directly. In any other case, it'll be passed to ConvertTo-Json $Value -Depth 100 -Compress -EscapeHandling EscapeNonAscii and the string result of that call will be set as the output value.

- uses: Amadevus/pwsh-script@v2
  id: bad-script
  with:
    script: return [ordered]@{ x = 'a1'; y = 'b2' }
  continue-on-error: true
- run: echo '${{ steps.bad-script.outputs.result }}'
  # should print {"x":"a1","y":"b2"}

Error handling

If the script throws an error/exception, it'll be caught, printed to the log and the error message will be set as an error output of the action.

- uses: Amadevus/pwsh-script@v2
  id: bad-script
  with:
    script: 'throw "this fails"'
  continue-on-error: true
- run: echo "${{ steps.bad-script.outputs.error }}"
  # should print 'this fails'

Actions cmdlets

A module called GitHubActionsCore will be imported in the scope of your script. It provides commands that are available for JavaScript Actions by @actions/core package, such as:

• Add-ActionPath
• Write-ActionWarning
• Set-ActionFailed

For module documentation, see GitHubActionsCore README.

The module has a good test suite written in Pester.

Notes

• This action requires pwsh to actually be available and on PATH of the runner - which is the case for all GitHub-provided runner VMs; for your own runners you need to take care of that yourself.
• This action is a composite action.
• This action has an extensive self-testing suite in CI workflow.
• Although available in the imported module, Get-ActionInput and Set-ActionOutput won't really work when used as part of this action.

Examples

- uses: Amadevus/pwsh-script@v2
  id: script
  with:
    script: |
      Write-ActionDebug "Visible only when ACTIONS_STEP_DEBUG secret is set"

      # access full context objects:
      if ($github.event.repository.full_name -ne $github.repository) {
        # throwing causes the step to fail
        throw "something fishy's going on, repos don't match"
      }

      $someData = Get-MyCustomData
      # data may contain workflow command strings (e.g. '::warning::...')
      # prevent runner interpreting these
      Invoke-ActionNoCommandsBlock -GenerateToken {
        # this won't result in any workflow commands
        Write-Host $someData
        Write-ActionError "not interpreted as error"
      }
      # commands work again

      # set env:BE_AWESOME=always here and for the following steps
      Set-ActionVariable BE_AWESOME always

      # add our custom tool to PATH for the following steps:
      $toolPath = Resolve-Path ./tools/bin
      Add-ActionPath $toolPath

      # warn if it's too late for people to work in Greenwich ;)
      if ([datetime]::UtcNow.Hour -ge 22) {
        Write-ActionWarning "It's time to go to bed. Don't write code late at night! ⚠"
      }

Changelog

Changelog is kept in CHANGELOG.md

License

This action is licensed under MIT license.