Skip to content

Commit e7c128a

Browse files
MariusStorhaugMariusStorhaug
committed
Implement Resolve-PSModuleVersion action
1 parent 098d9a6 commit e7c128a

3 files changed

Lines changed: 391 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,82 @@
1-
# Template-Action
1+
# Resolve-PSModuleVersion
22

3-
A template repository for GitHub Actions
3+
A GitHub Action that resolves the next module version from settings, PR labels, GitHub releases, and the PowerShell Gallery.
4+
5+
This action is the single decision point for module versioning. It runs in the **Plan** phase of a workflow, before the module is
6+
built, so that `Build-PSModule` can stamp the resolved version into the manifest. The bytes that are tested are then the bytes
7+
that ship to the PowerShell Gallery and to GitHub Releases.
48

59
## Usage
610

11+
This action is consumed by [`PSModule/Process-PSModule`](https://github.com/PSModule/Process-PSModule) but can be used directly.
12+
It expects to run on a `pull_request` event and consumes the JSON `Settings` output from
13+
[`PSModule/Get-PSModuleSettings`](https://github.com/PSModule/Get-PSModuleSettings).
14+
715
### Inputs
816

9-
### Secrets
17+
| Name | Required | Default | Description |
18+
| ---- | -------- | ------- | ----------- |
19+
| `Settings` | yes | | The full settings object as a JSON string (output of `Get-PSModuleSettings`). |
20+
| `Name` | no | `${repository name}` | The module name. When empty, the repository name is used. |
21+
| `WorkingDirectory` | no | `.` | Working directory for the script. |
22+
| `Debug` | no | `false` | Enable debug output. |
23+
| `Verbose` | no | `false` | Enable verbose output. |
24+
| `Version` | no | | Pin a specific version of the GitHub helper module. |
25+
| `Prerelease` | no | `false` | Allow prerelease versions of the GitHub helper module. |
26+
27+
The action reads the following keys from `Settings.Publish.Module`:
28+
29+
- `ReleaseType` (`Release` / `Prerelease` / `None`)
30+
- `AutoPatching`
31+
- `IncrementalPrerelease`
32+
- `DatePrereleaseFormat`
33+
- `VersionPrefix`
34+
- `MajorLabels`, `MinorLabels`, `PatchLabels`, `IgnoreLabels` (comma-separated)
1035

1136
### Outputs
1237

38+
| Name | Description |
39+
| ---- | ----------- |
40+
| `Version` | The `Major.Minor.Patch` portion of the resolved version (for example `1.4.0`). |
41+
| `Prerelease` | The prerelease tag, empty when not a prerelease. |
42+
| `FullVersion` | The full version string including `VersionPrefix` and prerelease tag (for example `v1.4.0-mybranch001`). |
43+
| `ReleaseType` | The resolved release type. `Release`, `Prerelease`, or `None` when no version bump label is present. |
44+
| `CreateRelease` | `true` when a release or prerelease should actually be created from this run. |
45+
46+
### Permissions
47+
48+
The action needs `contents: read` (for `actions/checkout`) and `pull-requests: read` to read PR labels. The
49+
`GH_TOKEN` environment variable must be set so `gh release list` can query GitHub releases.
50+
1351
### Example
1452

1553
```yaml
16-
Example here
54+
- name: Resolve module version
55+
id: resolve
56+
uses: PSModule/Resolve-PSModuleVersion@v1
57+
env:
58+
GH_TOKEN: ${{ github.token }}
59+
with:
60+
Settings: ${{ steps.settings.outputs.Settings }}
61+
62+
- name: Build module
63+
uses: PSModule/Build-PSModule@v5
64+
with:
65+
Version: ${{ steps.resolve.outputs.Version }}
66+
Prerelease: ${{ steps.resolve.outputs.Prerelease }}
1767
```
68+
69+
## How it works
70+
71+
1. Loads the resolved `Settings` JSON and the `pull_request` event payload.
72+
2. Validates `ReleaseType` and applies `IgnoreLabels` overrides.
73+
3. Picks the bump type from PR labels: `MajorLabels` > `MinorLabels` > (`PatchLabels` or `AutoPatching`).
74+
4. Reads the latest version from GitHub Releases (`gh release list`) and the PowerShell Gallery (`Find-PSResource`),
75+
takes the higher of the two as the baseline.
76+
5. Bumps the baseline according to the resolved bump type.
77+
6. For prereleases, appends the sanitized branch name, optionally a `DatePrereleaseFormat` timestamp, and an
78+
incremental counter calculated from existing prereleases on the same baseline + branch.
79+
7. Emits `Version`, `Prerelease`, `FullVersion`, `ReleaseType`, and `CreateRelease` as step outputs.
80+
81+
When `ReleaseType` is `None`, when an `IgnoreLabels` label is present, or when no version bump label is found
82+
(and `AutoPatching` is disabled), `CreateRelease` is `false` and the version outputs are empty strings.

‎action.yml‎

Lines changed: 45 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
1-
name: Template-Action
2-
description: A template action for GitHub Actions using PowerShell
1+
name: Resolve-PSModuleVersion
2+
description: Resolves the next module version from settings, PR labels, GitHub releases, and the PowerShell Gallery.
33
author: PSModule
44
branding:
5-
icon: upload-cloud
5+
icon: tag
66
color: white
77

88
inputs:
9-
Subject:
10-
description: The subject to greet
9+
Settings:
10+
description: The complete settings object as a JSON string (output of Get-PSModuleSettings).
11+
required: true
12+
Name:
13+
description: Name of the module. When empty, the repository name is used.
1114
required: false
12-
default: World
15+
WorkingDirectory:
16+
description: The working directory where the script will run from.
17+
required: false
18+
default: '.'
1319
Debug:
1420
description: Enable debug output.
1521
required: false
@@ -22,26 +28,43 @@ inputs:
2228
description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
2329
required: false
2430
Prerelease:
25-
description: Allow prerelease versions if available.
31+
description: Allow prerelease versions of the GitHub module if available.
2632
required: false
2733
default: 'false'
28-
WorkingDirectory:
29-
description: The working directory where the script will run from.
30-
required: false
31-
default: ${{ github.workspace }}
34+
35+
outputs:
36+
Version:
37+
description: The Major.Minor.Patch portion of the resolved version.
38+
value: ${{ steps.resolve.outputs.Version }}
39+
Prerelease:
40+
description: The prerelease tag, empty when not a prerelease.
41+
value: ${{ steps.resolve.outputs.Prerelease }}
42+
FullVersion:
43+
description: The full version string including version prefix and prerelease tag (for example v1.4.0-alpha001).
44+
value: ${{ steps.resolve.outputs.FullVersion }}
45+
ReleaseType:
46+
description: The resolved release type - Release, Prerelease, or None.
47+
value: ${{ steps.resolve.outputs.ReleaseType }}
48+
CreateRelease:
49+
description: 'true when a release or prerelease should be created from this run.'
50+
value: ${{ steps.resolve.outputs.CreateRelease }}
3251

3352
runs:
3453
using: composite
3554
steps:
36-
- name: Template-Action
37-
uses: PSModule/GitHub-Script@0097f3bbe3f413f3b577b9bcc600727b0ca3201a # v1.7.10
55+
- name: Install-PSModuleHelpers
56+
uses: PSModule/Install-PSModuleHelpers@ed79b6e3aa8c9cd3d30ab2bf02ea6bd4687b9c74 # v1.0.7
57+
58+
- name: Install PSSemVer
59+
shell: pwsh
60+
run: |
61+
Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository
62+
63+
- name: Resolve module version
64+
id: resolve
65+
shell: pwsh
66+
working-directory: ${{ inputs.WorkingDirectory }}
3867
env:
39-
PSMOUDLE_TEMPLATE_ACTION_INPUT_Subject: ${{ inputs.Subject }}
40-
with:
41-
Name: Template-Action
42-
Debug: ${{ inputs.Debug }}
43-
Prerelease: ${{ inputs.Prerelease }}
44-
Verbose: ${{ inputs.Verbose }}
45-
Version: ${{ inputs.Version }}
46-
WorkingDirectory: ${{ inputs.WorkingDirectory }}
47-
Script: ${{ github.action_path }}/scripts/main.ps1
68+
PSMODULE_RESOLVE_PSMODULEVERSION_INPUT_Settings: ${{ inputs.Settings }}
69+
PSMODULE_RESOLVE_PSMODULEVERSION_INPUT_Name: ${{ inputs.Name }}
70+
run: ${{ github.action_path }}/scripts/main.ps1

0 commit comments

Comments
 (0)