{"id":13530984,"url":"https://github.com/Amadevus/pwsh-script","last_synced_at":"2025-04-01T19:31:03.760Z","repository":{"id":54649178,"uuid":"269564107","full_name":"Amadevus/pwsh-script","owner":"Amadevus","description":"GitHub Action to run PowerShell scripts in a rich, prepared scope - inspired by actions/github-script.","archived":false,"fork":false,"pushed_at":"2024-02-05T20:02:44.000Z","size":100,"stargazers_count":48,"open_issues_count":8,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-13T14:58:14.529Z","etag":null,"topics":["actions","github-action","github-actions","github-actions-javascript","powershell"],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Amadevus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-05T07:46:36.000Z","updated_at":"2024-12-17T16:13:38.000Z","dependencies_parsed_at":"2024-06-18T15:50:01.487Z","dependency_job_id":"32ce9ce1-803d-4f7d-9a28-d8b0f53e83d7","html_url":"https://github.com/Amadevus/pwsh-script","commit_stats":{"total_commits":68,"total_committers":2,"mean_commits":34.0,"dds":0.05882352941176472,"last_synced_commit":"97a8b211a5922816aa8a69ced41fa32f23477186"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amadevus%2Fpwsh-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amadevus%2Fpwsh-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amadevus%2Fpwsh-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Amadevus%2Fpwsh-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Amadevus","download_url":"https://codeload.github.com/Amadevus/pwsh-script/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246700188,"owners_count":20819833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","github-action","github-actions","github-actions-javascript","powershell"],"created_at":"2024-08-01T07:00:58.756Z","updated_at":"2025-04-01T19:30:58.752Z","avatar_url":"https://github.com/Amadevus.png","language":"PowerShell","readme":"# pwsh-script\n\nGitHub Action to run PowerShell scripts that use the workflow run context - inspired by [actions/github-script].\n\n![GitHub top language](https://img.shields.io/github/languages/top/Amadevus/pwsh-script?logo=powershell)\n[![CI](https://github.com/Amadevus/pwsh-script/workflows/CI/badge.svg?branch=main)](https://github.com/Amadevus/pwsh-script/actions?query=workflow%3ACI)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Amadevus/pwsh-script)](https://github.com/Amadevus/pwsh-script/releases/latest)\n![GitHub commits since latest release (by date)](https://img.shields.io/github/commits-since/Amadevus/pwsh-script/latest)\n\nIn order to use this action, `script` input is required. The value of that input should be\nthe body of a PowerShell script.\nThe following variables are initialized before your script is executed:\n- `$github` is an object representing the workflow's [`github` context]\n- `$job` is an object representing the workflow's [`job` context]\n- `$runner` is an object representing the workflow's [`runner` context]\n- `$strategy` is an object representing the workflow's [`strategy` context]\n- `$matrix` is an object representing the workflow's [`matrix` context]\n\n[actions/github-script]: https://github.com/actions/github-script\n[`@actions/core`]: https://github.com/actions/toolkit/tree/main/packages/core\n[`github` context]: https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context\n[`job` context]: https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#job-context\n[`runner` context]: https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#runner-context\n[`strategy` context]: https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#strategy-context\n[`matrix` context]: https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#matrix-context\n\n## Demo\n\nYou can try out this action yourself by commenting on a [demo issue](https://github.com/Amadevus/pwsh-script/issues/2). Instructions in the issue.\n\n## Reading step results\nThe return value of the script will be made available in the step's outputs under the `result` key.\n```yml\n- uses: Amadevus/pwsh-script@v2\n  id: my-script\n  with:\n    script: '1 + 1'\n- run: echo \"${{ steps.my-script.outputs.result }}\"\n  # should print 2\n```\n\n## Result encoding\n\nIf the script return value is a single string, it'll be set as the value of the `result` output directly.\nIn any other case, it'll be passed to `ConvertTo-Json $Value -Depth 100 -Compress -EscapeHandling EscapeNonAscii`\nand the string result of that call will be set as the output value.\n```yml\n- uses: Amadevus/pwsh-script@v2\n  id: bad-script\n  with:\n    script: return [ordered]@{ x = 'a1'; y = 'b2' }\n  continue-on-error: true\n- run: echo '${{ steps.bad-script.outputs.result }}'\n  # should print {\"x\":\"a1\",\"y\":\"b2\"}\n```\n\n## Error handling\n\nIf the script throws an error/exception, it'll be caught, printed to the log and the error message\nwill be set as an `error` output of the action.\n```yml\n- uses: Amadevus/pwsh-script@v2\n  id: bad-script\n  with:\n    script: 'throw \"this fails\"'\n  continue-on-error: true\n- run: echo \"${{ steps.bad-script.outputs.error }}\"\n  # should print 'this fails'\n```\n\n## Actions cmdlets\nA module called `GitHubActionsCore` will be imported in the scope of your script. It provides commands\nthat are available for JavaScript Actions by [`@actions/core`] package, such as:\n- `Add-ActionPath`\n- `Write-ActionWarning`\n- `Set-ActionFailed`\n\nFor module documentation, see [GitHubActionsCore README](docs/GitHubActionsCore/README.md).\n\nThe module has a good test suite written in Pester.\n\n## Notes\n\n- This action requires `pwsh` to actually be available and on PATH of the runner - which\n  is the case for all GitHub-provided runner VMs; for your own runners you need to take care of that yourself.\n- This action is a [`composite` action](https://docs.github.com/en/actions/creating-actions/creating-a-composite-run-steps-action).\n- This action has an extensive self-testing suite in [CI workflow](.github/workflows/ci.yml).\n- Although available in the imported module, `Get-ActionInput` and `Set-ActionOutput` won't really work when used as part of this action.\n\n## Examples\n\n```yml\n- uses: Amadevus/pwsh-script@v2\n  id: script\n  with:\n    script: |\n      Write-ActionDebug \"Visible only when ACTIONS_STEP_DEBUG secret is set\"\n\n      # access full context objects:\n      if ($github.event.repository.full_name -ne $github.repository) {\n        # throwing causes the step to fail\n        throw \"something fishy's going on, repos don't match\"\n      }\n\n      $someData = Get-MyCustomData\n      # data may contain workflow command strings (e.g. '::warning::...')\n      # prevent runner interpreting these\n      Invoke-ActionNoCommandsBlock -GenerateToken {\n        # this won't result in any workflow commands\n        Write-Host $someData\n        Write-ActionError \"not interpreted as error\"\n      }\n      # commands work again\n\n      # set env:BE_AWESOME=always here and for the following steps\n      Set-ActionVariable BE_AWESOME always\n\n      # add our custom tool to PATH for the following steps:\n      $toolPath = Resolve-Path ./tools/bin\n      Add-ActionPath $toolPath\n\n      # warn if it's too late for people to work in Greenwich ;)\n      if ([datetime]::UtcNow.Hour -ge 22) {\n        Write-ActionWarning \"It's time to go to bed. Don't write code late at night! ⚠\"\n      }\n```\n\n## Changelog\n\nChangelog is kept in [CHANGELOG.md](CHANGELOG.md)\n\n## License\n\nThis action is licensed under [MIT license](LICENSE).","funding_links":[],"categories":["powershell","Community Resources"],"sub_categories":["Utility"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAmadevus%2Fpwsh-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAmadevus%2Fpwsh-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAmadevus%2Fpwsh-script/lists"}