Skip to content

Commit ca9e2ea

Browse files
MariusStorhaugMariusStorhaug
authored
🩹 [Patch]: Document usage of the Script parameter (#28)
## Description - Fixes #27 This pull request includes significant updates to the `README.md` file for improved clarity and additional examples, as well as changes to the `TestWorkflow.yml` to test various script paths. Documentation improvements: * [`README.md`](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L3-R31): Improved descriptions, added clarity to existing examples, and included new examples for running scripts in different formats and contexts. [[1]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L3-R31) [[2]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L54-R118) [[3]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L94-R138) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L114-R157) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L133-R177) [[6]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L157-L162) Workflow updates: * [`.github/workflows/TestWorkflow.yml`](diffhunk://#diff-242a265d6d6bfff6094c9285345022d0e6d7ddde58504dfc80249fafbd89ba2cL58-R108): Added multiple test cases for running GitHub PowerShell scripts using different path syntaxes to ensure compatibility across various environments. ## Type of change <!-- Use the check-boxes [x] on the options that are relevant. --> - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [x] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist <!-- Use the check-boxes [x] on the options that are relevant. --> - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas
1 parent 81a24b8 commit ca9e2ea

File tree

3 files changed

+126
-46
lines changed

3 files changed

+126
-46
lines changed

‎.github/workflows/TestWorkflow.yml

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,57 @@ jobs:
5555
- name: Checkout repo
5656
uses: actions/checkout@v4
5757

58-
- name: Action-Test
58+
# # Not a supported way of running the action
59+
# # This syntax is specifically for using a function in a specific module
60+
# # i.e.: moduleName\functionName
61+
# - name: Action-Test [tests\info.ps1]
62+
# if: success() || failure()
63+
# uses: ./
64+
# with:
65+
# Script: tests\info.ps1
66+
67+
- name: Action-Test [tests/info.ps1]
68+
if: success() || failure()
69+
uses: ./
70+
with:
71+
Script: tests/info.ps1
72+
73+
- name: Action-Test [.\tests\info.ps1]
74+
if: success() || failure()
75+
uses: ./
76+
with:
77+
Script: .\tests\info.ps1
78+
79+
- name: Action-Test [./tests/info.ps1]
80+
if: success() || failure()
81+
uses: ./
82+
with:
83+
Script: ./tests/info.ps1
84+
85+
- name: Action-Test [. .\tests\info.ps1]
86+
if: success() || failure()
87+
uses: ./
88+
with:
89+
Script: . .\tests\info.ps1
90+
91+
- name: Action-Test [. ./tests/info.ps1]
92+
if: success() || failure()
93+
uses: ./
94+
with:
95+
Script: . ./tests/info.ps1
96+
97+
- name: Action-Test [. '.\tests\info.ps1']
98+
if: success() || failure()
5999
uses: ./
60100
with:
61-
Debug: true
62-
Verbose: true
63101
Script: . '.\tests\info.ps1'
64102

103+
- name: Action-Test [. './tests/info.ps1']
104+
if: success() || failure()
105+
uses: ./
106+
with:
107+
Script: . './tests/info.ps1'
108+
65109
ActionTestCommands:
66110
name: Commands + Outputs
67111
runs-on: ${{ inputs.runs-on }}

‎README.md

Lines changed: 77 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
11
# GitHub-Script
22

3-
A GitHub Action used for running a PowerShell Script that uses the GitHub PowerShell module.
3+
A GitHub Action for running a PowerShell script that uses the GitHub PowerShell module.
44

5-
For more information on the available functions and automatic loaded variables, see the
6-
[GitHub PowerShell module documentation](https://psmodule.io/GitHub)
5+
For more information on available functions and automatically loaded variables, see the
6+
[GitHub PowerShell module documentation](https://psmodule.io/GitHub).
77

88
## Usage
99

1010
### Inputs
1111

12-
| Name | Description | Required | Default |
13-
| - | - | - | - |
14-
| `Script` | The script to run. Can be inline, multi-line or a path to a script file. | false | |
15-
| `Token` | Log in using an Installation Access Token (IAT). | false | `${{ github.token }}` |
16-
| `ClientID` | Log in using a GitHub App, using the App's Client ID and Private Key. | false | |
17-
| `PrivateKey` | Log in using a GitHub App, using the App's Client ID and Private Key. | false | |
18-
| `Debug` | Enable debug output. | false | `'false'` |
19-
| `Verbose` | Enable verbose output. | false | `'false'` |
20-
| `Version` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | false | |
21-
| `Prerelease` | Allow prerelease versions if available. | false | `'false'` |
22-
| `ShowOutput` | Show the output of the script. | false | `'false'` |
23-
| `WorkingDirectory` | The working directory where the script will run from. | false | `${{ github.workspace }}` |
12+
| Name | Description | Required | Default |
13+
|--------------------|---------------------------------------------------------------------------|----------|---------------------------|
14+
| `Script` | The script to run. Can be inline, multi-line, or a path to a script file. | false | |
15+
| `Token` | Log in using an Installation Access Token (IAT). | false | `${{ github.token }}` |
16+
| `ClientID` | Log in using a GitHub App, with the App's Client ID and Private Key. | false | |
17+
| `PrivateKey` | Log in using a GitHub App, with the App's Client ID and Private Key. | false | |
18+
| `Debug` | Enable debug output. | false | `'false'` |
19+
| `Verbose` | Enable verbose output. | false | `'false'` |
20+
| `Version` | Specifies the exact version of the GitHub module to install. | false | |
21+
| `Prerelease` | Allow prerelease versions if available. | false | `'false'` |
22+
| `ShowOutput` | Show the script's output. | false | `'false'` |
23+
| `WorkingDirectory` | The working directory where the script runs. | false | `${{ github.workspace }}` |
2424

2525
### Outputs
2626

27-
| Name | Description |
28-
| - | - |
29-
| `result` | The output of the script as a JSON object. To add outputs to `result`, use `Set-GitHubOutput`. |
27+
| Name | Description |
28+
|----------|---------------------------------------------------------------------------------------- |
29+
| `result` | The script output as a JSON object. To add outputs to `result`, use `Set-GitHubOutput`. |
3030

31-
To use the outputs in a subsequent step, you can use the following syntax:
31+
To use the outputs in a subsequent step, reference them as follows:
3232

3333
```yaml
3434
- uses: PSModule/GitHub-Script@v1
@@ -51,28 +51,71 @@ To use the outputs in a subsequent step, you can use the following syntax:
5151
Write-Output $result.Octocat.Image
5252
```
5353
54-
5554
### Examples
5655
57-
#### Example 1: Run a GitHub PowerShell script
56+
#### Example 1: Run a GitHub PowerShell script file
5857
59-
Run a script (`scripts/main.ps1`) that uses the GitHub PowerShell module, authenticated using the `GITHUB_TOKEN`.
58+
Runs a script (`scripts/main.ps1`) that uses the GitHub PowerShell module, authenticated using the `GITHUB_TOKEN`.
6059

6160
```yaml
6261
jobs:
6362
Run-Script:
6463
runs-on: ubuntu-latest
6564
steps:
66-
- name: Run script
65+
- name: Run inline script - single line
66+
uses: PSModule/GitHub-Script@v1
67+
with:
68+
Script: Get-GitHubPullRequest
69+
70+
- name: Run inline script - multiline
6771
uses: PSModule/GitHub-Script@v1
6872
with:
69-
Script: "scripts/main.ps1"
73+
Script: |
74+
LogGroup 'Get-GitHubPullRequest' {
75+
Get-GitHubPullRequest
76+
}
77+
78+
- name: Run script file - Local repository
79+
uses: PSModule/GitHub-Script@v1
80+
with:
81+
Script: ./scripts/main.ps1
82+
83+
- name: Run script file - In a composite action
84+
uses: PSModule/GitHub-Script@v1
85+
with:
86+
Script: ${{ github.action_path }}/scripts/main.ps1
7087
```
7188

89+
> [!IMPORTANT]
90+
> Use `${{ github.action_path }}/<pathToScript.ps1>` if you are creating an action of your own that uses this action as a step. This ensures
91+
> the path references your action rather than the `GitHub-Script` action repository. Using `$env:GITHUB_ACTION_PATH` can lead to mixed results
92+
> when nesting actions. The context syntax will expand to the correct path when the job is evaluated by GitHub before being processed by the runner.
93+
94+
The `Script` input supports these formats:
95+
96+
- Inline script:
97+
- Single-line
98+
- Multi-line
99+
- Path to a script file (recommended):
100+
- `scripts/main.ps1`
101+
- `.\scripts\main.ps1`
102+
- `./scripts/main.ps1`
103+
- `. .\scripts\main.ps1`
104+
- `. ./scripts/main.ps1`
105+
- `. '.\scripts\main.ps1'`
106+
- `. './scripts/main.ps1'`
107+
108+
> [!WARNING]
109+
> Using `tests\info.ps1` is PowerShell syntax for calling a function from a specific module (e.g., `Microsoft.PowerShell.Management\Get-ChildItem`).
110+
<!-- markdownlint-disable-next-line -->
111+
112+
> [!TIP]
113+
> Use script files instead of inline scripts for better support for development tools and linters. The PowerShell extension for Visual Studio Code and
114+
> linters like PSScriptAnalyzer work natively with script files.
115+
72116
#### Example 2: Run a GitHub PowerShell script without a token
73117

74-
Run a script that uses the GitHub PowerShell module.
75-
This example runs a non-authenticated script that gets the GitHub Zen message.
118+
Runs a non-authenticated script that retrieves the GitHub Zen message.
76119

77120
```yaml
78121
jobs:
@@ -91,8 +134,8 @@ jobs:
91134

92135
#### Example 3: Run a GitHub PowerShell script with a custom token
93136

94-
Run a script that uses the GitHub PowerShell module with a token. The token can be both a personal access token (PAT) or
95-
an installation access token (IAT). This example runs an authenticated script that gets the GitHub Zen message.
137+
Runs a script that uses the GitHub PowerShell module with a token. The token can be a personal access token (PAT) or
138+
an installation access token (IAT). This example retrieves the GitHub Zen message.
96139

97140
```yaml
98141
jobs:
@@ -111,8 +154,7 @@ jobs:
111154

112155
#### Example 4: Run a GitHub PowerShell script with a GitHub App using a Client ID and Private Key
113156

114-
Run a script that uses the GitHub PowerShell module with a GitHub App.
115-
This example runs an authenticated script that gets the GitHub App.
157+
Runs a script that uses the GitHub PowerShell module with a GitHub App. This example retrieves the GitHub App details.
116158

117159
```yaml
118160
jobs:
@@ -130,9 +172,9 @@ jobs:
130172
}
131173
```
132174

133-
#### Example 5: Using the outputs from the script
175+
#### Example 5: Using outputs from the script
134176

135-
Run a script that uses the GitHub PowerShell module and outputs the result.
177+
Runs a script that uses the GitHub PowerShell module and outputs the result.
136178

137179
```yaml
138180
- name: Run GitHub Script
@@ -150,13 +192,7 @@ Run a script that uses the GitHub PowerShell module and outputs the result.
150192
env:
151193
result: ${{ steps.test.outputs.result }}
152194
run: |
153-
$result = $env:result | ConvertFrom-Json
154-
Set-GitHubStepSummary -Summary $result.WISECAT
155-
Write-GitHubNotice -Message $result.Zen -Title 'GitHub Zen'
195+
$result = $env:result | ConvertFrom-Json
196+
Set-GitHubStepSummary -Summary $result.WISECAT
197+
Write-GitHubNotice -Message $result.Zen -Title 'GitHub Zen'
156198
```
157-
158-
## Related projects
159-
160-
- [actions/create-github-app-token](https://github.com/actions/create-github-app-token) -> Functionality will be brought into GitHub PowerShell module.
161-
- [actions/github-script](https://github.com/actions/github-script)
162-
- [PSModule/GitHub](https://github.com/PSModule/GitHub)

‎tests/info.ps1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
#Requires -Modules GitHub
22

3-
LogGroup ' - Event Info' {
3+
LogGroup ' - Get-GithubEventData' {
44
Get-GithubEventData | Format-List
55
}
66

7-
LogGroup ' - Runner Info' {
7+
LogGroup ' - Get-GithubRunnerData' {
88
Get-GithubRunnerData | Format-List
99
}

0 commit comments

Comments
 (0)