Configuration

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

UniversalServer:
  UniversalServerUrl: https://psu.example.test
  UniversalPSResourceRepositoryName: output
  UniversalPSResourceRepositoryUrl: ./output/
  UniversalPSResourceRepositoryAutoRemove: true
  UniversalRepositoryStagingDirectoryName: PsuRepository
  UniversalRepositoryZipName:
  UniversalRepositoryAsModule: false
  UniversalUnpinned: true
  UniversalDeploymentNotificationDelaySeconds: 2
  UniversalDeploymentNotificationLookbackSeconds: 120
  UniversalDeploymentNotificationFilter:

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	<ProjectName>.<ModuleVersion>.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.
UniversalDeploymentNotificationDelaySeconds	2	Seconds to wait before querying notifications after deployment. Valid range: 0-300.
UniversalDeploymentNotificationLookbackSeconds	120	Fallback lookback window when no deployment start time was recorded in the current workflow. Valid range: 1-3600.
UniversalDeploymentNotificationFilter	Empty	Optional text that must appear in a deployment error title or description.

Authentication

The deployment tasks require UniversalServerAppToken. In CI, map a secret to the environment variable:

env:
  UniversalServerAppToken: ${{ secrets.UniversalServerAppToken }}

For local development, use the ignored secrets.local.ps1 file:

$UniversalServerAppToken = '<token>'

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:

PsuRepository/
|-- repository.psd1
`-- Modules/
    |-- MyModule/
    |   `-- 1.0.0/
    `-- MyDependency/
        `-- 2.0.0/

The zip contains the project module and transitively resolved RequiredModules dependencies. Dependencies are processed through an iterative queue, matching Sampler's packaging approach and avoiding nested recursive calls. The first discovery order is retained; when the same module is required again, its selection changes only if the newly resolved version is higher. 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.

Post-deployment validation

Add assert_universal_deployment_succeeded immediately after a deployment task. The deployment tasks record their UTC start time, and the assertion task queries:

GET /api/v1/notification/last

The workflow fails when a newer deployment, module, or configuration notification:

• has level Error;
• contains failed or error; or
• contains Invalid configuration.

If the assertion task runs without a deployment task in the same InvokeBuild workflow, it uses UniversalDeploymentNotificationLookbackSeconds.

Use UniversalDeploymentNotificationFilter when multiple deployments can run against the same PSU instance concurrently and notifications contain a stable module or project identifier.

For example, restrict deployment errors to notifications containing the module name:

UniversalServer:
  UniversalDeploymentNotificationFilter: MyModule

The filter is case-insensitive and applies to the combined notification title and description. Leave it empty to consider every recent deployment error. Only set a filter when PSU includes that value in relevant error notifications; a filter intentionally excludes generic deployment errors that do not contain the configured text.