|
1 | 1 | # Publish-PSModule |
2 | 2 |
|
3 | | -Creates a GitHub release and publishes the PowerShell module to the PowerShell Gallery. |
4 | | - |
5 | | -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the [Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. |
6 | | - |
7 | | -## Specifications and practices |
8 | | - |
9 | | -Publish-PSModule follows: |
10 | | - |
11 | | -- [SemVer 2.0.0 specifications](https://semver.org) |
12 | | -- [GitHub Flow specifications](https://docs.github.com/en/get-started/using-github/github-flow) |
13 | | -- [Continiuous Delivery practices](https://en.wikipedia.org/wiki/Continuous_delivery) |
14 | | - |
15 | | -... and supports the following practices in the PSModule framework: |
16 | | - |
17 | | -- [PowerShell publishing guidelines](https://learn.microsoft.com/en-us/powershell/gallery/concepts/publishing-guidelines?view=powershellget-3.x) |
18 | | - |
19 | | -## How it works |
20 | | - |
21 | | -The workflow will trigger on pull requests to the repositorys default branch. |
22 | | -When the pull request is opened, the action will decide what to do based on labels on the pull request. |
23 | | - |
24 | | -It will get the latest release version by looking up the versions in GitHub releases, PowerShell Gallery and the module manifest. |
25 | | -The next version is then determined by the labels on the pull request. If a prerelease label is found, the action will create a |
26 | | -prerelease with the branch name (in normalized form) as the prerelease name. By defualt, the following labels are used: |
27 | | - |
28 | | -- For a major release, and increasing the first number in the version use: |
29 | | - - `major` |
30 | | - - `breaking` |
31 | | -- For a minor release, and increasing the second number in the version. |
32 | | - - `minor` |
33 | | - - `feature` |
34 | | -- For a patch release, and increases the third number in the version. |
35 | | - - `patch` |
36 | | - - `fix` |
37 | | - |
38 | | -The types of labels used for the types of prereleases can be configured using the `MajorLabels`, `MinorLabels` and `PatchLabels` |
39 | | -parameters/settings. See the [Usage](#usage) section for more information. |
40 | | - |
41 | | -When a pull request is merged into the default branch, the action will create a release based on the labels and clean up any previous |
42 | | -prereleases that was created. |
43 | | - |
44 | | -## Usage |
45 | | - |
46 | | -The action can be configured using the following settings: |
47 | | - |
48 | | -| Name | Description | Required | Default | |
49 | | -| --- | --- | --- | --- | |
50 | | -| `Name` | Name of the module to publish. Defaults to the repository name. | `false` | | |
51 | | -| `ModulePath` | Path to the folder where the module to publish is located. | `false` | `outputs/modules` | |
52 | | -| `APIKey` | PowerShell Gallery API Key. | `true` | | |
53 | | -| `AutoCleanup`| Control wether to automatically cleanup prereleases. If disabled, the action will not remove any prereleases. | `false` | `true` | |
54 | | -| `AutoPatching` | Control wether to automatically handle patches. If disabled, the action will only create a patch release if the pull request has a 'patch' label. | `false` | `true` | |
55 | | -| `DatePrereleaseFormat` | The format to use for the prerelease number using [.NET DateTime format strings](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings). | `false` | `''` | |
56 | | -| `IncrementalPrerelease` | Control wether to automatically increment the prerelease number. If disabled, the action will ensure only one prerelease exists for a given branch. | `false` | `true` | |
57 | | -| `VersionPrefix` | The prefix to use for the version number. | `false` | `v` | |
58 | | -| `MajorLabels` | A comma separated list of labels that trigger a major release. | `false` | `major, breaking` | |
59 | | -| `MinorLabels` | A comma separated list of labels that trigger a minor release. | `false` | `minor, feature` | |
60 | | -| `PatchLabels` | A comma separated list of labels that trigger a patch release. | `false` | `patch, fix` | |
61 | | -| `IgnoreLabels` | A comma separated list of labels that do not trigger a release. | `false` | `NoRelease` | |
62 | | -| `WhatIf` | Control wether to simulate the action. If enabled, the action will not create any releases. Used for testing. | `false` | `false` | |
63 | | -| `Debug` | Enable debug output. | `'false'` | `false` | |
64 | | -| `Verbose` | Enable verbose output. | `'false'` | `false` | |
65 | | -| `Version` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | | `false` | |
66 | | -| `Prerelease` | Allow prerelease versions if available. | `'false'` | `false` | |
67 | | -| `WorkingDirectory` | The working directory where the script runs. | `'false'` | `'.'` | |
68 | | -| `UsePRTitleAsReleaseName` | When enabled, uses the pull request title as the name for the GitHub release. If not set or the PR has no title, the version string is used. | `false` | false | |
69 | | -| `UsePRBodyAsReleaseNotes` | When enabled, uses the pull request body as the release notes for the GitHub release. If not set or the PR has no body, the release notes are auto-generated. | `true` | false | |
70 | | -| `UsePRTitleAsNotesHeading` | When enabled, the release notes will begin with the pull request title as a H1 heading followed by the pull request body, including a reference to the PR number. | `true` | false | |
71 | | - |
72 | | -## Release Title and Notes Logic |
73 | | - |
74 | | -- If `UsePRTitleAsReleaseName` is enabled and the pull request has a title, the release name will be set to the PR title. Otherwise, it defaults to the version string. |
75 | | -- If `UsePRTitleAsNotesHeading` is enabled and the PR has both a title and body, the release notes will start with the PR title as a heading (with PR number), followed by the PR body. |
76 | | -- If only `UsePRBodyAsReleaseNotes` is enabled and the PR has a body, the release notes will use the PR body. |
77 | | -- If neither is enabled or the PR has no body, the release notes are auto-generated (`--generate-notes`). |
78 | | -- The GitHub CLI command for creating the release is constructed stepwise, with `--title`, `--notes` (if provided), and `--generate-notes` as a fallback, matching the logic from Auto-Release. |
79 | | - |
80 | | -The action outputs the calculated release name and body in the logs for visibility and testing. |
81 | | - |
82 | | -## Example |
83 | | - |
84 | | -```yaml |
85 | | -name: Publish-PSModule |
86 | | - |
87 | | -on: [pull_request] |
88 | | - |
89 | | -jobs: |
90 | | - Publish-PSModule: |
91 | | - name: Publish-PSModule |
92 | | - runs-on: ubuntu-latest |
93 | | - steps: |
94 | | - - name: Checkout repo |
95 | | - uses: actions/checkout@v4 |
96 | | - |
97 | | - - name: Initialize environment |
98 | | - uses: PSModule/Initialize-PSModule@main |
99 | | - |
100 | | - - name: Publish-PSModule |
101 | | - uses: PSModule/Publish-PSModule@main |
102 | | - env: |
103 | | - GITHUB_TOKEN: ${{ github.token }} |
104 | | - with: |
105 | | - APIKey: ${{ secrets.APIKEY }} |
106 | | -``` |
107 | | -
|
108 | | -## Permissions |
109 | | -
|
110 | | -The action requires the following permissions: |
111 | | -
|
112 | | -If running the action in a restrictive mode, the following permissions needs to be granted to the action: |
113 | | -
|
114 | | -```yaml |
115 | | -permissions: |
116 | | - contents: write # Required to create releases |
117 | | - pull-requests: write # Required to create comments on the PRs |
118 | | -``` |
| 3 | +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). |
0 commit comments