release-psdocs.yml

name: Release PSDocs

on:
  push:
    tags:
      - 'psdocs-v*'
  workflow_dispatch:
    inputs:
      tag:
        description: 'Tag to simulate (e.g. psdocs-v0.10.0 or psdocs-v0.10.0-preview.1)'
        required: true
        type: string
      dry_run:
        description: 'Skip Publish-Module and gh release create (validate + build only).'
        required: false
        type: boolean
        default: true

permissions: {}

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    environment: release
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0
      
      - name: Setup .NET
        uses: actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9 # v4.3.1
        with:
          dotnet-version: '8.0.x'
      
      - name: Setup PowerShell modules
        shell: pwsh
        run: |
          Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
          Install-Module -Name InvokeBuild -MinimumVersion 5.4.0 -Scope CurrentUser -Force

      - name: Parse tag and detect channel
        id: version
        shell: pwsh
        run: |
          $tagRef = if ('${{ github.event_name }}' -eq 'workflow_dispatch') { '${{ inputs.tag }}' } else { '${{ github.ref_name }}' }
          $full = $tagRef -replace '^psdocs-v', ''
          $base = ($full -split '-', 2)[0]
          $isPrerelease = $full.Contains('-')
          $channel = if ($isPrerelease) { 'preview' } else { 'stable' }
          "tag=$tagRef"          | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          "full=$full"           | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          "base=$base"           | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          "channel=$channel"     | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          "is_prerelease=$($isPrerelease.ToString().ToLower())" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
          Write-Host "Tag: $tagRef -> full=$full base=$base channel=$channel"

      - name: Validate version matches manifest
        shell: pwsh
        run: |
          $manifestPath = './packages/psdocs/src/PSDocs/PSDocs.psd1'
          $manifest = Import-PowerShellDataFile -Path $manifestPath
          $expected = '${{ steps.version.outputs.base }}'
          if ($manifest.ModuleVersion -ne $expected) {
            Write-Error "Manifest ModuleVersion '$($manifest.ModuleVersion)' does not match tag base version '$expected'. Update $manifestPath before tagging."
            exit 1
          }
          Write-Host "Manifest ModuleVersion '$($manifest.ModuleVersion)' matches tag base '$expected'."

      - name: Extract release notes
        id: notes
        shell: pwsh
        run: |
          ./scripts/extract-release-notes.ps1 `
            -ChangelogPath ./packages/psdocs/CHANGELOG.md `
            -Version '${{ steps.version.outputs.full }}' `
            -OutputPath ./release-notes.md

      - name: Build
        shell: pwsh
        working-directory: packages/psdocs
        run: |
          Invoke-Build Build -File ./pipeline.build.ps1 -Build '${{ steps.version.outputs.full }}'
      
      - name: Publish to PSGallery
        if: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != true }}
        shell: pwsh
        env:
          PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
        run: |
          Publish-Module -Path packages/psdocs/out/modules/PSDocs -NuGetApiKey $env:PSGALLERY_API_KEY
      
      - name: Create GitHub Release
        if: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != true }}
        env:
          GH_TOKEN: ${{ github.token }}
          PRERELEASE_FLAG: ${{ steps.version.outputs.is_prerelease == 'true' && '--prerelease' || '' }}
        run: |
          gh release create "${{ steps.version.outputs.tag }}" \
            --title "PSDocs v${{ steps.version.outputs.full }}" \
            --notes-file ./release-notes.md \
            $PRERELEASE_FLAG

      - name: Dry-run summary
        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
        shell: pwsh
        run: |
          Write-Host '=== DRY RUN ==='
          Write-Host "Would publish PSDocs v${{ steps.version.outputs.full }} (channel=${{ steps.version.outputs.channel }}) to PSGallery."
          Write-Host "Would create GitHub Release for tag ${{ steps.version.outputs.tag }}."
          Write-Host '--- release notes ---'
          Get-Content ./release-notes.md