Publish Documentation #14
This file contains hidden or 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: Publish Documentation | |
| env: | |
| FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true | |
| on: | |
| workflow_run: | |
| workflows: ['Build and Publish Module'] | |
| types: | |
| - completed | |
| workflow_dispatch: | |
| inputs: | |
| run_id: | |
| description: Successful Build and Publish Module workflow run id that produced the docs artifact | |
| required: true | |
| type: string | |
| tag_name: | |
| description: Release tag associated with the documentation, for example v1.23.0 | |
| required: true | |
| type: string | |
| dry_run: | |
| description: Skip the git push to homotechsualdocs (test mode) | |
| required: false | |
| default: false | |
| type: boolean | |
| permissions: | |
| actions: read | |
| contents: read | |
| jobs: | |
| publish-docs: | |
| name: Publish docs to homotechsualdocs | |
| runs-on: windows-latest | |
| env: | |
| FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true | |
| if: >- | |
| github.event_name == 'workflow_dispatch' || | |
| ( | |
| github.event.workflow_run.conclusion == 'success' && | |
| github.event.workflow_run.event == 'push' | |
| ) | |
| steps: | |
| - name: Checkout HaloAPI repository | |
| uses: actions/checkout@v6 | |
| with: | |
| ref: ${{ github.event.workflow_run.head_sha || github.sha }} | |
| - name: Resolve workflow context | |
| id: context | |
| shell: pwsh | |
| env: | |
| GITHUB_EVENT_NAME_VALUE: ${{ github.event_name }} | |
| INPUT_RUN_ID_VALUE: ${{ inputs.run_id }} | |
| INPUT_TAG_NAME_VALUE: ${{ inputs.tag_name }} | |
| WORKFLOW_RUN_ID_VALUE: ${{ github.event.workflow_run.id }} | |
| WORKFLOW_RUN_HEAD_BRANCH_VALUE: ${{ github.event.workflow_run.head_branch }} | |
| run: | | |
| if ($env:GITHUB_EVENT_NAME_VALUE -eq 'workflow_dispatch') { | |
| $runId = $env:INPUT_RUN_ID_VALUE | |
| $rawTagName = $env:INPUT_TAG_NAME_VALUE | |
| if ([string]::IsNullOrWhiteSpace($rawTagName)) { | |
| Write-Error 'Input tag_name is required for workflow_dispatch.' | |
| exit 1 | |
| } | |
| $rawTagName = $rawTagName.Trim() | |
| if ($rawTagName.StartsWith('v')) { | |
| $tagName = $rawTagName | |
| } else { | |
| $tagName = "v$rawTagName" | |
| } | |
| } else { | |
| $runId = $env:WORKFLOW_RUN_ID_VALUE | |
| $tagName = $env:WORKFLOW_RUN_HEAD_BRANCH_VALUE | |
| } | |
| if ([string]::IsNullOrWhiteSpace($runId)) { | |
| Write-Error 'Workflow run id was not provided by the event payload.' | |
| exit 1 | |
| } | |
| if ($env:GITHUB_EVENT_NAME_VALUE -eq 'workflow_dispatch' -and $runId -notmatch '^\d+$') { | |
| Write-Error "Input run_id must be a numeric GitHub Actions run id. Received: '$runId'." | |
| exit 1 | |
| } | |
| if ([string]::IsNullOrWhiteSpace($tagName) -or -not $tagName.StartsWith('v')) { | |
| Write-Error "Expected a tag-based workflow run, received '$tagName'." | |
| exit 1 | |
| } | |
| "run_id=$runId" >> $env:GITHUB_OUTPUT | |
| "tag_name=$tagName" >> $env:GITHUB_OUTPUT | |
| - name: Download documentation artifact | |
| shell: pwsh | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| DOCS_RUN_ID: ${{ steps.context.outputs.run_id }} | |
| run: | | |
| $ErrorActionPreference = 'Stop' | |
| if ([string]::IsNullOrWhiteSpace($env:DOCS_RUN_ID) -or $env:DOCS_RUN_ID -notmatch '^\d+$') { | |
| Write-Error "Resolved run id is invalid: '$env:DOCS_RUN_ID'." | |
| exit 1 | |
| } | |
| gh run download "$env:DOCS_RUN_ID" --name module-docs --dir docs-artifact | |
| - name: Clone and update homotechsualdocs | |
| shell: pwsh | |
| env: | |
| GH_TOKEN: ${{ secrets.DOCS_REPO_TOKEN }} | |
| run: | | |
| $ErrorActionPreference = 'Stop' | |
| $PSNativeCommandUseErrorActionPreference = $true | |
| $sourceCommandletsPath = Get-ChildItem -Path 'docs-artifact' -Directory -Recurse | | |
| Where-Object { | |
| $_.Name -eq 'commandlets' -and | |
| $_.Parent -and | |
| $_.Parent.Name -ieq 'haloapi' | |
| } | | |
| Select-Object -First 1 -ExpandProperty FullName | |
| $sourceIndexPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath 'docs\HaloAPI\index.mdx' | |
| $sourceImagePath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath 'docs\HaloAPI\img' | |
| $hasCommandlets = -not [string]::IsNullOrWhiteSpace($sourceCommandletsPath) | |
| $hasIndex = Test-Path -Path $sourceIndexPath -PathType Leaf | |
| $hasImages = Test-Path -Path $sourceImagePath -PathType Container | |
| if (-not $hasCommandlets) { | |
| Write-Error 'Documentation artifact does not contain a docs/haloapi/commandlets directory.' | |
| exit 1 | |
| } | |
| Write-Host "Using generated documentation from: $sourceCommandletsPath" -ForegroundColor Cyan | |
| if ($hasIndex) { | |
| Write-Host "Using index doc from: $sourceIndexPath" -ForegroundColor Cyan | |
| } | |
| if ($hasImages) { | |
| Write-Host "Using image assets from: $sourceImagePath" -ForegroundColor Cyan | |
| } | |
| git -c core.autocrlf=false clone https://x-access-token:$env:GH_TOKEN@github.com/homotechsual/homotechsualdocs.git docs-repo | |
| Push-Location docs-repo | |
| try { | |
| git config core.autocrlf false | |
| git remote set-url origin https://x-access-token:$env:GH_TOKEN@github.com/homotechsual/homotechsualdocs.git | |
| $targetBranch = 'main' | |
| git fetch origin $targetBranch | |
| git checkout -B $targetBranch "origin/$targetBranch" | |
| $pushCheckSucceeded = $true | |
| try { | |
| git push --dry-run origin "HEAD:$targetBranch" | |
| } catch { | |
| $pushCheckSucceeded = $false | |
| } | |
| if (-not $pushCheckSucceeded) { | |
| Write-Error "DOCS_REPO_TOKEN cannot push to homotechsual/homotechsualdocs:$targetBranch. Ensure the token has repository write access (contents:write)." | |
| exit 1 | |
| } | |
| if (Test-Path 'docs/haloapi/commandlets') { | |
| Remove-Item -Path 'docs/haloapi/commandlets' -Recurse -Force | |
| } | |
| if ($hasImages -and (Test-Path 'docs/haloapi/img')) { | |
| Remove-Item -Path 'docs/haloapi/img' -Recurse -Force | |
| } | |
| New-Item -Path 'docs/haloapi/commandlets' -ItemType Directory -Force | Out-Null | |
| Copy-Item -Path (Join-Path -Path $sourceCommandletsPath -ChildPath '*') -Destination 'docs/haloapi/commandlets' -Recurse -Force | |
| if ($hasIndex) { | |
| Copy-Item -Path $sourceIndexPath -Destination 'docs/haloapi/index.mdx' -Force | |
| if (Test-Path 'docs/haloapi/index.md') { | |
| Remove-Item -Path 'docs/haloapi/index.md' -Force | |
| } | |
| } | |
| if ($hasImages) { | |
| Copy-Item -Path $sourceImagePath -Destination 'docs/haloapi/img' -Recurse -Force | |
| } | |
| git config user.email 'action@github.com' | |
| git config user.name 'GitHub Action' | |
| $changes = git status --porcelain | |
| if (-not $changes) { | |
| Write-Host 'No documentation changes to commit.' -ForegroundColor Yellow | |
| exit 0 | |
| } | |
| $pathsToAdd = @() | |
| $pathsToAdd += 'docs/haloapi/commandlets' | |
| if ($hasIndex) { | |
| $pathsToAdd += 'docs/haloapi/index.mdx' | |
| } | |
| if ($hasImages) { | |
| $pathsToAdd += 'docs/haloapi/img' | |
| } | |
| git add -- $pathsToAdd | |
| git commit -m "Docs update for HaloAPI ${{ steps.context.outputs.tag_name }}" | |
| if ('${{ inputs.dry_run }}' -eq 'true') { | |
| Write-Host 'Dry run: skipping git push.' -ForegroundColor Yellow | |
| } else { | |
| git push origin "HEAD:$targetBranch" | |
| } | |
| } finally { | |
| Pop-Location | |
| } |