diff --git a/CHANGELOG.md b/CHANGELOG.md index df8f316..aedc187 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added reusable Sampler tasks for packaging and deploying PowerShell Universal modules. - Added task-file alias exports compatible with `ModuleBuildTasks` in Sampler repositories. +- Added WikiSource documentation and DscResource.DocGenerator build and publish workflows. ### Changed diff --git a/README.md b/README.md index 5a99334..294516d 100644 --- a/README.md +++ b/README.md @@ -22,3 +22,8 @@ The module provides tasks to: Configure the server under `UniversalServer` in `build.yaml`. Supply `UniversalServerAppToken` through the build environment or a local secrets file; do not commit tokens. + +## Documentation + +See the [GitHub wiki](https://github.com/SynEdgy/Sampler.PowerShellUniversalTasks/wiki) +for installation, configuration, and task reference documentation. diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index 5c3024f..863732b 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -25,5 +25,5 @@ 'DscResource.AnalyzerRules' = 'latest' xDscResourceDesigner = 'latest' 'DscResource.DocGenerator' = 'latest' + PlatyPS = 'latest' } - diff --git a/build.yaml b/build.yaml index 3749760..2928cf3 100644 --- a/build.yaml +++ b/build.yaml @@ -56,10 +56,19 @@ BuildWorkflow: - Build_NestedModules_ModuleBuilder - Create_changelog_release_output + docs: + - Create_Wiki_Output_Folder + - Generate_Markdown_For_Public_Commands + - Generate_External_Help_File_For_Public_Commands + - Clean_Markdown_Of_Public_Commands + - Copy_Source_Wiki_Folder + - Generate_Wiki_Sidebar + - Clean_Markdown_Metadata + - Package_Wiki_Content pack: - build - + - docs - package_module_nupkg hqrmtest: @@ -83,6 +92,7 @@ BuildWorkflow: publish: - Publish_Release_To_GitHub # Runs first, if token is expired it will fail early - publish_module_to_gallery + - Publish_GitHub_Wiki_Content #################################################### # PESTER Configuration # @@ -177,6 +187,8 @@ ModuleBuildTasks: - '*.ib.tasks' DscResource.Test: - 'Task.*' + DscResource.DocGenerator: + - 'Task.*' # Invoke-Build Header to be used to 'decorate' the terminal output of the tasks. @@ -203,10 +215,23 @@ GitConfig: GitHubConfig: GitHubFilesToAdd: - CHANGELOG.md + ReleaseAssets: + - output/CHANGELOG.md + - output/WikiContent.zip GitHubConfigUserName: github-actions[bot] GitHubConfigUserEmail: 41898282+github-actions[bot]@users.noreply.github.com UpdateChangelogOnPrerelease: false +#################################################### +# DscResource.DocGenerator Configuration # +#################################################### +DscResource.DocGenerator: + Publish_GitHub_Wiki_Content: + Debug: false + Generate_Wiki_Sidebar: + Debug: false + AlwaysOverwrite: true + #################################################### # Changelog Configuration # #################################################### diff --git a/source/WikiSource/Configuration.md b/source/WikiSource/Configuration.md new file mode 100644 index 0000000..1e50335 --- /dev/null +++ b/source/WikiSource/Configuration.md @@ -0,0 +1,83 @@ +# Configuration + +The tasks resolve explicit task parameters first, then values from the +`UniversalServer` section of `build.yaml`. Server URL and token values can also +come from build environment variables. + +## UniversalServer settings + +```yaml +UniversalServer: + UniversalServerUrl: https://psu.example.test + UniversalPSResourceRepositoryName: output + UniversalPSResourceRepositoryUrl: ./output/ + UniversalPSResourceRepositoryAutoRemove: true + UniversalRepositoryStagingDirectoryName: PsuRepository + UniversalRepositoryZipName: + UniversalRepositoryAsModule: false + UniversalUnpinned: true +``` + +| Setting | Default | Description | +|---|---|---| +| `UniversalServerUrl` | None | Base URL of the PowerShell Universal server. | +| `UniversalServerAppToken` | None | Application token. Prefer an environment variable or `secrets.local.ps1` instead of committing it. | +| `UniversalPSResourceRepositoryName` | `output` | Resource repository name used for module installation. | +| `UniversalPSResourceRepositoryUrl` | `./output/` | Repository URL or local path. Relative paths resolve from the consumer repository root. | +| `UniversalPSResourceRepositoryAutoRemove` | `true` | Remove the resource repository after the installation attempt. | +| `UniversalRepositoryStagingDirectoryName` | `PsuRepository` | Staging directory created below the build output directory. | +| `UniversalRepositoryZipName` | `..zip` | Optional explicit offline repository package name. | +| `UniversalRepositoryAsModule` | `false` | Value sent to the deployment endpoint's `asModule` query parameter. | +| `UniversalUnpinned` | `true` | Value sent to the deployment endpoint's `unpinned` query parameter. | + +## Authentication + +The deployment tasks require `UniversalServerAppToken`. In CI, map a secret to +the environment variable: + +```yaml +env: + UniversalServerAppToken: ${{ secrets.UniversalServerAppToken }} +``` + +For local development, use the ignored `secrets.local.ps1` file: + +```powershell +$UniversalServerAppToken = '' +``` + +The token is used only by build and deployment tasks. It is not intended for +PowerShell Universal runtime scripts, apps, or dashboard endpoints. + +## PowerShell resource repository deployment + +`publish_module_from_psresource_repos_to_universal_server` queries the server +for `UniversalPSResourceRepositoryName`. + +- A matching trusted repository is reused. +- A differing repository is removed and recreated when + `UniversalPSResourceRepositoryAutoRemove` is `true`. +- A missing repository is created. +- The module is installed synchronously from that repository. +- The repository is removed after deployment when auto-remove is enabled. + +## Offline automation repository layout + +`package_universal_automation_repository` creates: + +```text +PsuRepository/ +|-- repository.psd1 +`-- Modules/ + |-- MyModule/ + | `-- 1.0.0/ + `-- MyDependency/ + `-- 2.0.0/ +``` + +The zip contains the project module and recursively resolved `RequiredModules` +dependencies. `repository.psd1` identifies the project module that PowerShell +Universal should load from the `Modules` directory. + +Keep `UniversalRepositoryAsModule` set to `false` for this full repository +layout. diff --git a/source/WikiSource/Getting-Started.md b/source/WikiSource/Getting-Started.md new file mode 100644 index 0000000..4b6b9e7 --- /dev/null +++ b/source/WikiSource/Getting-Started.md @@ -0,0 +1,105 @@ +# Getting Started + +## Prerequisites + +- A PowerShell module repository based on Sampler. +- PowerShell 7 or Windows PowerShell 5.1. +- Access to a PowerShell Universal server for deployment tasks. +- A PowerShell Universal application token for authenticated deployments. + +## Install the task module + +Add the module to the consumer repository's `RequiredModules.psd1`: + +```powershell +@{ + Sampler.PowerShellUniversalTasks = 'latest' +} +``` + +For released versions, the module can also be installed directly: + +```powershell +Install-PSResource -Name Sampler.PowerShellUniversalTasks +``` + +## Import the task file + +Add the module to `ModuleBuildTasks` in the consumer repository's `build.yaml`: + +```yaml +ModuleBuildTasks: + Sampler.PowerShellUniversalTasks: + - 'Task.*' +``` + +Sampler imports the module and dot-sources the task file through the exported +`Task.Publish_PowerShellUniversal` alias. + +## Configure the server + +Add a `UniversalServer` section: + +```yaml +UniversalServer: + UniversalServerUrl: https://psu.example.test + UniversalPSResourceRepositoryName: output + UniversalPSResourceRepositoryUrl: ./output/ + UniversalPSResourceRepositoryAutoRemove: true + UniversalRepositoryStagingDirectoryName: PsuRepository + UniversalRepositoryAsModule: false + UniversalUnpinned: true +``` + +Do not store `UniversalServerAppToken` in `build.yaml`. Supply it as an +environment variable in CI: + +```powershell +$env:UniversalServerAppToken = '' +``` + +For local development, the tasks also dot-source `secrets.local.ps1` from the +consumer repository root when that ignored file exists: + +```powershell +$UniversalServerAppToken = '' +``` + +## Add workflows + +Package and deploy the module directly: + +```yaml +BuildWorkflow: + pack: + - build + - package_module_nupkg + + deploy: + - pack + - publish_packed_module_to_universal_server +``` + +Package and deploy a complete offline automation repository: + +```yaml +BuildWorkflow: + pack: + - build + - package_module_nupkg + - package_universal_automation_repository + + deploy_repository: + - pack + - publish_universal_automation_repository_to_server +``` + +Run workflows through the Sampler entry point: + +```powershell +./build.ps1 -Tasks pack +./build.ps1 -Tasks deploy_repository +``` + +Review [Configuration](Configuration.md) before deployment and +[Task Reference](Task-Reference.md) for task prerequisites and output details. diff --git a/source/WikiSource/Home.md b/source/WikiSource/Home.md new file mode 100644 index 0000000..f0a9abe --- /dev/null +++ b/source/WikiSource/Home.md @@ -0,0 +1,38 @@ +# Sampler.PowerShellUniversalTasks + +*Sampler.PowerShellUniversalTasks v#.#.#* + +`Sampler.PowerShellUniversalTasks` provides reusable Sampler and InvokeBuild tasks +for packaging and deploying PowerShell modules to PowerShell Universal. + +## Start here + +- [Getting Started](Getting-Started.md) - install the module, import its task file, and add tasks + to a Sampler workflow. +- [Configuration](Configuration.md) - configure the PowerShell Universal server, resource + repository, offline repository package, and deployment behavior. +- [Task Reference](Task-Reference.md) - prerequisites, behavior, and outputs for every exported + InvokeBuild task. + +## Available tasks + +| Task | Purpose | +|---|---| +| `publish_packed_module_to_universal_server` | Upload a packed module directly to the PowerShell Universal module deployment endpoint. | +| `publish_module_from_psresource_repos_to_universal_server` | Register or reconcile a PowerShell resource repository and install the module from it. | +| `package_universal_automation_repository` | Package the built module and its dependencies as an offline automation repository. | +| `publish_universal_automation_repository_to_server` | Upload and activate an offline automation repository package. | + +## Task discovery + +The module exports the `Task.Publish_PowerShellUniversal` alias. Sampler loads +the task file through `ModuleBuildTasks`: + +```yaml +ModuleBuildTasks: + Sampler.PowerShellUniversalTasks: + - 'Task.*' +``` + +Generated command pages and `_Sidebar.md` are rebuilt from `build.yaml`. Keep +hand-authored wiki content in `source/WikiSource`. diff --git a/source/WikiSource/Task-Reference.md b/source/WikiSource/Task-Reference.md new file mode 100644 index 0000000..12def71 --- /dev/null +++ b/source/WikiSource/Task-Reference.md @@ -0,0 +1,134 @@ +# Task Reference + +The exported alias `Task.Publish_PowerShellUniversal` loads one InvokeBuild task +file containing the tasks documented on this page. + +## Contents + +- [publish_packed_module_to_universal_server](#publish_packed_module_to_universal_server) +- [publish_module_from_psresource_repos_to_universal_server](#publish_module_from_psresource_repos_to_universal_server) +- [package_universal_automation_repository](#package_universal_automation_repository) +- [publish_universal_automation_repository_to_server](#publish_universal_automation_repository_to_server) +- [Common parameters](#common-parameters) + +## publish_packed_module_to_universal_server + +Uploads the module NuGet package directly to the PowerShell Universal module +deployment endpoint. + +### Prerequisites + +- The module has been built and packed. +- `/..nupkg` exists. +- `UniversalServerUrl` and `UniversalServerAppToken` are available. + +### Typical workflow + +```yaml +BuildWorkflow: + deploy: + - pack + - publish_packed_module_to_universal_server +``` + +The deployment is synchronous and targets the `output` PowerShell resource +repository on the server. + +## publish_module_from_psresource_repos_to_universal_server + +Installs the built module from a PowerShell resource repository configured on +the PowerShell Universal server. + +### Behavior + +1. Resolve the configured repository URL. +1. Create a local repository directory when the URL is a relative or absolute + filesystem path. +1. Query the server for the configured repository name. +1. Create or reconcile the repository. +1. Trigger a synchronous module installation. +1. Remove the repository when auto-remove is enabled. + +### Typical workflow + +```yaml +BuildWorkflow: + deploy: + - pack + - publish_module_from_psresource_repos_to_universal_server +``` + +## package_universal_automation_repository + +Creates an offline PowerShell Universal automation repository zip containing +the built module and all recursively resolved `RequiredModules`. + +### Prerequisites + +- The module build has completed. +- The built module manifest is available. +- Every required module can be resolved from `PSModulePath`. + +### Outputs + +- Staging directory: + `/` +- Zip package: + `/..zip`, unless + `UniversalRepositoryZipName` overrides it. + +### Typical workflow + +```yaml +BuildWorkflow: + pack: + - build + - package_module_nupkg + - package_universal_automation_repository +``` + +The package includes a top-level `repository.psd1` and versioned module folders +under `Modules`. + +## publish_universal_automation_repository_to_server + +Uploads the offline automation repository zip to the PowerShell Universal +deployment endpoint. + +### Prerequisites + +- `package_universal_automation_repository` has created the zip package. +- `UniversalServerUrl` and `UniversalServerAppToken` are available. + +### Typical workflow + +```yaml +BuildWorkflow: + deploy_repository: + - pack + - publish_universal_automation_repository_to_server +``` + +The task sends `UniversalRepositoryAsModule` and `UniversalUnpinned` as +deployment query parameters. For the complete repository layout generated by +this module, use `UniversalRepositoryAsModule: false`. + +## Common parameters + +The task file exposes these values through Sampler properties and environment +variables: + +| Parameter | Purpose | +|---|---| +| `OutputDirectory` | Base build output directory. | +| `UniversalServerUrl` | PowerShell Universal server URL. | +| `UniversalServerAppToken` | Deployment application token. | +| `UniversalPSResourceRepositoryName` | Resource repository name. | +| `UniversalPSResourceRepositoryUrl` | Resource repository URL or path. | +| `UniversalPSResourceRepositoryAutoRemove` | Controls repository cleanup. | +| `UniversalRepositoryStagingDirectoryName` | Offline repository staging directory name. | +| `UniversalRepositoryZipName` | Offline repository zip file name. | +| `UniversalRepositoryAsModule` | Deployment endpoint `asModule` value. | +| `UniversalUnpinned` | Deployment endpoint `unpinned` value. | + +See [Configuration](Configuration.md) for defaults and precedence.