Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Keeps the SHA-pinned GitHub Actions in .github/workflows current.
# Dependabot updates both the commit SHA and the trailing "# vX.Y.Z" comment.
#
# PowerShell Gallery modules are NOT covered by Dependabot. The Pester, PSScriptAnalyzer and platyPS
# versions are pinned in the env: block of .github/workflows/ci.yml; bump them there by hand.
# PowerShell Gallery modules are NOT covered by Dependabot. The build, test and docs tools are pinned to
# exact versions in RequiredModules.psd1; raise them there by hand.
version: 2
updates:
- package-ecosystem: github-actions
Expand Down
60 changes: 35 additions & 25 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,24 @@
# Every job calls Tests/test-local.ps1 for one stage, so `./Tests/test-local.ps1` locally runs the same checks.
# The build job (Sampler/ModuleBuilder) produces output/<ModuleName>/<version>/; the Pester jobs test that built
# module under both Windows PowerShell 5.1 and PowerShell 7, because the module must work on both.
#
# Tools (Pester, PSScriptAnalyzer, platyPS and the build modules) are downloaded from the PowerShell Gallery once,
# by the build job, at the exact versions in RequiredModules.psd1. The other jobs get that folder as an artifact,
# and test-local.ps1 imports each tool at its pinned version. No job installs a tool by itself.
#
# Publishing to the PowerShell Gallery is done by release.yml (see AGENTS.md). No module name is hard-coded here.
#
# Security note: never interpolate ${{ github.* }} / ${{ matrix.* }} values directly into a
# run: script. Pass them through env: instead.

name: CI

# Topic branches are covered by their pull request; listing them under push too would run every job twice.
# Branches are covered by their pull request; listing them under push too would run every job twice.
# Use "Run workflow" (workflow_dispatch) to test a branch that has no PR yet.
on:
push:
branches:
- master
- 'release/**'
pull_request:
branches:
- master
Expand All @@ -26,14 +30,11 @@ on:
permissions:
contents: read

# A newer push to a pull request cancels the older run. Other runs get a group of their own (the commit), so a
# run on master is never cancelled or replaced while it waits, and every merged commit gets a result.
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

env:
PESTER_VERSION: 5.7.1
PSSA_VERSION: 1.24.0
PLATYPS_VERSION: 0.14.2
group: ci-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
Expand Down Expand Up @@ -62,6 +63,14 @@ jobs:
if-no-files-found: error
retention-days: 7

- name: Upload Required Modules
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: required-modules
path: output/RequiredModules/
if-no-files-found: error
retention-days: 7 # as long as module-build: a job re-run later still needs it

test:
name: Pester (${{ matrix.name }})
needs: build
Expand Down Expand Up @@ -90,14 +99,11 @@ jobs:
name: module-build
path: output

- name: Install Pester
run: |
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072
if (-not (Get-PackageProvider -ListAvailable -Name NuGet -ErrorAction SilentlyContinue)) {
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Scope CurrentUser -Force | Out-Null
}
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name Pester -RequiredVersion $env:PESTER_VERSION -Scope CurrentUser -Force -SkipPublisherCheck
- name: Download Required Modules
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: required-modules
path: output/RequiredModules

- name: Run Pester against the built module
env:
Expand All @@ -115,6 +121,7 @@ jobs:

analyze:
name: PSScriptAnalyzer
needs: build
runs-on: windows-latest
defaults:
run:
Expand All @@ -126,16 +133,18 @@ jobs:
with:
persist-credentials: false

- name: Install PSScriptAnalyzer
run: |
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name PSScriptAnalyzer -RequiredVersion $env:PSSA_VERSION -Scope CurrentUser -Force
- name: Download Required Modules
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: required-modules
path: output/RequiredModules

- name: Analyze source
run: ./Tests/test-local.ps1 -Stage Analyze

docs:
name: Docs drift
needs: build
runs-on: windows-latest
defaults:
run:
Expand All @@ -147,10 +156,11 @@ jobs:
with:
persist-credentials: false

- name: Install platyPS
run: |
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
Install-Module -Name platyPS -RequiredVersion $env:PLATYPS_VERSION -Scope CurrentUser -Force
- name: Download Required Modules
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: required-modules
path: output/RequiredModules

- name: Regenerate help and check for drift
run: ./Tests/test-local.ps1 -Stage Docs
101 changes: 83 additions & 18 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,14 @@
# package on both editions (Build/Test-ReleasePackage.ps1)
# 4. publish Publish-PSResource -NupkgPath of that exact .nupkg, after checking its SHA256. Runs in the
# "psgallery" environment, which holds the PSGALLERY_API_KEY secret and should require the owner's
# approval.
# 5. release GitHub Release for the tag, with the CHANGELOG section as its notes
# approval. If the version is already on the Gallery (a re-run after the upload went through), it
# uploads nothing and succeeds.
# 5. release GitHub Release for the tag, with the CHANGELOG section as its notes, then a wait until the
# Gallery lists the version (a warning, never a failure)
#
# A Gallery version can never be replaced, so everything that can fail is checked before step 4.
# Re-running: "Re-run failed jobs" is always safe. "Re-run all jobs" after a successful publish stops at step 1,
# because the version then exists. See "Releasing" in AGENTS.md.
# No module name is hard-coded here.
#
# Security note: never interpolate ${{ github.* }} values directly into a run: script. Use env: or the
Expand Down Expand Up @@ -45,6 +49,9 @@ jobs:
defaults:
run:
shell: pwsh
outputs:
# Passed to the publish job apart from the artifact, so the file and its expected hash do not travel together
sha256: ${{ steps.package.outputs.sha256 }}

steps:
- name: Checkout Repository
Expand All @@ -70,9 +77,11 @@ jobs:
run: ./Tests/test-local.ps1

- name: Package and check the package
id: package
run: |
$Release = Join-Path 'output' 'release'
$Package = ./Build/Test-ReleasePackage.ps1 -PackagePath $Release
"sha256=$($Package.PackageSha256)" | Add-Content -Path $env:GITHUB_OUTPUT
Move-Item -Path 'release-notes.md' -Destination $Release
$Package | Select-Object ModuleName, Version, Functions, PackageName, PackageSha256 |
ConvertTo-Json | Set-Content -Path (Join-Path $Release 'release.json')
Expand Down Expand Up @@ -122,32 +131,61 @@ jobs:
- name: Publish
env:
PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
EXPECTED_SHA256: ${{ needs.build.outputs.sha256 }}
run: |
if (-not $env:PSGALLERY_API_KEY) { throw 'The PSGALLERY_API_KEY secret is not set in the psgallery environment.' }
if (-not $env:EXPECTED_SHA256) { throw 'The build job reported no package hash.' }
$Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json
if ("v$($Release.Version)" -ne $env:GITHUB_REF_NAME) {
throw "The built version $($Release.Version) does not match tag $env:GITHUB_REF_NAME."
}
# Publish the .nupkg the build job checked, and only if it is byte-for-byte that file
# Publish the .nupkg the build job checked: its hash must be the one that job reported
$Package = Join-Path 'release' $Release.PackageName
$Hash = (Get-FileHash -Path $Package -Algorithm SHA256).Hash
if ($Hash -ne $Release.PackageSha256) {
throw "The package hash $Hash does not match the checked package $($Release.PackageSha256)."
if ($Hash -ne $env:EXPECTED_SHA256) {
throw "The package hash $Hash does not match the checked package $env:EXPECTED_SHA256."
}
Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY
Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)"

- name: Wait until the Gallery lists the version
run: |
$Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json
foreach ($Attempt in 1..20) {
$Found = Find-PSResource -Name $Release.ModuleName -Version $Release.Version -Repository PSGallery `
-ErrorAction SilentlyContinue
if ($Found) { Write-Host "The Gallery lists $($Found.Name) $($Found.Version)"; exit 0 }
Start-Sleep -Seconds 30
# Is the version already on the Gallery? 200 = yes, 404 = no, anything else = stop. It is there when
# this job is re-run after an upload that went through (the build job refuses a version that exists
# before it builds). Uploading again would only fail, so skip it and let the release be created.
$Uri = "https://www.powershellgallery.com/api/v2/Packages(Id='$($Release.ModuleName)',Version='$($Release.Version)')"
try {
Invoke-WebRequest -Uri $Uri -UseBasicParsing | Out-Null
$Exists = $true
} catch {
$Status = 0
if ($_.Exception.Response) { $Status = [int]$_.Exception.Response.StatusCode }
if ($Status -ne 404) { throw "Could not check the PowerShell Gallery (HTTP $Status): $($_.Exception.Message)" }
$Exists = $false
}
$AlreadyThere = "Already on the Gallery: $($Release.ModuleName) $($Release.Version). Nothing was uploaded in this run."
$IsRerun = [int]$env:GITHUB_RUN_ATTEMPT -gt 1
if ($Exists) {
# On the first attempt nothing in this run can have uploaded it, so it came from somewhere else
# and is not the package this run tested
if (-not $IsRerun) {
throw "$($Release.ModuleName) $($Release.Version) appeared on the PowerShell Gallery after the build job checked, and this run did not upload it."
}
Write-Warning $AlreadyThere
$AlreadyThere | Add-Content -Path $env:GITHUB_STEP_SUMMARY
exit 0
}
# The publish itself succeeded; the Gallery can take longer to validate and index a package.
Write-Warning 'The Gallery does not list the version yet. Check the package page before announcing it.'

try {
Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY -ErrorAction Stop
} catch {
# A version the Gallery is still validating can answer 404 above; a re-run then gets a conflict
# here, which means the earlier attempt's upload went through
if ($IsRerun -and "$($_.Exception.Message)" -match '409|Conflict|already exists') {
Write-Warning "$AlreadyThere ($($_.Exception.Message))"
$AlreadyThere | Add-Content -Path $env:GITHUB_STEP_SUMMARY
exit 0
}
throw
}
Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)"
"Published $($Release.ModuleName) $($Release.Version), SHA256 $Hash" | Add-Content -Path $env:GITHUB_STEP_SUMMARY

github-release:
name: Create the GitHub Release
Expand All @@ -164,8 +202,35 @@ jobs:
name: release
path: release

# Safe to re-run: a published release is left as it is, and a draft for the tag is published with the notes
- name: Create Release
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md
run: |
draft=$(gh release view "$GITHUB_REF_NAME" --json isDraft --jq .isDraft 2> /dev/null || echo none)
if [ "$draft" = "false" ]; then
echo "Release $GITHUB_REF_NAME already exists."
elif [ "$draft" = "true" ]; then
gh release edit "$GITHUB_REF_NAME" --verify-tag --draft=false --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md
else
gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md
fi

# Last, and never a failure: the upload succeeded, but the Gallery can take a while to validate and list it
- name: Wait until the Gallery lists the version
shell: pwsh
run: |
try {
$Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json
foreach ($Attempt in 1..20) {
$Found = Find-PSResource -Name $Release.ModuleName -Version $Release.Version -Repository PSGallery `
-ErrorAction SilentlyContinue
if ($Found) { Write-Host "The Gallery lists $($Found.Name) $($Found.Version)"; exit 0 }
Start-Sleep -Seconds 30
}
Write-Warning 'The Gallery does not list the version yet. Check the package page before announcing it.'
} catch {
Write-Warning "Could not ask the Gallery for the version: $($_.Exception.Message)"
}
exit 0
Loading
Loading