Amadevus / pwsh-script

GitHub Action to run PowerShell scripts in a rich, prepared scope - inspired by actions/github-script.
MIT License
47 stars 8 forks source link
actions github-action github-actions github-actions-javascript powershell

pwsh-script

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

GitHub top language CI GitHub release (latest by date) GitHub commits since latest release (by date)

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:

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:

For module documentation, see GitHubActionsCore README.

The module has a good test suite written in Pester.

Notes

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.