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:

  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:
      powerShellModuleName:
        description: 'The name of the PowerShell module being built.'
        value: ${{ jobs.build-and-test.outputs.powerShellModuleName }}
      prereleaseModuleArtifactName:
        description: 'The name of the prerelease module artifact created by the build.'
        value: ${{ jobs.build-and-test.outputs.prereleaseModuleArtifactName }}
      stableModuleArtifactName:
        description: 'The name of the stable module artifact created by the build.'
        value: ${{ jobs.build-and-test.outputs.stableModuleArtifactName }}
      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'
  prereleaseModuleArtifactName: 'PrereleaseModuleArtifact'
  prereleaseModuleArtifactDirectoryPath: './artifacts/Prerelease'
  stableModuleArtifactName: 'StableModuleArtifact'
  stableModuleArtifactDirectoryPath: './artifacts/Stable'
  deployFilesArtifactName: 'DeployFilesArtifact'
  deployFilesArtifactDirectoryPath: './artifacts/deploy'
  ciVersionTagPrefix: 'ci-version-'

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 }}
      prereleaseModuleArtifactName: ${{ env.prereleaseModuleArtifactName }}
      stableModuleArtifactName: ${{ env.stableModuleArtifactName }}
      deployFilesArtifactName: ${{ env.deployFilesArtifactName }}
    steps:
      - name: Checkout the repo source code
        uses: actions/checkout@v3

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

      - name: Display PowerShell version being used
        shell: pwsh
        run: $PSVersionTable

      - name: Build the C# assemblies
        shell: pwsh
        run: ./build/Build-CSharpAssemblies.ps1 -Force

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

      - name: Run PowerShell linter with PSScriptAnalyzer
        shell: pwsh
        run: Invoke-ScriptAnalyzer -Path . -Recurse -EnableExit

      - 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-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: Determine new version from Git tag and set environment variables
        shell: pwsh
        run: |
          [string] $ciVersionTagPrefix = $Env:ciVersionTagPrefix
          [string] $ciTagSearchPattern = $ciVersionTagPrefix + '*'

          Write-Output "Fetching all git tags, in case they were not included with the git checkout."
          & git fetch --tags origin

          Write-Output "Searching for CI version git tag by using search pattern '$ciTagSearchPattern'."
          [string] $ciVersionTag = (& git tag --list $ciTagSearchPattern)
          Write-Output "CI version git tag is '$ciVersionTag'."

          if ([string]::IsNullOrWhiteSpace($ciVersionTag))
          {
            Write-Output "No CI version git tag was found. Assuming this is the first CI build and setting the version number to 0.0.0."
            $ciVersionTag = $ciVersionTagPrefix + '0.0.0'
          }

          [string] $previousVersionNumber = $ciVersionTag -replace $ciVersionTagPrefix, ''

          Write-Output "Previous version number was '$previousVersionNumber'. Determining what the new version number should be."
          [string] $newVersionNumber = '${{ inputs.versionNumber }}'
          if ([string]::IsNullOrWhiteSpace($newVersionNumber))
          {
            Write-Output "No version number was provided. Incrementing the previous version number."
            $currentVersion = [System.Version]::new($previousVersionNumber)
            $newVersion = [System.Version]::new($currentVersion.Major, $currentVersion.Minor, $currentVersion.Build + 1)
            $newVersionNumber = $newVersion.ToString()
          }
          else
          {
            Write-Output "Version number '$newVersionNumber' was provided. Using it as the new version number."
          }

          Write-Output "Setting new environment variables 'NewVersionNumber=$newVersionNumber' and 'PreviousCiVersionTag=$ciVersionTag'."
          "NewVersionNumber=$newVersionNumber" | Out-File -FilePath $Env:GITHUB_ENV -Encoding utf8 -Append
          "PreviousCiVersionTag=$ciVersionTag" | Out-File -FilePath $Env:GITHUB_ENV -Encoding utf8 -Append

      - name: Create Stable and Prerelease module artifacts
        shell: pwsh
        run: |
          function Replace-TextInFile(
            [ValidateScript({Test-Path $_ -PathType Leaf})]
            [string]$filePath,
            [string]$textToReplace,
            [string]$replacementText)
          {
            $fileContents = Get-Content -Path $filePath -Raw
            $newFileContents = $fileContents.Replace($textToReplace, $replacementText)
            Set-Content -Path $filePath -Value $newFileContents
          }

          Write-Output "Reading in environment variables."
          [string] $moduleName = $Env:powerShellModuleName
          [string] $moduleDirectoryPath = $Env:powerShellModuleDirectoryPath
          [string] $moduleManifestFileName = $moduleName + '.psd1'
          [string] $prereleaseArtifactModuleDirectoryPath = Join-Path -Path $Env:prereleaseModuleArtifactDirectoryPath -ChildPath $moduleName
          [string] $stableArtifactModuleDirectoryPath = Join-Path -Path $Env:stableModuleArtifactDirectoryPath -ChildPath $moduleName

          Write-Output "Reading in dynamic environment variables."
          [string] $newVersionNumber = $Env:NewVersionNumber

          Write-Output "Determining what the module manifest file paths should be."
          [string] $manifestFilePath = Join-Path -Path $moduleDirectoryPath -ChildPath $moduleManifestFileName
          [string] $prereleaseManifestFilePath = Join-Path -Path $prereleaseArtifactModuleDirectoryPath -ChildPath $moduleManifestFileName
          [string] $stableManifestFilePath = Join-Path -Path $stableArtifactModuleDirectoryPath -ChildPath $moduleManifestFileName

          Write-Output "Retrieving the module manifest's current version number line from '$manifestFilePath' so it can be updated."
          $manifestVersionNumberRegexPattern = "(?i)ModuleVersion = '(?<Version>.*?)'"
          $manifestVersionNumberMatches =
            Select-String -Path $manifestFilePath -Pattern $manifestVersionNumberRegexPattern |
            Select-Object -First 1
          if ($manifestVersionNumberMatches.Matches.Count -le 0 -or
            !$manifestVersionNumberMatches.Matches[0].Success)
          {
            throw "Could not find the manifest's current version number."
          }

          $manifestVersionNumberMatch = $manifestVersionNumberMatches.Matches[0]
          $currentManifestVersionNumber = $manifestVersionNumberMatch.Groups['Version'].Value
          $currentManifestVersionNumberLine = $manifestVersionNumberMatch.Value

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

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

          # Prerelease version numbers can only contain 'a-zA-Z0-9' characters.
          [string] $dateTime = (Get-Date -Format 'yyyyMMddTHHmmss')
          [string] $truncatedCommitSha = $Env:GITHUB_SHA.Substring(0, 7)
          [string] $prereleaseVersionNumberPostfix = 'ci' + $dateTime + 'SHA' + $truncatedCommitSha

          Write-Output "Updating the prerelease manifest's version number from '$currentManifestVersionNumber' to '$newVersionNumber$prereleaseVersionNumberPostfix'."
          Replace-TextInFile -filePath $prereleaseManifestFilePath -textToReplace $currentManifestVersionNumberLine -replacementText "ModuleVersion = '$newVersionNumber'"
          Replace-TextInFile -filePath $prereleaseManifestFilePath -textToReplace "# Prerelease = ''" -replacementText "Prerelease = '$prereleaseVersionNumberPostfix'"

          Write-Output "Updating the stable manifest's version number from '$currentManifestVersionNumber' to '$newVersionNumber'."
          Replace-TextInFile -filePath $stableManifestFilePath -textToReplace $currentManifestVersionNumberLine -replacementText "ModuleVersion = '$newVersionNumber'"

      - 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: Update CI version tag and set 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] $previousCiVersionTag = $Env:PreviousCiVersionTag
          [string] $newVersionNumber = $Env:NewVersionNumber
          [string] $newCiVersionTag = $Env:ciVersionTagPrefix + $newVersionNumber
          [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

          Write-Output "Removing the previous CI version tag '$previousCiVersionTag'."
          & git tag -d $previousCiVersionTag
          & git push origin --delete $previousCiVersionTag

          Write-Output "Creating new CI version tag '$newCiVersionTag'."
          & git tag $newCiVersionTag
          & git push origin $newCiVersionTag

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

      - name: Upload prerelease module artifact
        uses: actions/upload-artifact@v3
        with:
          name: ${{ env.prereleaseModuleArtifactName }}
          path: ${{ env.prereleaseModuleArtifactDirectoryPath }}

      - name: Upload stable module artifact
        uses: actions/upload-artifact@v3
        with:
          name: ${{ env.stableModuleArtifactName }}
          path: ${{ env.stableModuleArtifactDirectoryPath }}

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