|
1 | 1 | # Resolve-PSModuleVersion |
2 | 2 |
|
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. |
8 | | - |
9 | | -## Usage |
10 | | - |
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 | | - |
15 | | -### Inputs |
16 | | - |
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) |
35 | | - |
36 | | -### Outputs |
37 | | - |
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 | | - |
51 | | -### Example |
52 | | - |
53 | | -```yaml |
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 }} |
67 | | -``` |
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. |
| 3 | +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). |
0 commit comments