build-test-and-deploy-powershell-module.yml

name: build-and-deploy

on:
  push:
    branches: main
    paths: [ "src/**", "build/**", "deploy/**", ".github/workflows/**", ".cspell.json" ]

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:
    inputs:
      versionNumber:
        description: 'The version number to use for the module. This should be in the format of "Major.Minor.Patch". e.g. "1.0.0". Future builds will increment from this version number. This input is optional. If not provided, the previous version numbers Patch will be incremented.'
        required: false
        type: string
        default: ''

env:
  artifactsDirectoryPath: './artifacts'

jobs:
  run-build-and-test:
    uses: ./.github/workflows/build-and-test-powershell-module.yml
    with:
      versionNumber: ${{ github.event.inputs.versionNumber }}

  publish-prerelease-module:
    needs: run-build-and-test
    runs-on: ubuntu-latest
    steps:
      - name: Download module artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.moduleArtifactName }}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Publish prerelease PowerShell module
        shell: pwsh
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $moduleDirectoryPath = "$Env:artifactsDirectoryPath/$moduleName"
          [string] $moduleManifestFilePath = Join-Path -Path $moduleDirectoryPath -ChildPath "$moduleName.psd1"
          [string] $prereleaseVersionLabel = '${{ needs.run-build-and-test.outputs.prereleaseVersionLabel}}'

          Write-Output "Updating the module manifest version number's prerelease label to '$prereleaseVersionLabel'."
          Update-ModuleManifest -Path $moduleManifestFilePath -Prerelease $prereleaseVersionLabel

          Write-Output "Testing the prerelease module manifest file '$moduleManifestFilePath' to ensure it is still valid."
          Test-ModuleManifest -Path $moduleManifestFilePath

          Write-Output "Publishing the prerelease version of the module."
          Publish-Module -Path $moduleDirectoryPath -NuGetApiKey '${{ secrets.POWERSHELL_GALLERY_API_KEY }}' -Verbose

      - name: Wait a short while for the module to be available on the PowerShell Gallery before continuing
        shell: pwsh
        run: Start-Sleep -Seconds 30

  test-prerelease-module-in-pwsh:
    needs: [run-build-and-test, publish-prerelease-module]
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macOS-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Display PowerShell version being used
        shell: pwsh
        run: $PSVersionTable

      - name: Install prerelease module from PowerShell Gallery
        shell: pwsh
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $prereleaseVersionNumber = '${{ needs.run-build-and-test.outputs.prereleaseVersionNumber}}'

          Write-Output "Installing the module '$moduleName' prerelease version '$prereleaseVersionNumber' from the PowerShell Gallery."
          Install-Module -Name $moduleName -AllowPrerelease -RequiredVersion $prereleaseVersionNumber -Force -Scope CurrentUser -Repository PSGallery -ErrorAction Stop -Verbose

      - name: Download deploy files artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.deployFilesArtifactName}}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Run smoke tests
        shell: pwsh
        run: |
          [string] $smokeTestsScriptPath = "$Env:artifactsDirectoryPath/Invoke-SmokeTests.ps1"

          Write-Output "Running Pester smoke tests from file '$smokeTestsScriptPath'."
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{
              Path = $smokeTestsScriptPath
              Throw = $true
            }
          }
          Invoke-Pester -Configuration $pesterConfig

          Write-Output "Displaying the installed module version that was used for the smoke tests."
          Get-Module -Name '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'

  test-prerelease-module-in-windows-powershell:
    needs: [run-build-and-test, publish-prerelease-module]
    runs-on: windows-latest
    steps:
      - name: Display PowerShell version being used
        shell: powershell
        run: $PSVersionTable

      - name: Install prerelease module from PowerShell Gallery
        shell: powershell
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $prereleaseVersionNumber = '${{ needs.run-build-and-test.outputs.prereleaseVersionNumber}}'

          Write-Output "Installing the module '$moduleName' prerelease version '$prereleaseVersionNumber' from the PowerShell Gallery."
          Install-Module -Name $moduleName -AllowPrerelease -RequiredVersion $prereleaseVersionNumber -Force -Scope CurrentUser -Repository PSGallery -ErrorAction Stop -Verbose

      - name: Download deploy files artifact from triggered workflow
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.deployFilesArtifactName}}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Run smoke tests
        shell: powershell
        run: |
          [string] $smokeTestsScriptPath = "$Env:artifactsDirectoryPath/Invoke-SmokeTests.ps1"

          Write-Output "Running Pester smoke tests from file '$smokeTestsScriptPath'."
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{
              Path = $smokeTestsScriptPath
              Throw = $true
            }
          }
          Invoke-Pester -Configuration $pesterConfig

          Write-Output "Displaying the installed module version that was used for the smoke tests."
          Get-Module -Name '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'

  publish-stable-module:
    needs: [run-build-and-test, test-prerelease-module-in-pwsh, test-prerelease-module-in-windows-powershell]
    runs-on: ubuntu-latest
    environment: production # Used for deployment approvals.
    steps:
      - name: Download module artifact from triggered workflow
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.moduleArtifactName}}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Publish stable PowerShell module
        shell: pwsh
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $moduleDirectoryPath = "$Env:artifactsDirectoryPath/$moduleName"
          Publish-Module -Path $moduleDirectoryPath -NuGetApiKey '${{ secrets.POWERSHELL_GALLERY_API_KEY }}' -Verbose

      - name: Wait a short while for the module to be available on the PowerShell Gallery before continuing
        shell: pwsh
        run: Start-Sleep -Seconds 30

  test-stable-module-in-pwsh:
    needs: [run-build-and-test, publish-stable-module]
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macOS-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Display PowerShell version being used
        shell: pwsh
        run: $PSVersionTable

      - name: Install stable module from PowerShell Gallery
        shell: pwsh
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $stableVersionNumber = '${{ needs.run-build-and-test.outputs.stableVersionNumber}}'

          Write-Output "Installing the module '$moduleName' stable version '$stableVersionNumber' from the PowerShell Gallery."
          Install-Module -Name $moduleName -RequiredVersion $stableVersionNumber -Force -Scope CurrentUser -Repository PSGallery -ErrorAction Stop -Verbose

      - name: Download deploy files artifact from triggered workflow
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.deployFilesArtifactName}}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Run smoke tests
        shell: pwsh
        run: |
          [string] $smokeTestsScriptPath = "$Env:artifactsDirectoryPath/Invoke-SmokeTests.ps1"

          Write-Output "Running Pester smoke tests from file '$smokeTestsScriptPath'."
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{
              Path = $smokeTestsScriptPath
              Throw = $true
            }
          }
          Invoke-Pester -Configuration $pesterConfig

          Write-Output "Displaying the installed module version that was used for the smoke tests."
          Get-Module -Name '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'

  test-stable-module-in-windows-powershell:
    needs: [run-build-and-test, publish-stable-module]
    runs-on: windows-latest
    steps:
      - name: Display PowerShell version being used
        shell: powershell
        run: $PSVersionTable

      - name: Install stable module from PowerShell Gallery
        shell: powershell
        run: |
          [string] $moduleName = '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'
          [string] $stableVersionNumber = '${{ needs.run-build-and-test.outputs.stableVersionNumber}}'

          Write-Output "Installing the module '$moduleName' stable version '$stableVersionNumber' from the PowerShell Gallery."
          Install-Module -Name $moduleName -RequiredVersion $stableVersionNumber -Force -Scope CurrentUser -Repository PSGallery -ErrorAction Stop -Verbose

      - name: Download deploy files artifact from triggered workflow
        uses: actions/download-artifact@v4
        with:
          name: ${{ needs.run-build-and-test.outputs.deployFilesArtifactName}}
          path: ${{ env.artifactsDirectoryPath }}

      - name: Run smoke tests
        shell: powershell
        run: |
          [string] $smokeTestsScriptPath = "$Env:artifactsDirectoryPath/Invoke-SmokeTests.ps1"

          Write-Output "Running Pester smoke tests from file '$smokeTestsScriptPath'."
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{
              Path = $smokeTestsScriptPath
              Throw = $true
            }
          }
          Invoke-Pester -Configuration $pesterConfig

          Write-Output "Displaying the installed module version that was used for the smoke tests."
          Get-Module -Name '${{ needs.run-build-and-test.outputs.powerShellModuleName }}'