# Task Reference

The exported alias `Task.Publish_PowerShellUniversal` loads one InvokeBuild task
file containing the tasks documented on this page.

Low-level tasks perform one packaging, publishing, or validation operation.
Compound tasks sequence only operations exported by this module. Build and
package workflows owned by the consumer repository remain explicit in the
consumer `build.yaml`.

## 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)
- [assert_universal_deployment_succeeded](#assert_universal_deployment_succeeded)
- [publish_psu_pull_module_from_psresourcerepo](#publish_psu_pull_module_from_psresourcerepo)
- [publish_psu_push_repository](#publish_psu_push_repository)
- [Compound task dependency boundary](#compound-task-dependency-boundary)
- [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.
- `<OutputDirectory>/<ProjectName>.<ModuleVersion>.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 transitively resolved `RequiredModules`. Module
dependencies are processed through an iterative queue rather than nested
recursive calls. First-discovery order is preserved, while a later occurrence
replaces the selected module only when it resolves to a higher version.

### Prerequisites

- The module build has completed.
- The built module manifest is available.
- Every required module can be resolved from `PSModulePath`.

### Outputs

- Staging directory:
  `<OutputDirectory>/<UniversalRepositoryStagingDirectoryName>`
- Zip package:
  `<OutputDirectory>/<ProjectName>.<ModuleVersion>.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`.

## assert_universal_deployment_succeeded

Queries recent PowerShell Universal notifications and throws when PSU reports a
deployment-related error after the deployment start time.

### Typical workflow

```yaml
BuildWorkflow:
  deploy_repository:
    - pack
    - publish_universal_automation_repository_to_server
    - assert_universal_deployment_succeeded
```

The deployment tasks record their start time in the current InvokeBuild
session. When no start time is available, the assertion checks the configured
lookback window.

The task fails on newer deployment, module, or configuration notifications
whose level is `Error` or whose text contains `failed`, `error`, or
`Invalid configuration`.

An optional notification filter can restrict matches to a module or project
identifier when deployments run concurrently.

```yaml
UniversalServer:
  UniversalDeploymentNotificationFilter: MyModule
```

When errors are found, the task writes each timestamp, level, title, and
description to the build log before throwing a terminating error containing
the same summary.

## publish_psu_pull_module_from_psresourcerepo

Provides a single workflow entry that runs:

1. `publish_module_from_psresource_repos_to_universal_server`
1. `assert_universal_deployment_succeeded`

```yaml
BuildWorkflow:
  deploy:
    - pack
    - publish_psu_pull_module_from_psresourcerepo
```

Use this task when PSU should pull the project module and its packaged
dependencies from the configured PowerShell resource repository. The consumer
workflow remains responsible for building and packaging those artifacts.

## publish_psu_push_repository

Provides a single workflow entry that runs:

1. `package_universal_automation_repository`
1. `publish_universal_automation_repository_to_server`
1. `assert_universal_deployment_succeeded`

```yaml
BuildWorkflow:
  deploy:
    - build
    - publish_psu_push_repository
```

Use this task when the build should assemble and push the complete offline
automation repository layout. The consumer workflow remains responsible for
producing the built module consumed by the repository packaging task.

## Compound task dependency boundary

The compound tasks do not reference consumer workflows such as `build`, `test`,
`pack`, or `publish`, and do not depend on unrelated external task modules.
This keeps their internal sequence stable when a consumer changes its workflow
names or packaging strategy.

## 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. |
| `UniversalDeploymentNotificationDelaySeconds` | Delay before querying notifications. |
| `UniversalDeploymentNotificationLookbackSeconds` | Fallback lookback window when no deployment start time is recorded. |
| `UniversalDeploymentNotificationFilter` | Optional title or description filter for deployment errors. |

See [Configuration](Configuration.md) for defaults and precedence.