ci: delete the staging branch when a preview pull request closes

.github/workflows/cleanup-staging.yml

@@ -0,0 +1,49 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: Cleanup staging
+
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions:
+  contents: write
+
+jobs:
+  cleanup:
+    name: Delete staging branch
+    runs-on: ubuntu-latest
+    # The preview is over once the pull request is closed, merged or not.
+    if: >-
+      startsWith(github.event.pull_request.head.ref, 'preview/') && github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Delete the site/<name>-staging branch if it exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          name="${HEAD_REF#preview/}"
+          staging_branch="site/${name}-staging"
+          if gh api "repos/${REPOSITORY}/git/ref/heads/${staging_branch}" --silent; then
+            gh api -X DELETE "repos/${REPOSITORY}/git/refs/heads/${staging_branch}"
+            echo "Deleted ${staging_branch}."
+          else
+            echo "No ${staging_branch} branch; nothing to do."
+          fi

AGENTS.md

@@ -17,4 +17,5 @@
 - Push the `preview/<name>` branch before opening the pull request. The deploy workflow publishes its build to the generated `site/<name>-staging` branch and ASF serves it at `https://asyncband-<name>.staged.apache.org/`.
 - Treat `site/<name>-staging` as deployment output. Never base work on it, commit to it directly, or use it as the pull request head branch.
 - Open the pull request from `preview/<name>` into `main` and include the staging URL in the pull request description.
+- When the pull request is closed, the cleanup workflow deletes the `site/<name>-staging` branch so deployment output does not accumulate. The staged preview may remain reachable until ASF infrastructure prunes it. To remove a stale staging branch by hand, delete its `site/<name>-staging` branch.
 - Production publishing remains separate: pushes to `main` publish through the `asf-site` branch.