fix(ci): isolate v3 docs publishing and skip unrelated docs-only checks (#10612)

.github/V3-MIGRATION.md

@@ -25,7 +25,8 @@ The source workflows already target the new OSS repository and public npm. Repos
 - Branch protection and required checks refer to the `v3-` workflows and allow the configured release bot's squash merges and synchronization into `v3-develop` and `v3-main`.
 - Default-branch dispatch entries are present on `main`, Actions is enabled, and the beta and stable workflows pass with `dry_run: true` before an actual publish. Pro dispatch input descriptions on `main` should name the OSS `v3-develop` / `v3-main` branches; their current descriptions still use the former OSS names, although dispatch already selects `v3-develop`.
 - `RELEASE_RESULT_FEISHU_WEBHOOK_URL` is configured if internal release notifications are required.
-- Site and UI Library deployment stay gated by `V3_ASSET_DEPLOY_ENABLED`. Confirm the `DOCS_ALI_OSS_*` settings and `DOCS_ALI_CDN_DOMAIN`, then enable the gate when the deployment destination is ready.
+- Documentation deployment uses the independent repository secrets `V3_DOCS_ALI_OSS_BUCKET`, `V3_DOCS_ALI_OSS_REGION` and `V3_DOCS_ALI_CDN_DOMAIN`; leave the existing v2 deployment targets unchanged. Documentation and UI Library share `DOCS_ALI_OSS_ACCESS_KEY_ID` and `DOCS_ALI_OSS_ACCESS_KEY_SECRET`, which must have access to their respective destinations. UI Library keeps its `nocobase-ui-library` bucket in `cn-beijing`. Both workflows publish on matching pushes to `v3-develop`, or when manually dispatched with `publish` enabled; no additional migration variable is required.
+- Pull requests changing only `docs/**` skip Quality, Changeset Check and Guard Main; the Docs workflow checks and builds the documentation without publishing. Quality also skips documentation-only pushes to `v3-develop`, where Docs builds and publishes instead. Mixed changes retain the normal checks. These workflow-level path filters must be considered before making the skipped workflows required branch checks, because GitHub can leave required checks pending when a workflow is filtered out. Preview routing is managed separately by the bot.
 
 ## Historical references
 

.github/workflows/v3-changeset-check.yml

@@ -9,6 +9,8 @@ on:
     branches:
       - v3-main
       - v3-develop
+    paths-ignore:
+      - 'docs/**'
 
 permissions:
   contents: read

.github/workflows/v3-docs.yml

@@ -91,17 +91,15 @@ jobs:
 
       - name: Publish
         if: >-
-          vars.V3_ASSET_DEPLOY_ENABLED == 'true' && (
           github.event_name == 'workflow_dispatch' && inputs.publish ||
           github.event_name == 'push' && github.ref == 'refs/heads/v3-develop'
-          )
         working-directory: docs
         env:
           DOCS_ALI_OSS_ACCESS_KEY_ID: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_ID }}
           DOCS_ALI_OSS_ACCESS_KEY_SECRET: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_SECRET }}
-          DOCS_ALI_OSS_BUCKET: ${{ secrets.DOCS_ALI_OSS_BUCKET }}
-          DOCS_ALI_OSS_REGION: ${{ secrets.DOCS_ALI_OSS_REGION }}
-          DOCS_ALI_CDN_DOMAIN: ${{ secrets.DOCS_ALI_CDN_DOMAIN }}
+          DOCS_ALI_OSS_BUCKET: ${{ secrets.V3_DOCS_ALI_OSS_BUCKET }}
+          DOCS_ALI_OSS_REGION: ${{ secrets.V3_DOCS_ALI_OSS_REGION }}
+          DOCS_ALI_CDN_DOMAIN: ${{ secrets.V3_DOCS_ALI_CDN_DOMAIN }}
           # ossutil reads the credentials from these names rather than the DOCS_-prefixed ones.
           OSS_ACCESS_KEY_ID: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_ID }}
           OSS_ACCESS_KEY_SECRET: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_SECRET }}

.github/workflows/v3-guard-main.yml

@@ -7,6 +7,8 @@ on:
   pull_request:
     branches:
       - v3-main
+    paths-ignore:
+      - 'docs/**'
 
 permissions:
   contents: read

.github/workflows/v3-quality.yml

@@ -5,9 +5,13 @@ on:
     branches:
       - v3-develop
       - v3-main
+    paths-ignore:
+      - 'docs/**'
   push:
     branches:
       - v3-develop
+    paths-ignore:
+      - 'docs/**'
 
 permissions:
   contents: read

.github/workflows/v3-ui-library.yml

@@ -105,10 +105,8 @@ jobs:
 
       - name: Publish to OSS
         if: >-
-          vars.V3_ASSET_DEPLOY_ENABLED == 'true' && (
           (github.event_name == 'push' && github.ref == 'refs/heads/v3-develop') ||
           (github.event_name == 'workflow_dispatch' && inputs.publish && github.ref == 'refs/heads/v3-develop')
-          )
         env:
           UI_LIBRARY_ALI_OSS_ACCESS_KEY_ID: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_ID }}
           UI_LIBRARY_ALI_OSS_ACCESS_KEY_SECRET: ${{ secrets.DOCS_ALI_OSS_ACCESS_KEY_SECRET }}

tests/scripts/v3-workflow-routing.test.mjs

@@ -62,16 +62,36 @@ test('v3 GitHub Releases never take the shared Latest marker', () => {
   assert.match(source, /release\/\*\)\s+FLAGS=\(--latest=false\)/u);
 });
 
-test('site deployment waits for migration configuration while PR builds stay available', () => {
+test('site deployment uses the existing publish triggers without a migration gate', () => {
   for (const name of ['docs', 'ui-library']) {
     const source = workflow(name);
-    assert.match(source, /vars\.V3_ASSET_DEPLOY_ENABLED == 'true'/u);
+    assert.doesNotMatch(source, /V3_ASSET_DEPLOY_ENABLED/u);
+    assert.match(
+      source,
+      /github\.event_name == 'push' && github\.ref == 'refs\/heads\/v3-develop'/u,
+    );
+    assert.match(
+      source,
+      /github\.event_name == 'workflow_dispatch' && inputs\.publish/u,
+    );
     assert.match(
       source,
       /pull_request:\n    branches:\n      - v3-develop\n      - v3-main/u,
     );
     assert.match(source, /publish:[\s\S]*?default: false/u);
   }
+  const docs = workflow('docs');
+  for (const name of ['OSS_BUCKET', 'OSS_REGION', 'CDN_DOMAIN']) {
+    assert.ok(docs.includes(`secrets.V3_DOCS_ALI_${name}`));
+    assert.ok(!docs.includes(`secrets.DOCS_ALI_${name}`));
+  }
+  for (const name of ['docs', 'ui-library']) {
+    for (const key of ['ID', 'SECRET']) {
+      assert.ok(
+        workflow(name).includes(`secrets.DOCS_ALI_OSS_ACCESS_KEY_${key}`),
+      );
+    }
+  }
 });
 
 test('independent Pro releases keep their own repository and branches', () => {