actions: update the documentation with context examples

.forgejo/workflows/actions.yml

@@ -1,3 +1,15 @@
+#
+#
+# https://code.forgejo.org/forgejo/end-to-end/settings/actions
+#
+# secrets.CASCADE_DOCS_ORIGIN_TOKEN
+#   https://code.forgejo.org/forgejo-ci scope write:issue, read:repository, read:user
+# vars.CASCADE_DOCS_DESTINATION_DOER
+#   forgejo-cascading-pr (https://codeberg.org/forgejo-cascading-pr)
+# secrets.CASCADE_DOCS_DESTINATION_TOKEN
+#   https://codeberg.org/forgejo-cascading-pr scope write:issue, write:repository, read:user
+#
+
 on:
   pull_request:
   push:
@@ -11,6 +23,7 @@ jobs:
       matrix:
         info:
           - version: v1.22
+            branch: next
             forgejo: https://codeberg.org
             repo: forgejo-experimental/forgejo
             tests: ${{ vars.V1_22_TESTS }}
@@ -29,7 +42,9 @@ jobs:
         with:
           install-only: true
 
-      - if: matrix.info.tests != 'none'
+      - name: run
+        id: run
+        if: matrix.info.tests != 'none'
         shell: bash
         run: |
           set -x
@@ -41,3 +56,22 @@ jobs:
           chown forgejo $DIR /srv
 
           su -c "actions/run.sh $binary $full_version ${{ matrix.info.version }} ${{ matrix.info.tests }}" forgejo
+
+          echo full_version="$full_version" >> $GITHUB_OUTPUT
+
+      - name: update documentation
+        if: matrix.info.version == 'v1.21' && matrix.info.tests != 'none' && github.ref == 'refs/heads/main'
+        uses: https://code.forgejo.org/actions/cascading-pr@v1
+        with:
+          origin-url: ${{ env.GITHUB_SERVER_URL }}
+          origin-repo: ${{ github.repository }}
+          origin-token: ${{ secrets.CASCADE_DOCS_ORIGIN_TOKEN }}
+          origin-ref: refs/heads/main
+          destination-url: https://codeberg.org
+          destination-fork-repo: ${{ vars.CASCADE_DOCS_DESTINATION_DOER }}/docs
+          destination-repo: forgejo/docs
+          destination-branch: ${{ matrix.info.branch || matrix.info.version }}
+          destination-token: ${{ secrets.CASCADE_DOCS_DESTINATION_TOKEN }}
+          update: .forgejo/cascading-docs
+        env:
+          VERSION: "${{ steps.run.outputs.full_version }}"