tip: Add example to tip #294
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: build | |
| on: | |
| push: | |
| branches: [ "main" ] | |
| paths: [ "src/**", "build/**", "deploy/**", ".github/workflows/**" ] | |
| pull_request: | |
| branches: [ "main" ] | |
| # 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: '' | |
| deploy: | |
| description: 'Deploy the build artifacts. Only has effect when not building the main branch.' | |
| required: false | |
| type: boolean | |
| default: false | |
| env: | |
| powerShellModuleName: 'tiPS' # Must match the name in the deployment workflow. | |
| powerShellModuleDirectoryPath: './src/tiPS' | |
| powerShellModuleManifestFileName: 'tiPS.psd1' | |
| deployFilesDirectoryPath: './deploy' | |
| prereleaseArtifactDirectoryPath: './artifacts/Prerelease' | |
| stableArtifactDirectoryPath: './artifacts/Stable' | |
| deployFilesArtifactDirectoryPath: './artifacts/deploy' | |
| prereleaseArtifactName: 'PrereleaseModuleArtifact' # Must match the name in the deployment workflow. | |
| stableArtifactName: 'StableModuleArtifact' # Must match the name in the deployment workflow. | |
| deployFilesArtifactName: 'DeployFilesArtifact' # Must match the name in the deployment workflow. | |
| ciVersionTagPrefix: 'ci-version-' | |
| jobs: | |
| build-and-test: | |
| runs-on: windows-latest # Use Windows agent to ensure dotnet.exe is available to build C# assemblies. | |
| 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 = $Env:powerShellModuleManifestFileName | |
| [string] $prereleaseArtifactModuleDirectoryPath = Join-Path -Path $Env:prereleaseArtifactDirectoryPath -ChildPath $moduleName | |
| [string] $stableArtifactModuleDirectoryPath = Join-Path -Path $Env:stableArtifactDirectoryPath -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.prereleaseArtifactName }} | |
| path: ${{ env.prereleaseArtifactDirectoryPath }} | |
| - name: Upload stable module artifact | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: ${{ env.stableArtifactName }} | |
| path: ${{ env.stableArtifactDirectoryPath }} | |
| - name: Upload deploy files artifact | |
| uses: actions/upload-artifact@v3 | |
| with: | |
| name: ${{ env.deployFilesArtifactName }} | |
| path: ${{ env.deployFilesArtifactDirectoryPath }} | |
| trigger-deployment: | |
| needs: build-and-test | |
| # Only trigger a deployment if this build is for a push (not a PR) and is for the default branch (main). | |
| if: inputs.deploy || (github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) | |
| uses: ./.github/workflows/deploy-powershell-module.yml | |
| secrets: inherit |