Add PR docs preview lifecycle via gh-pages by MariusStorhaug · Pull Request #75 · PSModule/docs

Marius Storhaug (MariusStorhaug) · 2026-07-19T23:05:12Z

Summary

Implement a full pull-request preview lifecycle for docs changes, including deploy, iterative update, and cleanup.

What changed

Reworked .github/workflows/Docs.yml to support:
- preview deploy/update for PR opened, reopened, and synchronize
- preview cleanup on PR closed
- per-PR environment name + URL (pr-preview-<number>) for clickable pipeline links
- PR comments that publish/update preview URL and update removal status on close
- gh-pages updates performed through auto-merged PRs (no direct commits to gh-pages)
Switched live docs publish flow to branch-based gh-pages updates via PR + auto-merge.
Added .github/PR-PREVIEW.md with setup expectations and required Scribbler GitHub App permissions.
Updated README.md with preview URL behavior and setup doc link.

Required repo/app setup

See .github/PR-PREVIEW.md for the complete checklist and required Scribbler permissions.

Notes

This assumes:

gh-pages already exists and is configured as the GitHub Pages source.
gh-pages branch protection enforces PR-only updates.
auto-merge is enabled for the repository.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-07-19T23:07:35Z

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Fail ❌
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Fail ❌
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

Super-linter detected linting errors

For more information, see the GitHub Actions workflow run

Powered by Super-linter

GITHUB_ACTIONS_ZIZMOR

�[1m�[94minfo[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:110:109
    �[1m�[94m|�[0m
�[1m�[94m110�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Publish-LiveDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}�[1m�[94m...�[0m
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                  �[1m�[94m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[94mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → Low
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[96mhelp[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:156:105
    �[1m�[94m|�[0m
�[1m�[94m155�[0m �[1m�[94m|�[0m         run: |
    �[1m�[94m|�[0m         �[1m�[94m---�[0m �[1m�[94mthis run block�[0m
�[1m�[94m156�[0m �[1m�[94m|�[0m           ./.github/scripts/docs/Set-ZensicalSiteUrl.ps1 -ConfigPath "$PWD/zensical.toml" -SiteUrl "${{ env.PREVIEW_URL }}"
    �[1m�[94m|�[0m                                                                                                         �[1m�[96m^^^^^^^^^^^^^^^�[0m �[1m�[96mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[94minfo[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:163:112
    �[1m�[94m|�[0m
�[1m�[94m163�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Publish-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}�[1m�[94m...�[0m
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                     �[1m�[94m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[94mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → Low
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[96mhelp[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:163:209
    �[1m�[94m|�[0m
�[1m�[94m163�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Publish-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -PullRequestNumber ${{ github.event.number }} -PreviewUrl "${{ env.PREVIEW_URL }}�[1m�[94m...�[0m
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                                                                                                                      �[1m�[96m^^^^^^^^^^^^^^^�[0m �[1m�[96mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[94minfo[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:191:112
    �[1m�[94m|�[0m
�[1m�[94m191�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Cleanup-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}�[1m�[94m...�[0m
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                     �[1m�[94m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[94mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → Low
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[96mhelp[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:191:209
    �[1m�[94m|�[0m
�[1m�[94m191�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Cleanup-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -PullRequestNumber ${{ github.event.number }} -PreviewUrl "${{ env.PREVIEW_URL }}�[1m�[94m...�[0m
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                                                                                                                      �[1m�[96m^^^^^^^^^^^^^^^�[0m �[1m�[96mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[96mhelp[template-injection]�[0m�[1m: code injection via template expansion�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:191:251
    �[1m�[94m|�[0m
�[1m�[94m191�[0m �[1m�[94m|�[0m �[1m�[94m...�[0m   run: ./.github/scripts/docs/Cleanup-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -PullRequestNumber ${{ github.event.number }} -PreviewUrl "${{ env.PREVIEW_URL }}" -EnvironmentName "${{ env.PREVIEW_ENVIRONMENT }}"
    �[1m�[94m|�[0m       �[1m�[94m---�[0m �[1m�[94mthis run block�[0m                                                                                                                                                                                                                                �[1m�[96m^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[96mmay expand into attacker-controllable code�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#template-injection�[39m

�[1m�[91merror[unpinned-uses]�[0m�[1m: unpinned action reference�[0m
  �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:84:15
   �[1m�[94m|�[0m
�[1m�[94m84�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
   �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91maction is not pinned to a hash (required by blanket policy)�[0m
   �[1m�[94m|�[0m
   �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
   �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
   �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#unpinned-uses�[39m

�[1m�[91merror[unpinned-uses]�[0m�[1m: unpinned action reference�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:134:15
    �[1m�[94m|�[0m
�[1m�[94m134�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
    �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91maction is not pinned to a hash (required by blanket policy)�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#unpinned-uses�[39m

�[1m�[91merror[unpinned-uses]�[0m�[1m: unpinned action reference�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:184:15
    �[1m�[94m|�[0m
�[1m�[94m184�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
    �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91maction is not pinned to a hash (required by blanket policy)�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mnote�[0m: this finding has an auto-fix
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#unpinned-uses�[39m

�[1m�[91merror[github-app]�[0m�[1m: dangerous use of GitHub App tokens�[0m
  �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:84:15
   �[1m�[94m|�[0m
�[1m�[94m84�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
   �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91mapp token inherits blanket installation permissions�[0m
   �[1m�[94m|�[0m
   �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
   �[1m�[94m= �[0m�[1mtip�[0m: specify at least one `permission-<name>` input to limit the token's permissions
   �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#github-app�[39m

�[1m�[91merror[github-app]�[0m�[1m: dangerous use of GitHub App tokens�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:134:15
    �[1m�[94m|�[0m
�[1m�[94m134�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
    �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91mapp token inherits blanket installation permissions�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mtip�[0m: specify at least one `permission-<name>` input to limit the token's permissions
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#github-app�[39m

�[1m�[91merror[github-app]�[0m�[1m: dangerous use of GitHub App tokens�[0m
   �[1m�[94m--> �[0m/github/workspace/.github/workflows/Docs.yml:184:15
    �[1m�[94m|�[0m
�[1m�[94m184�[0m �[1m�[94m|�[0m         uses: actions/create-github-app-token@v2
    �[1m�[94m|�[0m               �[1m�[91m^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^�[0m �[1m�[91mapp token inherits blanket installation permissions�[0m
    �[1m�[94m|�[0m
    �[1m�[94m= �[0m�[1mnote�[0m: audit confidence → High
    �[1m�[94m= �[0m�[1mtip�[0m: specify at least one `permission-<name>` input to limit the token's permissions
    �[1m�[94m= �[0m�[1mhelp�[0m: audit documentation → �[32mhttps://docs.zizmor.sh/audits/#github-app�[39m

�[32m24�[39m findings (�[1m�[93m11�[39m suppressed, �[91m10�[39m unsafe fixes�[0m): �[35m3�[39m informational, �[36m4�[39m low, �[33m0�[39m medium, �[31m6�[39m high�[32m INFO�[0m �[2mzizmor�[0m�[2m:�[0m 🌈 zizmor v1.25.2
�[32m INFO�[0m �[1maudit�[0m�[2m:�[0m �[2mzizmor�[0m�[2m:�[0m 🌈 completed /github/workspace/.github/actions/update-index/action.yml
�[32m INFO�[0m �[1maudit�[0m�[2m:�[0m �[2mzizmor�[0m�[2m:�[0m 🌈 completed /github/workspace/.github/dependabot.yml
�[32m INFO�[0m �[1maudit�[0m�[2m:�[0m �[2mzizmor�[0m�[2m:�[0m 🌈 completed /github/workspace/.github/workflows/Docs.yml

POWERSHELL


�[32;1mRuleName                           �[0m�[32;1m Severity    �[0m�[32;1m ScriptName�[0m�[32;1m Line �[0m�[32;1m Message�[0m
�[32;1m--------                           �[0m �[32;1m--------    �[0m �[32;1m----------�[0m �[32;1m---- �[0m �[32;1m-------�[0m
PSUseBOMForUnicodeEncodedFile       Warning      Cleanup-Pr       Missing BOM encoding for non-ASCII encoded file 'Clean
                                                 eviewDocs.       up-PreviewDocs.ps1'
                                                 ps1
PSUseDeclaredVarsMoreThanAssignment Warning      Cleanup-Pr 61    The variable 'deleteEnvironmentExit' is assigned but n
s                                                eviewDocs.       ever used.
                                                 ps1
PSUseDeclaredVarsMoreThanAssignment Warning      Cleanup-Pr 63    The variable 'environmentCheckExit' is assigned but ne
s                                                eviewDocs.       ver used.
                                                 ps1



�[32;1mRuleName                           �[0m�[32;1m Severity    �[0m�[32;1m ScriptName�[0m�[32;1m Line �[0m�[32;1m Message�[0m
�[32;1m--------                           �[0m �[32;1m--------    �[0m �[32;1m----------�[0m �[32;1m---- �[0m �[32;1m-------�[0m
PSUseBOMForUnicodeEncodedFile       Warning      Publish-Pr       Missing BOM encoding for non-ASCII encoded file 'Publi
                                                 eviewDocs.       sh-PreviewDocs.ps1'
                                                 ps1



�[32;1mRuleName                           �[0m�[32;1m Severity    �[0m�[32;1m ScriptName�[0m�[32;1m Line �[0m�[32;1m Message�[0m
�[32;1m--------                           �[0m �[32;1m--------    �[0m �[32;1m----------�[0m �[32;1m---- �[0m �[32;1m-------�[0m
PSUseApprovedVerbs                  Warning      Shared.ps1 51    The cmdlet 'Upsert-IssueComment' uses an unapproved ve
                                                                  rb.
PSUseShouldProcessForStateChangingF Warning      Shared.ps1 20    Function 'Set-WorkflowOutput' has verb that could chan
unctions                                                          ge system state. Therefore, the function has to suppor
                                                                  t 'ShouldProcess'.
PSProvideCommentHelp                Information  Shared.ps1 4     The cmdlet 'Invoke-Git' does not have a help comment.
PSProvideCommentHelp                Information  Shared.ps1 20    The cmdlet 'Set-WorkflowOutput' does not have a help c
                                                                  omment.
PSProvideCommentHelp                Information  Shared.ps1 35    The cmdlet 'Invoke-Gh' does not have a help comment.
PSProvideCommentHelp                Information  Shared.ps1 51    The cmdlet 'Upsert-IssueComment' does not have a help
                                                                  comment.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Marius Storhaug (MariusStorhaug) and others added 2 commits July 20, 2026 01:04

Add PR preview lifecycle workflow

4b5287d

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Document preview setup and permissions

cd5b0ac

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Marius Storhaug (MariusStorhaug) and others added 3 commits July 20, 2026 01:13

Extract docs workflow logic into scripts

1643c9e

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Switch docs deploy to app-only gh-pages pushes

5674696

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Add preview lifecycle flow diagram

bfd59cf

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add PR docs preview lifecycle via gh-pages#75

Add PR docs preview lifecycle via gh-pages#75
Marius Storhaug (MariusStorhaug) wants to merge 5 commits into
mainfrom
pr-docs-previews

Marius Storhaug (MariusStorhaug) commented Jul 19, 2026

Uh oh!

github-actions Bot commented Jul 19, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Marius Storhaug (MariusStorhaug) commented Jul 19, 2026

Summary

What changed

Required repo/app setup

Notes

Uh oh!

github-actions Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Super-linter summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Jul 19, 2026 •

edited

Loading