Skip to content

Commit 2c81030

Browse files
MariusStorhaugMariusStorhaug
committed
feat: update README to include inputs, setup/teardown scripts, and permissions for workflow
1 parent 8c0220a commit 2c81030

File tree

1 file changed

+112
-120
lines changed

1 file changed

+112
-120
lines changed

‎README.md‎

Lines changed: 112 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -68,31 +68,7 @@ Depending on the labels in the pull requests, the workflow will result in differ
6868
- Publishes the module to the PowerShell Gallery.
6969
- Creates a release on the GitHub repository.
7070

71-
### Scenario Matrix
72-
73-
This table shows when each job runs based on the trigger scenario:
74-
75-
| Job | Open/Updated PR | Merged PR | Abandoned PR | Manual Run |
76-
|-----|-----------------|-----------|--------------|------------|
77-
| **Get-Settings** | ✅ Always | ✅ Always | ✅ Always | ✅ Always |
78-
| **Lint-Repository** | ✅ Yes | ❌ No | ❌ No | ❌ No |
79-
| **Build-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
80-
| **Build-Docs** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
81-
| **Build-Site** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
82-
| **Test-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
83-
| **Lint-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
84-
| **Test-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
85-
| **BeforeAll-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
86-
| **Test-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
87-
| **AfterAll-ModuleLocal** | ✅ Yes | ✅ Yes | ✅ Yes* | ✅ Yes |
88-
| **Get-TestResults** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
89-
| **Get-CodeCoverage** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
90-
| **Publish-Site** | ❌ No | ✅ Yes | ❌ No | ❌ No |
91-
| **Publish-Module** | ✅ Yes** | ✅ Yes** | ✅ Yes*** | ✅ Yes** |
92-
93-
\* Runs for cleanup if tests were started
94-
\*\* Only when all tests/coverage/build succeed
95-
\*\*\* Publishes cleanup/retraction version
71+
## Usage
9672

9773
To use the workflow, create a new file in the `.github/workflows` directory of the module repository and add the following content.
9874

@@ -130,6 +106,116 @@ jobs:
130106
```
131107
</details>
132108

109+
### Inputs
110+
111+
| Name | Type | Description | Required | Default |
112+
| ---- | ---- | ----------- | -------- | ------- |
113+
| `Name` | `string` | The name of the module to process. This defaults to the repository name if nothing is specified. | `false` | N/A |
114+
| `SettingsPath` | `string` | The path to the settings file. Settings in the settings file take precedence over the action inputs. | `false` | `.github/PSModule.yml` |
115+
| `Version` | `string` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | `false` | `''` |
116+
| `Prerelease` | `boolean` | Whether to use a prerelease version of the 'GitHub' module. | `false` | `false` |
117+
| `Debug` | `boolean` | Whether to enable debug output. Adds a `debug` step to every job. | `false` | `false` |
118+
| `Verbose` | `boolean` | Whether to enable verbose output. | `false` | `false` |
119+
| `WorkingDirectory` | `string` | The path to the root of the repo. | `false` | `.` |
120+
121+
### Setup and Teardown Scripts
122+
123+
The workflow supports automatic execution of setup and teardown scripts for module tests:
124+
125+
- Scripts are automatically detected and executed if present
126+
- If no scripts are found, the workflow continues normally
127+
128+
#### Setup - `BeforeAll.ps1`
129+
130+
- Place in your test directories (`tests/BeforeAll.ps1`)
131+
- Runs once before all test matrix jobs to prepare the test environment
132+
- Deploy test infrastructure, download test data, initialize databases, or configure services
133+
- Has access to the same environment variables as your tests (secrets, GitHub token, etc.)
134+
135+
##### Example - `BeforeAll.ps1`
136+
137+
```powershell
138+
Write-Host "Setting up test environment..."
139+
# Deploy test infrastructure
140+
# Download test data
141+
# Initialize test databases
142+
Write-Host "Test environment ready!"
143+
```
144+
145+
#### Teardown - `AfterAll.ps1`
146+
147+
- Place in your test directories (`tests/AfterAll.ps1`)
148+
- Runs once after all test matrix jobs complete to clean up the test environment
149+
- Remove test resources, clean up databases, stop services, or upload artifacts
150+
- Has access to the same environment variables as your tests
151+
152+
##### Example - `AfterAll.ps1`
153+
154+
```powershell
155+
Write-Host "Cleaning up test environment..."
156+
# Remove test resources
157+
# Cleanup databases
158+
# Stop services
159+
Write-Host "Cleanup completed!"
160+
```
161+
162+
### Secrets
163+
164+
The following secrets are used by the workflow. They can be automatically provided (if available) by setting the `secrets: inherit`
165+
in the workflow file.
166+
167+
| Name | Location | Description | Default |
168+
| ---- | -------- | ----------- | ------- |
169+
| `APIKEY` | GitHub secrets | The API key for the PowerShell Gallery. | N/A |
170+
| `TEST_APP_ENT_CLIENT_ID` | GitHub secrets | The client ID of an Enterprise GitHub App for running tests. | N/A |
171+
| `TEST_APP_ENT_PRIVATE_KEY` | GitHub secrets | The private key of an Enterprise GitHub App for running tests. | N/A |
172+
| `TEST_APP_ORG_CLIENT_ID` | GitHub secrets | The client ID of an Organization GitHub App for running tests. | N/A |
173+
| `TEST_APP_ORG_PRIVATE_KEY` | GitHub secrets | The private key of an Organization GitHub App for running tests. | N/A |
174+
| `TEST_USER_ORG_FG_PAT` | GitHub secrets | The fine-grained personal access token with org access for running tests. | N/A |
175+
| `TEST_USER_USER_FG_PAT` | GitHub secrets | The fine-grained personal access token with user account access for running tests. | N/A |
176+
| `TEST_USER_PAT` | GitHub secrets | The classic personal access token for running tests. | N/A |
177+
178+
### Permissions
179+
180+
The following permissions are needed for the workflow to be able to perform all tasks.
181+
182+
```yaml
183+
permissions:
184+
contents: write # to checkout the repo and create releases on the repo
185+
pull-requests: write # to write comments to PRs
186+
statuses: write # to update the status of the workflow from linter
187+
pages: write # to deploy to Pages
188+
id-token: write # to verify the Pages deployment originates from an appropriate source
189+
```
190+
191+
For more info see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site).
192+
193+
### Scenario Matrix
194+
195+
This table shows when each job runs based on the trigger scenario:
196+
197+
| Job | Open/Updated PR | Merged PR | Abandoned PR | Manual Run |
198+
|-----|-----------------|-----------|--------------|------------|
199+
| **Get-Settings** | ✅ Always | ✅ Always | ✅ Always | ✅ Always |
200+
| **Lint-Repository** | ✅ Yes | ❌ No | ❌ No | ❌ No |
201+
| **Build-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
202+
| **Build-Docs** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
203+
| **Build-Site** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
204+
| **Test-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
205+
| **Lint-SourceCode** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
206+
| **Test-Module** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
207+
| **BeforeAll-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
208+
| **Test-ModuleLocal** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
209+
| **AfterAll-ModuleLocal** | ✅ Yes | ✅ Yes | ✅ Yes* | ✅ Yes |
210+
| **Get-TestResults** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
211+
| **Get-CodeCoverage** | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
212+
| **Publish-Site** | ❌ No | ✅ Yes | ❌ No | ❌ No |
213+
| **Publish-Module** | ✅ Yes** | ✅ Yes** | ✅ Yes*** | ✅ Yes** |
214+
215+
\* Runs for cleanup if tests were started
216+
\*\* Only when all tests/coverage/build succeed
217+
\*\*\* Publishes cleanup/retraction version
218+
133219
## Configuration
134220
135221
The workflow is configured using a settings file in the module repository.
@@ -279,103 +365,9 @@ Build:
279365
Skip: true
280366
```
281367

282-
## Usage
283-
284-
### Inputs
285-
286-
| Name | Type | Description | Required | Default |
287-
| ---- | ---- | ----------- | -------- | ------- |
288-
| `Name` | `string` | The name of the module to process. This defaults to the repository name if nothing is specified. | `false` | N/A |
289-
| `SettingsPath` | `string` | The path to the settings file. Settings in the settings file take precedence over the action inputs. | `false` | `.github/PSModule.yml` |
290-
| `Version` | `string` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | `false` | `''` |
291-
| `Prerelease` | `boolean` | Whether to use a prerelease version of the 'GitHub' module. | `false` | `false` |
292-
| `Debug` | `boolean` | Whether to enable debug output. Adds a `debug` step to every job. | `false` | `false` |
293-
| `Verbose` | `boolean` | Whether to enable verbose output. | `false` | `false` |
294-
| `WorkingDirectory` | `string` | The path to the root of the repo. | `false` | `.` |
295-
296-
### Setup and Teardown Scripts
297-
298-
The workflow supports automatic execution of setup and teardown scripts for module tests:
299-
300-
- Scripts are automatically detected and executed if present
301-
- If no scripts are found, the workflow continues normally
302-
303-
#### Setup - `BeforeAll.ps1`
304-
305-
- Place in your test directories (`tests/BeforeAll.ps1`)
306-
- Runs once before all test matrix jobs to prepare the test environment
307-
- Deploy test infrastructure, download test data, initialize databases, or configure services
308-
- Has access to the same environment variables as your tests (secrets, GitHub token, etc.)
309-
310-
##### Example - `BeforeAll.ps1`
311-
312-
```powershell
313-
Write-Host "Setting up test environment..."
314-
# Deploy test infrastructure
315-
# Download test data
316-
# Initialize test databases
317-
Write-Host "Test environment ready!"
318-
```
319-
320-
#### Teardown - `AfterAll.ps1`
321-
322-
- Place in your test directories (`tests/AfterAll.ps1`)
323-
- Runs once after all test matrix jobs complete to clean up the test environment
324-
- Remove test resources, clean up databases, stop services, or upload artifacts
325-
- Has access to the same environment variables as your tests
326-
327-
##### Example - `AfterAll.ps1`
328-
329-
```powershell
330-
Write-Host "Cleaning up test environment..."
331-
# Remove test resources
332-
# Cleanup databases
333-
# Stop services
334-
Write-Host "Cleanup completed!"
335-
```
336-
337-
### Secrets
338-
339-
The following secrets are used by the workflow. They can be automatically provided (if available) by setting the `secrets: inherit`
340-
in the workflow file.
341-
342-
| Name | Location | Description | Default |
343-
| ---- | -------- | ----------- | ------- |
344-
| `APIKEY` | GitHub secrets | The API key for the PowerShell Gallery. | N/A |
345-
| `TEST_APP_ENT_CLIENT_ID` | GitHub secrets | The client ID of an Enterprise GitHub App for running tests. | N/A |
346-
| `TEST_APP_ENT_PRIVATE_KEY` | GitHub secrets | The private key of an Enterprise GitHub App for running tests. | N/A |
347-
| `TEST_APP_ORG_CLIENT_ID` | GitHub secrets | The client ID of an Organization GitHub App for running tests. | N/A |
348-
| `TEST_APP_ORG_PRIVATE_KEY` | GitHub secrets | The private key of an Organization GitHub App for running tests. | N/A |
349-
| `TEST_USER_ORG_FG_PAT` | GitHub secrets | The fine-grained personal access token with org access for running tests. | N/A |
350-
| `TEST_USER_USER_FG_PAT` | GitHub secrets | The fine-grained personal access token with user account access for running tests. | N/A |
351-
| `TEST_USER_PAT` | GitHub secrets | The classic personal access token for running tests. | N/A |
352-
353-
## Permissions
354-
355-
If running the action in a restrictive mode, the following permissions need to be granted to the action:
356-
357-
```yaml
358-
permissions:
359-
contents: write # Create releases
360-
pull-requests: write # Create comments on the PRs
361-
statuses: write # Update the status of the PRs from the linter
362-
```
363-
364-
### Publishing to GitHub Pages
365-
366-
To publish the documentation to GitHub Pages, the action requires the following permissions:
367-
368-
```yaml
369-
permissions:
370-
pages: write # Deploy to Pages
371-
id-token: write # Verify the deployment originates from an appropriate source
372-
```
373-
374-
For more info see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site).
375-
376368
## Specifications and practices
377369

378-
Process-PSModule follows:
370+
The process is compatible with:
379371

380372
- [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) and [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
381373
- [GitHub Flow specifications](https://docs.github.com/en/get-started/using-github/github-flow)

0 commit comments

Comments
 (0)