Switch docs deploy to app-only gh-pages pushes

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

Author: MariusStorhaug

.github/PR-PREVIEW.md

@@ -8,21 +8,19 @@ This repository publishes docs previews for pull requests under:
 
 1. On PR open/reopen/synchronize:
    - builds docs with preview-specific `site_url`,
-   - updates `previews/pr-<number>/` content via a PR into `gh-pages`,
-   - enables auto-merge for that `gh-pages` PR,
+   - updates `previews/pr-<number>/` content by pushing directly to `gh-pages` as the Scribbler app,
    - comments on the source PR with the preview URL,
    - reports the preview URL through a named environment (`pr-preview-<number>`).
 2. On PR close (merge or abandon):
-   - removes `previews/pr-<number>/` via a PR into `gh-pages`,
-   - enables auto-merge for that cleanup PR,
+   - removes `previews/pr-<number>/` by pushing directly to `gh-pages` as the Scribbler app,
    - deletes all preview deployments and the preview environment.
 
 ## Required repository configuration
 
 1. Ensure `gh-pages` branch exists.
 2. Configure GitHub Pages to publish from `gh-pages`.
-3. Protect `gh-pages` so direct commits are blocked and updates happen through PRs only.
-4. Allow auto-merge for PRs in this repository.
+3. Protect `gh-pages` and restrict push access so **only Scribbler bot app** can push.
+4. In the `gh-pages` branch protection/ruleset, add **Scribbler bot app** as the only actor allowed to bypass required pull requests and any required status checks for that branch.
 
 ## Scribbler GitHub App permissions
 
@@ -31,8 +29,7 @@ The app needs the following repository permissions:
 | Permission | Access | Why |
 | --- | --- | --- |
 | Metadata | Read | Required baseline for API access |
-| Contents | Read & write | Push preview/cleanup branches and update content |
-| Pull requests | Read & write | Create/update/merge PRs into `gh-pages` |
+| Contents | Read & write | Push docs and preview content directly to `gh-pages` |
 | Issues | Read & write | Post and update preview comments on PR threads |
 | Deployments | Read & write | Deactivate and delete preview deployments |
 | Administration | Read & write | Delete per-PR environments during cleanup |

.github/scripts/docs/Cleanup-PreviewDocs.ps1

@@ -9,8 +9,6 @@ param(
     [string]$PreviewUrl,
     [Parameter(Mandatory = $true)]
     [string]$EnvironmentName,
-    [Parameter(Mandatory = $true)]
-    [string]$HeadBranch,
     [string]$PagesDirectory = '_pages',
     [string]$BaseBranch = 'gh-pages'
 )
@@ -47,16 +45,7 @@ if ($clonedPages) {
     $status = (& git -C $PagesDirectory status --porcelain)
     if (-not [string]::IsNullOrWhiteSpace($status)) {
         Invoke-Git -Arguments @('-C', $PagesDirectory, 'commit', '-m', "Remove docs preview for PR #$PullRequestNumber")
-        Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', '--force-with-lease', 'origin', "HEAD:refs/heads/$HeadBranch")
-
-        $env:GH_TOKEN = $Token
-        $prNumber = Upsert-PullRequest `
-            -Repository $Repository `
-            -HeadBranch $HeadBranch `
-            -BaseBranch $BaseBranch `
-            -Title "docs(preview): cleanup PR #$PullRequestNumber" `
-            -Body "Automated cleanup for preview URL: $PreviewUrl"
-        Enable-PullRequestAutoMerge -Repository $Repository -PullRequestNumber $prNumber
+        Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', 'origin', "HEAD:refs/heads/$BaseBranch")
     }
 }
 

.github/scripts/docs/Publish-LiveDocs.ps1

@@ -6,8 +6,6 @@ param(
     [Parameter(Mandatory = $true)]
     [string]$BuildDirectory,
     [Parameter(Mandatory = $true)]
-    [string]$HeadBranch,
-    [Parameter(Mandatory = $true)]
     [string]$CommitSha,
     [string]$PagesDirectory = '_pages',
     [string]$BaseBranch = 'gh-pages'
@@ -57,16 +55,6 @@ if ([string]::IsNullOrWhiteSpace($status)) {
 }
 
 Invoke-Git -Arguments @('-C', $PagesDirectory, 'commit', '-m', "Deploy docs from $CommitSha")
-Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', '--force-with-lease', 'origin', "HEAD:refs/heads/$HeadBranch")
-
-$env:GH_TOKEN = $Token
-$prNumber = Upsert-PullRequest `
-    -Repository $Repository `
-    -HeadBranch $HeadBranch `
-    -BaseBranch $BaseBranch `
-    -Title 'docs(publish): update live docs' `
-    -Body "Automated docs publish from `$CommitSha`nLive URL: https://psmodule.io/docs/"
-Enable-PullRequestAutoMerge -Repository $Repository -PullRequestNumber $prNumber
+Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', 'origin', "HEAD:refs/heads/$BaseBranch")
 
 Set-WorkflowOutput -Name 'has_changes' -Value 'true'
-Set-WorkflowOutput -Name 'pr_number' -Value $prNumber

.github/scripts/docs/Publish-PreviewDocs.ps1

@@ -9,8 +9,6 @@ param(
     [string]$PreviewUrl,
     [Parameter(Mandatory = $true)]
     [string]$BuildDirectory,
-    [Parameter(Mandatory = $true)]
-    [string]$HeadBranch,
     [string]$PagesDirectory = '_pages',
     [string]$BaseBranch = 'gh-pages'
 )
@@ -53,16 +51,7 @@ Invoke-Git -Arguments @('-C', $PagesDirectory, 'add', '-A')
 $status = (& git -C $PagesDirectory status --porcelain)
 if (-not [string]::IsNullOrWhiteSpace($status)) {
     Invoke-Git -Arguments @('-C', $PagesDirectory, 'commit', '-m', "Update docs preview for PR #$PullRequestNumber")
-    Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', '--force-with-lease', 'origin', "HEAD:refs/heads/$HeadBranch")
-
-    $env:GH_TOKEN = $Token
-    $prNumber = Upsert-PullRequest `
-        -Repository $Repository `
-        -HeadBranch $HeadBranch `
-        -BaseBranch $BaseBranch `
-        -Title "docs(preview): PR #$PullRequestNumber" `
-        -Body "Automated preview content update for #$PullRequestNumber`nPreview URL: $PreviewUrl"
-    Enable-PullRequestAutoMerge -Repository $Repository -PullRequestNumber $prNumber
+    Invoke-Git -Arguments @('-C', $PagesDirectory, 'push', 'origin', "HEAD:refs/heads/$BaseBranch")
 }
 
 $commentBody = "<!-- docs-pr-preview -->`n✅ Preview is ready: $PreviewUrl"

.github/scripts/docs/Shared.ps1

@@ -48,40 +48,6 @@ function Invoke-Gh {
     return $output
 }
 
-function Upsert-PullRequest {
-    param(
-        [Parameter(Mandatory = $true)]
-        [string]$Repository,
-        [Parameter(Mandatory = $true)]
-        [string]$HeadBranch,
-        [Parameter(Mandatory = $true)]
-        [string]$BaseBranch,
-        [Parameter(Mandatory = $true)]
-        [string]$Title,
-        [Parameter(Mandatory = $true)]
-        [string]$Body
-    )
-
-    $existing = Invoke-Gh -Arguments @('pr', 'list', '--repo', $Repository, '--base', $BaseBranch, '--head', $HeadBranch, '--state', 'open', '--json', 'number', '--jq', '.[0].number')
-    if ([string]::IsNullOrWhiteSpace($existing)) {
-        return (Invoke-Gh -Arguments @('pr', 'create', '--repo', $Repository, '--base', $BaseBranch, '--head', $HeadBranch, '--title', $Title, '--body', $Body, '--json', 'number', '--jq', '.number'))
-    }
-
-    Invoke-Gh -Arguments @('pr', 'edit', $existing, '--repo', $Repository, '--title', $Title, '--body', $Body) | Out-Null
-    return $existing
-}
-
-function Enable-PullRequestAutoMerge {
-    param(
-        [Parameter(Mandatory = $true)]
-        [string]$Repository,
-        [Parameter(Mandatory = $true)]
-        [string]$PullRequestNumber
-    )
-
-    Invoke-Gh -Arguments @('pr', 'merge', $PullRequestNumber, '--repo', $Repository, '--squash', '--auto', '--delete-branch') | Out-Null
-}
-
 function Upsert-IssueComment {
     param(
         [Parameter(Mandatory = $true)]

.github/workflows/Docs.yml

@@ -72,8 +72,7 @@ jobs:
       name: github-pages
       url: https://psmodule.io/docs/
     permissions:
-      contents: read
-      pull-requests: write
+      contents: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -108,7 +107,7 @@ jobs:
       - name: Publish live docs
         id: publish-live
         shell: pwsh
-        run: ./.github/scripts/docs/Publish-LiveDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -BuildDirectory "$PWD/src/site" -HeadBranch "scribbler/publish/main" -CommitSha "${{ github.sha }}"
+        run: ./.github/scripts/docs/Publish-LiveDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -BuildDirectory "$PWD/src/site" -CommitSha "${{ github.sha }}"
 
   preview:
     name: Preview
@@ -119,12 +118,10 @@ jobs:
       name: pr-preview-${{ github.event.number }}
       url: ${{ steps.preview-url.outputs.url }}
     permissions:
-      contents: read
+      contents: write
       deployments: write
       issues: write
-      pull-requests: write
     env:
-      PREVIEW_PAGES_BRANCH: scribbler/preview/pr-${{ github.event.number }}
       PREVIEW_URL: https://psmodule.io/docs/previews/pr-${{ github.event.number }}/
     steps:
       - name: Checkout repository
@@ -163,19 +160,17 @@ jobs:
       - name: Publish preview docs
         id: preview-url
         shell: pwsh
-        run: ./.github/scripts/docs/Publish-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -PullRequestNumber ${{ github.event.number }} -PreviewUrl "${{ env.PREVIEW_URL }}" -BuildDirectory "$PWD/src/site" -HeadBranch "${{ env.PREVIEW_PAGES_BRANCH }}"
+        run: ./.github/scripts/docs/Publish-PreviewDocs.ps1 -Repository "${{ github.repository }}" -Token "${{ steps.app-token.outputs.token }}" -PullRequestNumber ${{ github.event.number }} -PreviewUrl "${{ env.PREVIEW_URL }}" -BuildDirectory "$PWD/src/site"
 
   preview-cleanup:
     name: Preview cleanup
     if: github.event_name == 'pull_request' && github.event.action == 'closed'
     runs-on: ubuntu-24.04
     permissions:
-      contents: read
+      contents: write
       deployments: write
       issues: write
-      pull-requests: write
     env:
-      PREVIEW_CLEANUP_BRANCH: scribbler/preview-cleanup/pr-${{ github.event.number }}
       PREVIEW_URL: https://psmodule.io/docs/previews/pr-${{ github.event.number }}/
       PREVIEW_ENVIRONMENT: pr-preview-${{ github.event.number }}
     steps:
@@ -193,4 +188,4 @@ jobs:
 
       - name: Cleanup preview resources
         shell: pwsh
-        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 }}" -HeadBranch "${{ env.PREVIEW_CLEANUP_BRANCH }}"
+        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 }}"