From 7a5ef769482dcd2f2f677b96b35931b040cd31a2 Mon Sep 17 00:00:00 2001
From: Maksim <maxim.zinchuk@gmail.com>
Date: Tue, 12 May 2026 17:49:44 +0300
Subject: [PATCH] ci(sync-docs): add workflow_dispatch trigger
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Allow manual invocation of the docs-sync workflow without cutting a
release. Useful for:

- testing sync output against a non-main vc-docs branch (e.g. a long-
  running integration branch) before changes reach production
- re-running sync after fixing a docs-sync bug without a release cycle
- backfilling docs into a release branch

Inputs:
- target_branch (default: main) — vc-docs branch to checkout and open
  the auto-PR against
- ref_label (default: UTC timestamp) — used in the auto-PR branch name
  ('auto/sync-vc-shell-<label>') and PR title

Release-triggered runs (release: published) keep their existing
behavior: target main, label with the release tag.

Inputs are passed via env vars (not interpolated directly into shell)
to avoid command injection.
---
 .github/workflows/sync-docs.yml | 42 ++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml
index 7886a9a14..ffa2a390e 100644
--- a/.github/workflows/sync-docs.yml
+++ b/.github/workflows/sync-docs.yml
@@ -7,10 +7,20 @@ name: sync-docs
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      target_branch:
+        description: "vc-docs branch to checkout and open the PR against (defaults to main)"
+        required: false
+        default: main
+      ref_label:
+        description: "Label used in the auto-PR branch name and title (defaults to a UTC timestamp)"
+        required: false
+        default: ""
 
 jobs:
   sync:
-    if: ${{ !github.event.release.prerelease }}
+    if: ${{ github.event_name == 'workflow_dispatch' || !github.event.release.prerelease }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -19,7 +29,7 @@ jobs:
           repository: VirtoCommerce/vc-docs
           path: vc-docs
           token: ${{ secrets.VC_DOCS_BOT_TOKEN }}
-          ref: main
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.target_branch || 'main' }}
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -35,8 +45,28 @@ jobs:
       - name: Open PR
         env:
           GH_TOKEN: ${{ secrets.VC_DOCS_BOT_TOKEN }}
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_TARGET_BRANCH: ${{ inputs.target_branch }}
+          INPUT_REF_LABEL: ${{ inputs.ref_label }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
         run: |
-          BRANCH="auto/sync-vc-shell-${{ github.event.release.tag_name }}"
+          set -euo pipefail
+
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            BASE="$INPUT_TARGET_BRANCH"
+            LABEL="$INPUT_REF_LABEL"
+            if [[ -z "$LABEL" ]]; then
+              LABEL="manual-$(date -u +%Y%m%d-%H%M%S)"
+            fi
+            BRANCH="auto/sync-vc-shell-${LABEL}"
+            TITLE="docs: manual sync from vc-shell (${LABEL})"
+          else
+            BASE="main"
+            LABEL="$RELEASE_TAG"
+            BRANCH="auto/sync-vc-shell-${LABEL}"
+            TITLE="docs: sync from vc-shell@${LABEL}"
+          fi
+
           cd vc-docs
           if [[ -z "$(git status --porcelain)" ]]; then
             echo "No changes to sync."
@@ -46,11 +76,11 @@ jobs:
           git config user.email "bot@virto.dev"
           git config user.name "vc-shell-docs-bot"
           git add .
-          git commit -m "docs: sync from vc-shell@${{ github.event.release.tag_name }}"
+          git commit -m "$TITLE"
           git push origin "$BRANCH"
           gh pr create \
-            --base main \
+            --base "$BASE" \
             --head "$BRANCH" \
-            --title "docs: sync from vc-shell@${{ github.event.release.tag_name }}" \
+            --title "$TITLE" \
             --body-file ../sync-report.md \
             --label auto-generated