|
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 | | -| `WorkingDirectory` | The working directory where the script runs. | `'false'` | `'.'` | |
64 | | - |
65 | | -## Example |
66 | | - |
67 | | -```yaml |
68 | | -name: Publish-PSModule |
69 | | - |
70 | | -on: [pull_request] |
71 | | - |
72 | | -jobs: |
73 | | - Publish-PSModule: |
74 | | - name: Publish-PSModule |
75 | | - runs-on: ubuntu-latest |
76 | | - steps: |
77 | | - - name: Checkout repo |
78 | | - uses: actions/checkout@v4 |
79 | | - |
80 | | - - name: Initialize environment |
81 | | - uses: PSModule/Initialize-PSModule@main |
82 | | - |
83 | | - - name: Publish-PSModule |
84 | | - uses: PSModule/Publish-PSModule@main |
85 | | - env: |
86 | | - GITHUB_TOKEN: ${{ github.token }} |
87 | | - with: |
88 | | - APIKey: ${{ secrets.APIKEY }} |
89 | | -``` |
90 | | -
|
91 | | -## Permissions |
92 | | -
|
93 | | -The action requires the following permissions: |
94 | | -
|
95 | | -If running the action in a restrictive mode, the following permissions needs to be granted to the action: |
96 | | -
|
97 | | -```yaml |
98 | | -permissions: |
99 | | - contents: write # Required to create releases |
100 | | - pull-requests: write # Required to create comments on the PRs |
101 | | -``` |
| 3 | +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). |
0 commit comments