build-and-test-powershell-module.yml

name: build

on:
  pull_request:
    branches: main

  # Allows you to run this workflow manually from the Actions tab.
  workflow_dispatch:

  # Allows the deployment workflow to call this workflow.
  workflow_call:
    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: ''
    # Outputs required by the deployment workflow.
    outputs:
      powerShellModuleName:
        description: 'The name of the PowerShell module being built.'
        value: ${{ jobs.build-and-test.outputs.powerShellModuleName }}
      stableVersionNumber:
        description: 'The stable version number of the PowerShell module created by the build.'
        value: ${{ jobs.build-and-test.outputs.stableVersionNumber }}
      prereleaseVersionNumber:
        description: 'The full prerelease version number of the PowerShell module created by the build.'
        value: ${{ jobs.build-and-test.outputs.prereleaseVersionNumber }}
      prereleaseVersionLabel:
        description: 'The prerelease label of the PowerShell module created by the build.'
        value: ${{ jobs.build-and-test.outputs.prereleaseVersionLabel }}
      moduleArtifactName:
        description: 'The name of the module artifact created by the build.'
        value: ${{ jobs.build-and-test.outputs.moduleArtifactName }}
      deployFilesArtifactName:
        description: 'The name of the deploy files artifact created by the build.'
        value: ${{ jobs.build-and-test.outputs.deployFilesArtifactName }}

env:
  powerShellModuleName: 'tiPS'
  powerShellModuleDirectoryPath: './src/tiPS'
  deployFilesDirectoryPath: './deploy'
  moduleArtifactName: 'ModuleArtifact'
  moduleArtifactDirectoryPath: './artifacts/Module'
  deployFilesArtifactName: 'DeployFilesArtifact'
  deployFilesArtifactDirectoryPath: './artifacts/deploy'

jobs:
  build-and-test:
    runs-on: windows-latest # Use Windows agent to ensure dotnet.exe is available to build C# assemblies.
    outputs:
      powerShellModuleName: ${{ env.powerShellModuleName }}
      stableVersionNumber: ${{ steps.version-number.outputs.majorMinorPatch }}
      prereleaseVersionNumber: ${{ steps.version-number.outputs.majorMinorPatch }}-${{ steps.version-number.outputs.prereleaseLabel }}
      prereleaseVersionLabel: ${{ steps.version-number.outputs.prereleaseLabel}}
      moduleArtifactName: ${{ env.moduleArtifactName }}
      deployFilesArtifactName: ${{ env.deployFilesArtifactName }}
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history so that GitVersion can determine the version number.

      - name: Display PowerShell version and OS details in case needed for troubleshooting
        shell: pwsh
        run: $PSVersionTable

      - name: Run spellcheck
        uses: streetsidesoftware/cspell-action@v5

      - name: Install GitVersion
        uses: gittools/actions/gitversion/setup@v0
        with:
          versionSpec: '5.x'

      - name: Get git metadata used to determine new version number
        id: git-version
        uses: gittools/actions/gitversion/execute@v0

      - name: Determine the new version number
        id: version-number
        shell: pwsh
        run: |
          [string] $newVersionNumber = '${{ steps.git-version.outputs.majorMinorPatch }}'
          [string] $prereleaseLabel = '${{ steps.git-version.outputs.preReleaseTag }}'

          [string] $manuallyProvidedVersionNumber = '${{ inputs.versionNumber }}'
          if (-not [string]::IsNullOrWhiteSpace($manuallyProvidedVersionNumber)) {
            Write-Output "Using manually provided version number '$manuallyProvidedVersionNumber'."
            $newVersionNumber = $manuallyProvidedVersionNumber
          }

          # The preReleaseTag is empty when building the default branch, so manually create a prerelease version number if needed.
          if ([string]::IsNullOrWhiteSpace($prereleaseLabel)) {
            [string] $dateTime = (Get-Date -Format 'yyyyMMddTHHmmss')
            $prereleaseLabel = 'CI' + $dateTime + 'SHA' + '${{ steps.git-version.outputs.shortSha }}'
          }
          # PowerShell prerelease labels can only contain the characters 'a-zA-Z0-9', so sanitize it if needed.
          $newVersionNumberPrereleaseLabel = $prereleaseLabel -replace '[^a-zA-Z0-9]', ''

          Write-Output "Setting step output variables 'majorMinorPatch=$newVersionNumber' and 'prereleaseLabel=$newVersionNumberPrereleaseLabel'."
          "majorMinorPatch=$newVersionNumber" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append
          "prereleaseLabel=$newVersionNumberPrereleaseLabel" | Out-File -FilePath $Env:GITHUB_OUTPUT -Encoding utf8 -Append

      - name: Build the C# assemblies
        shell: pwsh
        run: ./build/Build-CSharpAssemblies.ps1 -VersionNumber '${{ steps.git-version.outputs.assemblySemVer }}' -Force

      - name: Generate PowerShellTips.json file
        shell: pwsh
        run: ./build/Convert-PowerShellTipFilesToJsonFile.ps1

      # Suppress rules if needed: https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/using-scriptanalyzer
      - name: Run PowerShell linter with PSScriptAnalyzer
        shell: pwsh
        run: Invoke-ScriptAnalyzer -Path . -Recurse -EnableExit

      - name: Run Pester tests on Windows PowerShell to ensure backward compatibility
        shell: powershell
        run: |
          Write-Output "Pester version being used:"
          Import-Module -Name Pester
          Get-Module -Name Pester

          Write-Output "Running all Pester tests in the repo:"
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{ Throw = $true }
            TestResult = @{
              Enabled = $true
              OutputPath = 'test-results-windows-powershell-nunit.xml'
            }
            CodeCoverage = @{ Enabled = $false }
          }
          Invoke-Pester -Configuration $pesterConfig

      - name: Run Pester tests and generate code coverage report
        shell: pwsh
        run: |
          Write-Output "Pester version being used:"
          Import-Module -Name Pester
          Get-Module -Name Pester

          Write-Output "Running all Pester tests in the repo:"
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{ Throw = $true }
            TestResult = @{
              Enabled = $true
              OutputPath = 'test-results-pwsh-nunit.xml'
            }
            CodeCoverage = @{
              Enabled = $true
              OutputPath = 'code-coverage-jacoco.xml'
              Path = 'src/' # Only include code coverage for the module's source code, not build or deployment scripts.
            }
          }
          Invoke-Pester -Configuration $pesterConfig

      - name: Add code coverage report to PR
        # Adding the code coverage report is not supported for manual workflow runs.
        if: github.event_name != 'workflow_dispatch'
        uses: madrapps/jacoco-report@v1.6.1
        with:
          paths: code-coverage-jacoco.xml
          token: ${{ secrets.GITHUB_TOKEN }}
          min-coverage-overall: 60
          min-coverage-changed-files: 60

      - name: Build the concatenated psm1 file
        shell: pwsh
        run: ./build/Build-Psm1File.ps1 -DeleteSourceFilesAfterImport

      - name: Run Pester tests again to ensure the concatenated psm1 file works as expected
        shell: pwsh
        run: |
          Write-Output "Pester version being used:"
          Import-Module -Name Pester
          Get-Module -Name Pester

          Write-Output "Running all Pester tests in the repo:"
          $pesterConfig = New-PesterConfiguration @{
            Output = @{ Verbosity = 'Detailed' }
            Run = @{ Throw = $true }
            TestResult = @{ Enabled = $false }
            CodeCoverage = @{ Enabled = $false }
          }
          Invoke-Pester -Configuration $pesterConfig

      - name: Create the module artifact
        shell: pwsh
        run: |
          Write-Output "Reading in environment variables."
          [string] $moduleName = $Env:powerShellModuleName
          [string] $moduleDirectoryPath = $Env:powerShellModuleDirectoryPath
          [string] $moduleManifestFileName = $moduleName + '.psd1'
          [string] $moduleManifestFilePath = Join-Path -Path $moduleDirectoryPath -ChildPath $moduleManifestFileName
          [string] $moduleArtifactDirectoryPath = Join-Path -Path $Env:moduleArtifactDirectoryPath -ChildPath $moduleName
          [string] $newVersionNumber = '${{ steps.version-number.outputs.majorMinorPatch}}'

          Write-Output "Updating the version number of the module manifest file '$moduleManifestFilePath' to '$newVersionNumber'."
          Update-ModuleManifest -Path $moduleManifestFilePath -ModuleVersion $newVersionNumber

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

          Write-Output "Copying the module files to the module artifact directory '$moduleArtifactDirectoryPath'."
          Copy-Item -Path $moduleDirectoryPath -Destination $moduleArtifactDirectoryPath -Exclude '*.Tests.ps1' -Recurse -Force

      - name: Create deploy files artifact
        shell: pwsh
        run: |
          [string] $deployFilesDirectoryPath = $Env:deployFilesDirectoryPath
          [string] $deployFilesArtifactDirectoryPath = $Env:deployFilesArtifactDirectoryPath

          Write-Output "Copying the deployment files '$deployFilesDirectoryPath' to the deployment artifact directory '$deployFilesArtifactDirectoryPath'."
          Copy-Item -Path $deployFilesDirectoryPath -Destination $deployFilesArtifactDirectoryPath -Recurse -Force

      - name: Set the new version tag
        # Only run this step if we are doing a push (not a PR) to the default branch (e.g. main).
        if: github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
        shell: pwsh
        run: |
          [string] $newVersionNumber = '${{ steps.version-number.outputs.majorMinorPatch}}'
          [string] $newVersionTag = "v$newVersionNumber"

          # To avoid a 403 error on 'git push', ensure you have granted your GitHub Actions workflow read/write permission.
          # In your GitHub repo: Settings > Actions > General > Workflow permissions > Read and write permissions
          # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-default-github_token-permissions

          Write-Output "Tagging commit with new version tag '$newVersionTag'."
          & git tag $newVersionTag
          & git push origin $newVersionTag

      - name: Upload module artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.moduleArtifactName }}
          path: ${{ env.moduleArtifactDirectoryPath }}

      - name: Upload deploy files artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ env.deployFilesArtifactName }}
          path: ${{ env.deployFilesArtifactDirectoryPath }}