### Module Versioning Examples

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Demonstrates correct and incorrect module version formats using semantic versioning (MAJOR.MINOR.PATCH).

```powershell
ModuleVersion = '1.2.3'  # Good
ModuleVersion = '1.2'    # Bad - missing patch
```

--------------------------------

### Publish-PSModule Workflow Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/version-management.md

Illustrates a typical progression of module publishing using Publish-PSModule, showing how versions and releases are created and how automatic cleanup affects prerelease tags.

```yaml
Commit A: manifest version = 1.0.0-alpha
  ↓ Publish-PSModule with AutoCleanup disabled
  ↓ Creates: Release 1.0.0-alpha, Gallery: 1.0.0-alpha

Commit B: manifest version = 1.0.0-beta
  ↓ Publish-PSModule with AutoCleanup disabled
  ↓ Creates: Release 1.0.0-beta, Gallery: 1.0.0-beta
  ↓ Cleanup skips (both are prereleases)

Commit C: manifest version = 1.0.0
  ↓ Publish-PSModule with AutoCleanup enabled
  ↓ Creates: Release 1.0.0 (marked latest), Gallery: 1.0.0
  ↓ Cleanup deletes: 1.0.0-alpha, 1.0.0-beta tags (matches pattern)
```

--------------------------------

### Install PSResource Module

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/workflow-integration.md

Ensures the latest version of the Microsoft.PowerShell.PSResourceGet module is installed from the PSGallery. Use -TrustRepository to suppress confirmation prompts for untrusted repositories.

```powershell
Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Repository PSGallery -TrustRepository
```

--------------------------------

### Simulate Publishing with WhatIf

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Use the 'WhatIf' parameter to test the entire publishing workflow without making any actual changes to the repository or publishing to the gallery. This is useful for verifying the setup and flow.

```yaml
name: Test Publishing Workflow

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: write
  pull-requests: write

jobs:
  test-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Simulate Publishing (WhatIf)
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          WhatIf: 'true'
```

--------------------------------

### Minimal Publish Module Workflow

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/README.md

This workflow demonstrates the basic setup for publishing a PowerShell module. It checks out the code, builds the module, and then publishes it using the provided API key. Ensure the 'PSGALLERY_API_KEY' secret is configured in your repository.

```yaml
name: Publish Module

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Prerelease PowerShell Module Manifest

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

An example of a PowerShell module manifest configured for a prerelease version, specifying a prerelease tag like 'beta.1'.

```powershell
@{
    ModuleVersion = '2.0.0'
    Name = 'MyModule'
    Description = 'My PowerShell Module'
    Author = 'John Doe'
    CompanyName = 'Acme Inc'
    Copyright = '(c) 2024 Acme Inc. All rights reserved.'
    RootModule = 'MyModule.psm1'
    FunctionsToExport = @('Get-Item', 'Set-Item', 'New-Item')
    RequiredModules = @('Microsoft.PowerShell.Utility')
    PowerShellVersion = '5.1'
    PrivateData = @{
        PSData = @{
            Prerelease = 'beta.1'
        }
    }
}
```

--------------------------------

### Placeholder ModuleVersion Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

This error occurs when the ModuleVersion is set to the placeholder '999.0.0', indicating the build step did not stamp the artifact with a real version. Verify build logs and ensure the correct artifact is used.

```powershell
Error: ModuleVersion is the placeholder [999.0.0]. The artifact was not stamped with a real version by the build step.
```

--------------------------------

### PowerShell Module Manifest Snippet

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/version-management.md

Example of a PowerShell module manifest snippet showing how ModuleVersion and Prerelease are defined. This manifest would result in a published version of '1.2.3-beta.1'.

```powershell
@{
    ModuleVersion = '1.2.3'
    PrivateData = @{
        PSData = @{
            Prerelease = 'beta.1'
        }
    }
}
```

--------------------------------

### Minimal Valid PowerShell Module Manifest

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

A basic example of a PowerShell module manifest containing only the essential fields required for a valid manifest.

```powershell
@{
    ModuleVersion = '1.0.0'
    Name = 'MyModule'
    RootModule = 'MyModule.psm1'
}
```

--------------------------------

### Publish Module with Custom Environment Variable

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

This example shows how to pass a custom environment variable to the Publish-PSModule action. This can be useful for configuring specific behaviors or passing additional information.

```yaml
- name: Publish Module
  uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
  env:
    CUSTOM_VAR: value
```

--------------------------------

### Manifest File Not Found Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

This error occurs when the module manifest file (.psd1) is missing from the module directory. Ensure the .psd1 file exists and its name matches the module name.

```powershell
Error: Module manifest file not found at [/home/runner/work/repo/repo/outputs/module/MyModule/MyModule.psd1]
```

--------------------------------

### Stable Release PowerShell Module Manifest

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

An example of a complete PowerShell module manifest for a stable release, including metadata, exported functions, and required modules.

```powershell
@{
    ModuleVersion = '1.2.3'
    Name = 'MyModule'
    Description = 'My PowerShell Module'
    Author = 'John Doe'
    CompanyName = 'Acme Inc'
    Copyright = '(c) 2024 Acme Inc. All rights reserved.'
    RootModule = 'MyModule.psm1'
    FunctionsToExport = @('Get-Item', 'Set-Item')
    RequiredModules = @()
    PowerShellVersion = '5.1'
    PrivateData = @{
        PSData = @{
            Prerelease = ''
        }
    }
}
```

--------------------------------

### Failed to Import Manifest Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

This error indicates a problem parsing the .psd1 manifest file, often due to syntax errors or incorrect encoding. Validate the manifest syntax and ensure it's saved with UTF-8 encoding.

```powershell
Error: Failed to import manifest data file [...MyModule.psd1]: 
  Unexpected token 'something' in expression or statement.
```

--------------------------------

### Build Artifact (Pre-stamped) PowerShell Module Manifest

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

A manifest example for a build artifact, where the version is pre-stamped by a build process and the prerelease tag is empty for stable builds.

```powershell
@{
    ModuleVersion = '1.5.0'    # Stamped by Build-PSModule
    Name = 'MyModule'
    Description = 'My PowerShell Module'
    Author = 'John Doe'
    CompanyName = 'Acme Inc'
    Copyright = '(c) 2024 Acme Inc. All rights reserved.'
    RootModule = 'MyModule.psm1'
    FunctionsToExport = @('Get-Item', 'Set-Item')
    RequiredModules = @()
    PowerShellVersion = '5.1'
    PrivateData = @{
        PSData = @{
            Prerelease = ''         # Empty for stable builds
        }
    }
}
```

--------------------------------

### Prerelease Field Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Defines a prerelease identifier for alpha, beta, or release candidate versions. This field, nested under PrivateData.PSData, is used for determining release tags and gallery versions.

```powershell
@{
    ModuleVersion = '1.0.0'
    PrivateData = @{
        PSData = @{
            Prerelease = 'beta.1'
        }
    }
}
```

--------------------------------

### Publish PowerShell Module to Gallery

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/version-management.md

Use the Publish-PSResource cmdlet to publish a PowerShell module to the PSGallery repository. Ensure the Microsoft.PowerShell.PSResourceGet module is installed, a valid API key is provided, and the module path points to the module root directory.

```powershell
Publish-PSResource -Path $modulePath -Repository PSGallery -ApiKey $apiKey
```

--------------------------------

### Publish-PSResource Cmdlet Errors

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

These examples illustrate common error messages when the Publish-PSResource cmdlet fails. They typically indicate issues with authentication, existing versions, network connectivity, or server-side problems.

```powershell
❌ Invalid key: 401 Unauthorized
```

```powershell
❌ Already published: Conflict - version exists
```

```powershell
❌ Server error: 500 Internal Server Error
```

```powershell
❌ Timeout: Connection timeout after 30 seconds
```

--------------------------------

### Publish Module and Notify Slack

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Integrate Slack notifications into the publishing workflow to announce successful module publications. This example uses the slackapi/slack-github-action to post a formatted message to a Slack channel upon successful completion of the publish step.

```yaml
name: Publish with Notification

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Module
        id: publish
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
      
      - name: Notify Slack
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
          payload: |
            {
              "text": "Module published!",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "✅ Module ${{ github.event.repository.name }} published\n<${{ github.server_url }}/${{ github.repository }}/releases|View Release>"
                  }
                }
              ]
            }
```

--------------------------------

### RequiredModules Field

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Lists other PowerShell modules that this module depends on. `Resolve-PSModuleDependency` uses this field to install necessary dependencies.

```powershell
@{
    RequiredModules = @('ModuleA', 'ModuleB')
}
```

--------------------------------

### Test Publishing with WhatIf

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/README.md

This snippet shows how to perform a dry run of the publishing process using the 'WhatIf' parameter. This is useful for testing your workflow without actually publishing the module to the gallery. Ensure the 'PSGALLERY_API_KEY' secret is configured.

```yaml
- name: Test Publishing (Dry Run)
  uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
    WhatIf: 'true'
```

--------------------------------

### Build and Publish-PSModule Workflow

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/workflow-integration.md

This workflow first checks out the code, builds the module using `Build-PSModule`, and then publishes it. It requires a `PSGALLERY_API_KEY` secret and uses `AutoCleanup` and `UsePRBodyAsReleaseNotes` options.

```yaml
name: Build and Publish

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  build:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
        # Outputs artifact named 'module'
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          AutoCleanup: 'true'
          UsePRBodyAsReleaseNotes: 'true'
```

--------------------------------

### ModuleVersion Field Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Specifies the version of the module using Semantic Versioning (MAJOR.MINOR.PATCH). This field is required for publishing and is validated against a specific regex format.

```powershell
@{
    ModuleVersion = '1.2.3'
}
```

--------------------------------

### Manual Module Publishing with Input Parameters

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Enable manual triggering of the publishing workflow directly from the GitHub UI, allowing users to specify parameters like 'WhatIf' mode. This provides flexibility for ad-hoc testing or controlled releases.

```yaml
name: Manual Publish

on:
  workflow_dispatch:
    inputs:
      whatif:
        description: Dry run (WhatIf mode)
        required: false
        default: 'false'
        type: choice
        options:
          - 'false'
          - 'true'

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          WhatIf: ${{ github.event.inputs.whatif }}
```

--------------------------------

### Prerelease Version Progression

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Shows how to use prerelease identifiers (alpha, beta, rc) for development and testing phases, and how to represent a stable release.

```powershell
# Development
Prerelease = 'alpha.1'

# Beta testing
Prerelease = 'beta.1'
Prerelease = 'beta.2'

# Release candidate
Prerelease = 'rc.1'

# Stable (empty)
Prerelease = ''
```

--------------------------------

### Minimal Configuration for Publish-PSModule

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

This is the simplest configuration for publishing a module to the PowerShell Gallery. It requires only the API key and uses default settings for module name, path, and version.

```yaml
name: Publish Module

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Create a GitHub Release

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

Use this command to create a new GitHub release. Specify the tag, optionally provide a title, and choose between providing release notes via a file or auto-generating them. You can also set the target branch for prereleases and mark the release as a prerelease.

```bash
gh release create <tag> [--title <title>] [--notes-file <file>|--generate-notes] [--target <branch>] [--prerelease]
```

--------------------------------

### Download Module Artifact Configuration

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/workflow-integration.md

Configures the actions/download-artifact action to download a pre-built module artifact. Specify the artifact name and the local path for download.

```yaml
name: ${{ inputs.ArtifactName }}  # Default: 'module'
path: ${{ inputs.ModulePath }}    # Default: 'outputs/module'
```

--------------------------------

### Module Directory Not Found Error Example

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

This error occurs when the specified module directory is not found within the artifact. Ensure the artifact has the correct <ModulePath>/<Name>/ subdirectory layout.

```powershell
Error: Module directory not found at [/home/runner/work/repo/repo/outputs/module/MyModule].
Ensure the artifact contains a <ModulePath>/<Name>/ subdirectory layout.
```

--------------------------------

### GitHub CLI Release Creation Command

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/api-reference/publish-ps1.md

Use this command template to create a GitHub release. You can specify a tag, title, notes file or generate notes automatically, and target a specific branch. The `--prerelease` flag can be used for pre-release versions.

```powershell
gh release create <tag> --title <title> [--notes-file <path>|--generate-notes] [--target <branch>] [--prerelease]
```

--------------------------------

### Build Once, Use Twice Workflow

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Use this pattern to build your module artifact once and then deploy it to multiple repositories or environments. It separates the build job from subsequent publish jobs.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
        with:
          ArtifactName: built-module

  publish-gallery:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Publish to Gallery
        uses: PSModule/Publish-PSModule@main
        with:
          ArtifactName: built-module
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}

  publish-alternate:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Publish to Alternate Repository
        uses: custom/publish-action@main
        with:
          artifact: built-module
```

--------------------------------

### Manifest with Comments

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Demonstrates how to include comments within a PowerShell manifest file, including single-line and block comments for fields like ModuleVersion and Prerelease.

```powershell
@{
    # This is a required field - semantic version format
    ModuleVersion = '1.0.0'
    
    <#
        Prerelease identifier for alpha/beta/rc versions
        Leave empty for stable releases
    #>
    PrivateData = @{
        PSData = @{
            Prerelease = ''
        }
    }
}
```

--------------------------------

### Basic PowerShell Manifest Structure

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Illustrates the essential and optional fields for a PowerShell module manifest file (.psd1). Includes module version, metadata, composition, and requirements.

```powershell
@{
    # Required fields
    ModuleVersion = '1.0.0'
    
    # Optional prerelease field
    PrivateData = @{
        PSData = @{
            Prerelease = 'beta.1'
        }
    }
    
    # Standard metadata
    Name = 'MyModule'
    Description = 'Module description'
    Author = 'Author Name'
    CompanyName = 'Company'
    Copyright = 'Copyright info'
    
    # Module composition
    RootModule = 'MyModule.psm1'
    FunctionsToExport = @('Function1', 'Function2')
    
    # Requirements
    PowerShellVersion = '5.1'
    RequiredModules = @()
}
```

--------------------------------

### Conditional Module Publishing

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Implement conditional publishing logic to ensure modules are only published when specific criteria are met, such as merging a pull request from a branch that starts with 'release/'. This prevents accidental publishes from feature branches.

```yaml
name: Conditional Publishing

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    if: |
      github.event.pull_request.merged == true &&
      startsWith(github.event.pull_request.head.ref, 'release/')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### List GitHub Releases

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/api-reference/cleanup-ps1.md

This command queries GitHub for a list of releases, returning detailed information in JSON format. This data is used to identify prereleases that need to be cleaned up.

```bash
gh release list --json 'createdAt,isDraft,isLatest,isPrerelease,name,publishedAt,tagName'
```

--------------------------------

### Invalid Prerelease Format Examples

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

Prerelease identifiers in the manifest's PrivateData.PSData.Prerelease field must adhere to SemVer rules, containing only alphanumerics, hyphens, and dots as separators. Avoid underscores, spaces, and special characters.

```powershell
✅ "alpha"
```

```powershell
✅ "beta.1"
```

```powershell
✅ "rc1"
```

```powershell
✅ "0.1.0"
```

```powershell
✅ "a.b.c"
```

```powershell
✅ "1-2-3"
```

--------------------------------

### Invalid ModuleVersion Format Examples

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

The ModuleVersion in the manifest must follow the Major.Minor.Patch format (e.g., 1.0.0). Versions like '1.0' or those with pre-release information in this field will cause errors. Use the Prerelease field for pre-release identifiers.

```powershell
❌ Invalid: "1.0" (missing patch)
```

```powershell
❌ Invalid: "1" (missing minor and patch)
```

```powershell
❌ Invalid: "1.0.0-beta.1" (has prerelease - put in Prerelease field)
```

```powershell
✅ Valid: "1.0.0"
```

```powershell
✅ Valid: "2.1.3"
```

--------------------------------

### Upload a File to a GitHub Release

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

Attach a file to an existing GitHub release. You must specify the release tag and the path to the file. The `--clobber` option can be used to overwrite an existing asset with the same name.

```bash
gh release upload <tag> <file> [--clobber]
```

--------------------------------

### Configuring API Key with GitHub Secret

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/workflow-integration.md

Demonstrates how to securely pass the PowerShell Gallery API key to the Publish-PSModule action using a GitHub secret. This is the recommended approach for API key management.

```yaml
- uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Full CI/CD Pipeline with PSModule

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

This workflow automates the build, test, and publish steps for a PowerShell module. It handles pull requests and merges, ensuring modules are built, tested, and published to a gallery.

```yaml
name: Build, Test, and Publish

on:
  pull_request:
    types: [opened, synchronize, reopened]
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write
  checks: write

jobs:
  build:
    if: github.event.pull_request.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
        with:
          ArtifactName: module

  test:
    if: github.event.pull_request.action != 'closed'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: module
          path: outputs/module
      
      - name: Run Tests
        shell: pwsh
        run: |
          Invoke-Pester -Path tests/ -OutputFormat NUnitXml -OutputFile results.xml
      
      - name: Publish Test Results
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          files: results.xml

  publish:
    if: |
      github.github.event.pull_request.merged == true &&
      github.event.action == 'closed'
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          AutoCleanup: 'true'
          UsePRBodyAsReleaseNotes: 'true'
```

--------------------------------

### Advanced Publish-PSModule Workflow with Options

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/workflow-integration.md

An advanced workflow that builds the module, publishes it with custom options like `Name`, `ModulePath`, `WhatIf: 'false'`, and various release note configurations. It requires a `PSGALLERY_API_KEY` secret.

```yaml
name: Build, Publish, and Release

on:
  pull_request:
    types: [closed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
        with:
          ArtifactName: module
      
      - name: Publish Module
        uses: PSModule/Publish-PSModule@main
        with:
          Name: MyModule
          ModulePath: outputs/module
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          AutoCleanup: 'true'
          WhatIf: 'false'
          UsePRTitleAsReleaseName: 'true'
          UsePRBodyAsReleaseNotes: 'true'
          UsePRTitleAsNotesHeading: 'true'
          ArtifactName: module
```

--------------------------------

### Script Parameters

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/api-reference/cleanup-ps1.md

The cleanup.ps1 script does not accept explicit parameters. Configuration is managed through environment variables and the GitHub Actions context.

```powershell
[CmdletBinding()]
param()
```

--------------------------------

### Download Artifact using actions/download-artifact

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

Use this snippet to download a previously uploaded artifact. Specify the artifact name and the local path where it should be extracted.

```yaml
- uses: actions/download-artifact@v8
  with:
    name: module
    path: outputs/module
```

--------------------------------

### List GitHub Releases with JSON Output

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

Retrieve a list of all releases in a repository in JSON format. You can specify which fields to include in the output, such as `tagName`, `name`, `isDraft`, `isPrerelease`, `isLatest`, `createdAt`, `publishedAt`, and `body`.

```bash
gh release list --json 'tagName,name,isDraft,isPrerelease,isLatest,createdAt,publishedAt,body'
```

--------------------------------

### Publish Multiple Modules from One Repository

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Configure the workflow to build and publish multiple distinct modules from a single repository. Each module is specified with its own path and artifact name, ensuring they are handled independently during the publishing process.

```yaml
- name: Build Module A
  uses: PSModule/Build-PSModule@main
  with:
    ModulePath: src/ModuleA
    ArtifactName: moduleA

- name: Build Module B
  uses: PSModule/Build-PSModule@main
  with:
    ModulePath: src/ModuleB
    ArtifactName: moduleB

- name: Publish Module A
  uses: PSModule/Publish-PSModule@main
  with:
    Name: ModuleA
    ModulePath: outputs
    ArtifactName: moduleA
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}

- name: Publish Module B
  uses: PSModule/Publish-PSModule@main
  with:
    Name: ModuleB
    ModulePath: outputs
    ArtifactName: moduleB
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Matrix Testing and Publishing Workflow

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

This pattern allows you to test your module against multiple PowerShell versions using a matrix strategy and then publish the module only once after all tests pass. Ensure your tests are robust before relying on a single publish step.

```yaml
jobs:
  test:
    strategy:
      matrix: 
        ps-version: ['5.1', '7.0', '7.1', '7.2', '7.3', '7.4']
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-powershell@v2
        with:
          powershell-version: ${{ matrix.ps-version }}
      
      - name: Run Tests
        shell: pwsh
        run: Invoke-Pester

  publish:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Publish-PSModule with Custom Module Name and Path

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Configure the module name and artifact path when they differ from the repository defaults. Ensure the ModulePath points to the directory containing the module.

```yaml
- name: Publish Module
  uses: PSModule/Publish-PSModule@main
  with:
    Name: MyCustomModule
    ModulePath: build/artifacts
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
```

--------------------------------

### Publish-PSModule with PR-Driven Release Notes

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Utilize the Pull Request title and body to automatically generate release information. Set 'UsePRTitleAsReleaseName' and 'UsePRBodyAsReleaseNotes' to 'true'.

```yaml
- name: Publish Module
  uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
    UsePRTitleAsReleaseName: 'true'
    UsePRBodyAsReleaseNotes: 'true'
    UsePRTitleAsNotesHeading: 'true'
```

--------------------------------

### Check GitHub Release Tag Existence

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

Verify if a release tag already exists on GitHub before attempting to create a new release. This helps prevent 'tag already exists' errors.

```bash
gh release list | grep <tag>
```

--------------------------------

### Publish-PSModule: Use PR Title and Body for Release Notes

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/action-inputs.md

Configures the Publish-PSModule action to format release notes using both the pull request title as a heading and the PR body. Requires both to be present.

```yaml
- uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
    UsePRBodyAsReleaseNotes: 'true'
    UsePRTitleAsNotesHeading: 'true'
```

--------------------------------

### GitHub Actions Workflow for Publishing

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

This YAML snippet shows how to use the PSModule/Publish-PSModule action in a GitHub Actions workflow to publish a module. It demonstrates using a GitHub Secret for the API key.

```yaml
- uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}  # GitHub Secret
```

--------------------------------

### GitHub CLI Artifact Upload Command

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/api-reference/publish-ps1.md

This command uploads a compressed module artifact to a GitHub release. The `--clobber` flag allows overwriting an existing artifact if the release already exists.

```powershell
gh release upload <tag> <zipPath> --clobber
```

--------------------------------

### Incrementing Module Versions for Releases

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Illustrates how to increment the patch, minor, or major version for different types of releases (bug fix, new feature, breaking change).

```powershell
# First release
ModuleVersion = '1.0.0'

# Bug fix
ModuleVersion = '1.0.1'

# New feature
ModuleVersion = '1.1.0'

# Breaking change
ModuleVersion = '2.0.0'
```

--------------------------------

### Reading Manifest Data

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/manifest-format.md

Shows how to safely read a PowerShell manifest file (.psd1) using the `Import-PowerShellDataFile` cmdlet, which prevents arbitrary code execution.

```powershell
$manifestData = Import-PowerShellDataFile -Path $manifestFilePath
```

--------------------------------

### Dry Run with WhatIf Mode

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/external-dependencies.md

Use WhatIf mode for dry-run testing without making actual changes to the PowerShell Gallery or GitHub releases. This snippet demonstrates how to configure the action for a WhatIf test.

```yaml
- uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
    WhatIf: 'true'
```

--------------------------------

### Publish-PSModule with Auto-Generated Release Notes

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

Opt for auto-generated release notes using GitHub's changelog generator by setting 'UsePRBodyAsReleaseNotes' to 'false'. This is useful when the PR body is not descriptive.

```yaml
- name: Publish Module
  uses: PSModule/Publish-PSModule@main
  with:
    APIKey: ${{ secrets.PSGALLERY_API_KEY }}
    UsePRBodyAsReleaseNotes: 'false'
```

--------------------------------

### View GitHub Release

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/error-reference.md

Check if a specific GitHub release exists before attempting to upload artifacts to it. This helps diagnose 'release doesn't exist' errors.

```bash
gh release view <tag>
```

--------------------------------

### Optional Manifest Fields for Prerelease PowerShell Module

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/README.md

Shows how to include prerelease information in a PowerShell module's manifest using the 'Prerelease' field within 'PrivateData.PSData'.

```powershell
@{
    PrivateData = @{
        PSData = @{
            Prerelease = 'beta.1'   # SemVer prerelease identifier
        }
    }
}
```

--------------------------------

### Prerelease Workflow for PSModule

Source: https://github.com/psmodule/publish-psmodule/blob/main/_autodocs/usage-examples.md

This workflow automatically publishes prerelease versions of a module on every commit to the 'develop' branch. It preserves all prerelease versions, making them visible in the gallery.

```yaml
name: Prerelease

on:
  push:
    branches: [develop]

permissions:
  contents: write
  pull-requests: write

jobs:
  prerelease:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Build Module
        uses: PSModule/Build-PSModule@main
      
      - name: Publish Prerelease
        uses: PSModule/Publish-PSModule@main
        with:
          APIKey: ${{ secrets.PSGALLERY_API_KEY }}
          AutoCleanup: 'false'
```