{"id":21698606,"url":"https://github.com/theohbrothers/psmodulepublisher","last_synced_at":"2026-01-28T01:05:59.174Z","repository":{"id":48716041,"uuid":"212001839","full_name":"theohbrothers/PSModulePublisher","owner":"theohbrothers","description":"A project containing the necessary tools to ease publishing of PowerShell modules.","archived":false,"fork":false,"pushed_at":"2024-09-07T17:48:47.000Z","size":377,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-12T12:49:53.797Z","etag":null,"topics":["azure-pipelines","ci-templates","package-management","powershell","powershell-module","psgallery","submodule"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theohbrothers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-01T02:58:27.000Z","updated_at":"2024-09-07T17:48:51.000Z","dependencies_parsed_at":"2024-04-30T06:56:37.324Z","dependency_job_id":"7b279e76-9974-4f66-921b-1115f983c6bd","html_url":"https://github.com/theohbrothers/PSModulePublisher","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/theohbrothers/PSModulePublisher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theohbrothers%2FPSModulePublisher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theohbrothers%2FPSModulePublisher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theohbrothers%2FPSModulePublisher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theohbrothers%2FPSModulePublisher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theohbrothers","download_url":"https://codeload.github.com/theohbrothers/PSModulePublisher/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theohbrothers%2FPSModulePublisher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28831207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T23:29:49.665Z","status":"ssl_error","status_checked_at":"2026-01-27T23:25:58.379Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-pipelines","ci-templates","package-management","powershell","powershell-module","psgallery","submodule"],"created_at":"2024-11-25T19:35:27.046Z","updated_at":"2026-01-28T01:05:59.147Z","avatar_url":"https://github.com/theohbrothers.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PSModulePublisher\n\n[![github-workflows](https://img.shields.io/github/actions/workflow/status/theohbrothers/PSModulePublisher/ci-master-pr.yml?label=ci-master-pr\u0026logo=github\u0026style=flat-square)](https://github.com/theohbrothers/PSModulePublisher/actions/workflows/ci-master-pr.yml)\n[![github-release](https://img.shields.io/github/v/release/theohbrothers/PSModulePublisher?style=flat-square)](https://github.com/theohbrothers/PSModulePublisher/releases)\n[![powershellgallery-version](https://img.shields.io/powershellgallery/v/PSModulePublisher?logo=powershell\u0026logoColor=white\u0026label=PSGallery\u0026style=flat-square)](https://www.powershellgallery.com/packages/PSModulePublisher)\n\nA project containing the necessary tools to ease publishing of PowerShell modules.\n\n## Introduction\n\nThis project provides PowerShell cmdlets and CI remote templates that other projects can utilize for building, testing, and publishing PowerShell modules.\n\n## Directory structure\n\n`PSModulePublisher` sets the following convention of directory structure for PowerShell projects to adopt for building, testing, and publishing PowerShell modules.\n\n```shell\n/build/                                             # Build directory\n/build/PSModulePublisher/                           # PSModulePublisher as a submodule [optional]\n/build/definitions/modulemanifest.ps1               # The module manifest definition file\n\n/src/MyPowershellModule/                            # The module's root directory\n/src/MyPowershellModule/MyPowershellModule.psm1     # The script module file (.psm1)\n/src/MyPowershellModule/MyPowershellModule.psd1     # The module manifest file (.psd1) [optional]\n\n/test/                                              # Test directory [optional]\n/test/test.ps1                                      # The test entrypoint script [optional]\n```\n\n## Installation\n\n`PSModulePublisher` can either be installed as a [PowerShell module](#powershell-module), or used as a [submodule](#submodule) with provided CI remote templates.\n\n### PowerShell module\n\nTo use `PSModulePublisher` as a PowerShell module, simply perform an installation of the module in development or CI environment(s) prior to executing provided [cmdlets](#usage) to perform their respective functions.\n\n```powershell\n# Latest version\nInstall-Module -Name PSModulePublisher -Repository PSGallery -Scope CurrentUser -Verbose\n\n# Specific version\nInstall-Module -Name PSModulePublisher -Repository PSGallery -RequiredVersion x.x.x -Scope CurrentUser -Verbose\n```\n\nIf prompted to trust the repository, type `Y` and `enter`.\n\n### Submodule\n\n`PSModulePublisher` can be used as submodule together with provided [CI remote template(s)](#ci-remote-templates).\n\n#### Adding the submodule\n\nAdd `PSModulePublisher` as a submodule under the directory `build` in your main project:\n\n```shell\n# Add the submodule\ngit submodule add https://github.com/theohbrothers/PSModulePublisher.git build/PSModulePublisher\n\n# Checkout ref to use\ngit --git-dir build/PSModulePublisher/.git checkout vx.x.x\n\n# Commit the submodule\ngit commit -am 'Add submodule PSModulePublisher vx.x.x'\n```\n\n## Configuration\n\n### Script module file\n\nEnsure the main project contains the script module file at the location `src/MyPowershellModule/MyPowershellModule.psm1`.\n\n### Module manifest definition file\n\nThe project sources from a definition file to generate the module manifest file (`.psd1`) used for publishing the module. Ensure that the file exists in your main project at the location `build/definitions/modulemanifest.ps1` and that it contains the right properties and values relevant to your PowerShell module. Remember to update the definition file prior to publishing your module.\n\nThe definition template can be found [here](docs/samples/build/definitions/modulemanifest.ps1).\n\n### CI remote templates\n\n**Note:** This section only applies if using the project as a [submodule](#submodule).\n\nDecide on which CI provider to use in your main project based on those supported by this project. Then setup the CI file(s) for your main project, referencing relevant [CI remote template(s)](templates) of this project from your main project's CI file(s).\n\nSample CI files can be found [here](docs/samples/ci).\n\n### Test files (Optional)\n\nThe project optionally runs an entrypoint script for tests at the location `test/test.ps1`. You can add the module's main tests steps in this file for tests to be run.\n\nSample test files can be found [here](docs/samples/test).\n\n### CI settings\n\n#### Secrets\n\n##### PSGallery API Key\n\nAdd a secret variable `NUGET_API_KEY` containing your [PSGallery API key](https://learn.microsoft.com/en-us/powershell/gallery/how-to/publishing-packages/publishing-a-package#powershell-gallery-account-and-api-key) to your main project's CI settings for publishing your module on [PowerShell Gallery](https://www.powershellgallery.com/).\n\n#### Environment variables\n\n##### Project directory\n\nBy default, `PSModulePublisher` uses the main project's root directory as the path for execution. To override the default location, set the *environment* variable `PROJECT_DIRECTORY` to contain a custom directory value before executing `PSModulePublisher`.\n\n##### Module version\n\nThe default module version is `0.0.0` which prevents a module from being published. To publish a module, simply create a tag for a desired commit and push the tag. Tags must follow [Semantic Versioning](https://semver.org/) and be prepended with a lowercase `v`:\n\n```shell\n# Tag the commit to publish\ngit tag v1.0.12\n\n# Push the tag\ngit push remotename v1.0.12     # MODULE_VERSION will be 1.0.12\n```\n\nThe environment variable `MODULE_VERSION` will automatically be populated with the equivalent PowerShell module version based on the semver tag pushed.\n\n## Usage\n\n### Development\n\nThe PowerShell cmdlet [`Invoke-PSModulePublisher`](src/PSModulePublisher/Public/Invoke-PSModulePublisher.ps1) is used for executing the project's build, test, and publish steps for PowerShell modules.\n\n#### Parameters\n\n```powershell\nInvoke-PSModulePublisher [[-Repository] \u003cstring\u003e] [-DryRun] [\u003cCommonParameters\u003e]\n```\n\n#### Commands\n\nTo perform the project's build, test, and publish steps for a given Powershell module, simply define applicable [environment variables](#environment-variables-1) for the project before executing the cmdlet.\n\n```powershell\n# Process applicable environment variables\n$env:PROJECT_DIRECTORY = git rev-parse --show-toplevel\n\n# Build and Test steps (Generates module manifest, Tests module via module manifest)\nInvoke-PSModulePublisher\n\n# Publish steps (Publishes module as a dry run)\nInvoke-PSModulePublisher -Repository MyPSRepository -DryRun\n\n# Publish steps (Publishes module)\nInvoke-PSModulePublisher -Repository MyPSRepository\n```\n\n**Note:** Ensure the environment variable [`NUGET_API_KEY`](#psgallery-api-key) is defined prior to publishing PowerShell modules.\n\nThe [individual cmdlets](#via-cmdlets) may also be used for executing the project's build, test, and publish steps independently.\n\n#### VSCode\n\nThe project includes [samples](docs/samples/.vscode) of `.vscode/tasks.json` for executing build, test, and publish steps with the included cmdlets via [*Build Tasks*](https://code.visualstudio.com/docs/editor/tasks) in [VSCode](https://code.visualstudio.com/). Simply execute relevant build task(s) while entering custom or default values per variable prompt.\n\n### Continuous Integration (CI)\n\nThe project provides PowerShell [cmdlets](#via-cmdlets), as well as [CI remote templates](#via-submodule-and-ci-remote-templates) for executing the project's build, test, and publish steps for PowerShell modules.\n\n#### via Cmdlets\n\nThe following are the [parameters](#parameters) and [environment variables](#environment-variables-1) supported by the provided PowerShell cmdlets for building, testing, and publishing PowerShell modules.\n\n##### Parameters\n\n```powershell\nInvoke-Build [\u003cCommonParameters\u003e]\nInvoke-Test [[-ModuleManifestPath] \u003cstring\u003e] [\u003cCommonParameters\u003e]\nInvoke-Publish [[-ModuleManifestPath] \u003cstring\u003e] [-Repository] \u003cstring\u003e [-DryRun] [\u003cCommonParameters\u003e]\n```\n\n##### Environment variables\n\n###### Build, Test, Publish\n\n| Name | Example value | Mandatory | Type |\n|:-:|:-:|:-:|:-:|\n| [`PROJECT_DIRECTORY`](#project-directory) | `/path/to/my-project` | false | string |\n| [`MODULE_VERSION`](#module-version) | `x.x.x` | false, true (Build + Publish) | string |\n\n###### Publish\n\n| Name | Example value | Mandatory | Type |\n|:-:|:-:|:-:|:-:|\n| [`NUGET_API_KEY`](#psgallery-api-key) | `xxx` | true | string |\n\n##### Commands\n\nTo execute build, test, and publish steps for a project, simply define applicable [environment variables](#environment-variables-1) before executing the individual cmdlets within the CI environment to perform their respective functions.\n\n```shell\n# Process applicable environment variables\nexport PROJECT_DIRECTORY=$( git rev-parse --show-toplevel )\nexport MODULE_VERSION=$( echo \"$GITHUB_REF\" | sed -rn 's/^refs\\/tags\\/v(.*)/\\1/p' )\n\n# Install PSModulePublisher\npwsh -NoLogo -NonInteractive -NoProfile -Command 'Install-Module -Name PSModulePublisher -Repository PSGallery -Scope CurrentUser -Force -Verbose'\n\n# Build (Generates module manifest)\npwsh -NoLogo -NonInteractive -NoProfile -Command '$VerbosePreference = \"Continue\"; Invoke-Build'\n\n# Test (Tests module via module manifest)\npwsh -NoLogo -NonInteractive -NoProfile -Command '$VerbosePreference = \"Continue\"; Invoke-Test'\n\n# Publish (Publishes module)\npwsh -NoLogo -NonInteractive -NoProfile -Command '$VerbosePreference = \"Continue\"; Invoke-Publish -Repository PSGallery'\n```\n\n**Note:** Ensure the environment variable [`NUGET_API_KEY`](#psgallery-api-key) is defined prior to publishing PowerShell modules.\n\nSample CI files demonstrating use of this approach can be found [here](docs/samples/ci/github).\n\n#### via Submodule and CI remote templates\n\nThe provided [CI remote templates](templates) is composed of the following CI process:\n\n##### Build\n\n1. Display system info\n2. Get PowerShell version\n3. Process build variables\n4. Generate module manifest\n\n##### Test\n\n1. Test module via module's manifest\n\n##### Publish\n\n1. Install publish dependencies *(if applicable)*\n1. Publish module\n\n**Build**, **Test**, and **Publish** steps can be executed for all refs. Simply [configure](docs/samples/ci/azure-pipelines/azure-pipelines.linux.yml#L8-L11) your main project's CI file(s) and/or settings to allow so.\n\n**Publish** steps default to simulating publishing of the module. The module is published only for *tag* refs. Simply [configure](docs/samples/ci/azure-pipelines/azure-pipelines.linux.yml#L5-L11) your main project's CI file(s) and/or settings to allow so.\n\n##### Use cases\n\nFor a basic use case, the CI process could simply comprise a single stage containing all the steps from **Build**, **Test**, and **Publish**.\n\nIn cases where the module needs to be tested across multiple operating systems and/or versions of PowerShell, two stages can be configured: The 1st stage containing *multiple jobs* executing [**Build** and **Test** steps](docs/samples/ci/azure-pipelines/azure-pipelines.linux-windows.yml#L24-L40) for building and testing the module; the 2nd stage containing a *single* job executing [**Build** and **Publish** steps](docs/samples/ci/azure-pipelines/azure-pipelines.linux-windows.yml#L52) for publishing the module.\n\nSample CI files demonstrating use of this approach can be found [here](docs/samples/ci/azure-pipelines).\n\n## Maintenance\n\n### Submodule\n\n#### Using a specific tag\n\n```shell\n# Update the submodule\ngit submodule update --remote build/PSModulePublisher\n\n# Checkout ref to use\ngit --git-dir build/PSModulePublisher/.git checkout vx.x.x\n\n# Bump PSModulePublisher to the same ref in CI file\nvi azure-pipelines.yml\n\n# Commit the submodule and CI file\ngit commit -am 'Bump PSModulePublisher to vx.x.x'\n```\n\n## Best practices\n\n- Use only tag refs of `PSModulePublisher` in your main project.\n- If using the project as a [Submodule with CI remote templates](#submodule), ensure your main project's CI file(s) is configured to use the [CI remote templates](docs/samples/ci/azure-pipelines/azure-pipelines.linux-container.yml#L15-#L19) of `PSModulePublisher`, and that the ref matches that of the `PSModulePublisher` submodule used in your main project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheohbrothers%2Fpsmodulepublisher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheohbrothers%2Fpsmodulepublisher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheohbrothers%2Fpsmodulepublisher/lists"}