docs-deploy: Skip pipeline on default-branch pushes without docs changes (#99)

* docs-deploy: Skip pipeline on default-branch pushes without docs changes

Pass effective_any_modified from docs-build's check job to docs-deploy
via artifact. On push events, docs-deploy reads the artifact instead of
hardcoding has-changes=true, so the build/deploy/link-index pipeline is
skipped when no docs-relevant files changed. Version branches keep
current behavior (always run) via the existing use-release-branches
override in docs-build.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Narrow use-release-branches override to first push (branch creation)

The override previously forced effective_any_modified=true on every push
to a version branch. Now it only triggers when github.event.created is
true (first push), so subsequent pushes to version branches respect
actual docs-change detection like the default branch.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: reakaleek

.github/workflows/docs-build.yml

@@ -39,8 +39,9 @@ on:
         required: false
       use-release-branches:
         description: >
-          When true, push events to semver release branches (e.g. 9.4) run the docs build even when no docs/** files
-          changed, so links.json can be produced for the link index. main keeps skip-when-no-docs-diff behavior.
+          When true, the first push to a new semver release branch (e.g. 9.4) runs the docs build even when no
+          docs/** files changed, so links.json can be produced for the link index. Subsequent pushes to the same
+          branch only build when docs files actually change.
         type: boolean
         default: false
         required: false
@@ -191,9 +192,10 @@ jobs:
             core.setOutput('deleted_files', deleted.join(' '));
             core.setOutput('renamed_files', renamed.join(' '));
 
-      # Why: On a release line (e.g. 9.4), months of pushes may touch only code or deps—never docs/. We still need a
-      # full docs build sometimes so links.json exists for the shared link index. Opt-in repos enable that with
-      # use-release-branches; Vale lint stays tied to real doc edits (any_modified), not this override.
+      # Why: When a release branch (e.g. 9.4) is first created, it may share the same commit as the default
+      # branch, so changed-files reports no diff. We still need a full docs build on that first push so
+      # links.json is produced for the link index. Subsequent pushes only build when docs files actually change.
+      # Vale lint stays tied to real doc edits (any_modified), not this override.
       - name: Effective any_modified (release-branch opt-in)
         id: effective-any-modified
         if: always()
@@ -203,21 +205,36 @@ jobs:
           EVENT_NAME: ${{ github.event_name }}
           REF_NAME: ${{ github.ref_name }}
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+          CREATED: ${{ github.event.created }}
         run: |
           # Empty ANY_MODIFIED means "we did not run changed-files" (e.g. workflow_dispatch), not "no docs changed."
           # We only want to skip the docs build when changed-files explicitly reports no matching paths (false).
           # Treating empty as true keeps that contract: no diff result => do not infer skip; explicit false => skip
-          # unless use-release-branches forces a release-line build below.
+          # unless use-release-branches forces a build on new release branches below.
           effective="${ANY_MODIFIED}"
           if [[ -z "${effective}" ]]; then
             effective="true"
           fi
-          if [[ "${USE_RELEASE}" == "true" && "${EVENT_NAME}" == "push" && "${REF_NAME}" != "${DEFAULT_BRANCH}" ]] \
+          if [[ "${USE_RELEASE}" == "true" && "${EVENT_NAME}" == "push" && "${CREATED}" == "true" ]] \
+            && [[ "${REF_NAME}" != "${DEFAULT_BRANCH}" ]] \
             && [[ "${REF_NAME}" =~ ^[0-9]+\.[0-9]+(\.[0-9]+)?$ ]]; then
             effective="true"
           fi
           echo "effective_any_modified=${effective}" >> "$GITHUB_OUTPUT"
 
+      - name: Write check metadata
+        if: always() && steps.effective-any-modified.outputs.effective_any_modified != ''
+        run: |
+          echo '${{ steps.effective-any-modified.outputs.effective_any_modified }}' > /tmp/effective_any_modified
+
+      - name: Upload check metadata
+        if: always() && steps.effective-any-modified.outputs.effective_any_modified != ''
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-build-check-metadata
+          path: /tmp/effective_any_modified
+          retention-days: 1
+
   # This check skips the job when the workflow runs on a fork repo itself (e.g.
   # user/kibana), not when a fork PR targets upstream. Fork PRs to upstream run
   # fine because github.event.repository is the upstream repo (not a fork).

.github/workflows/docs-deploy.yml

@@ -45,7 +45,7 @@ on:
       use-release-branches:
         description: >
           When true, update-link-index runs for semver release branches (e.g. 9.4) as well as the default branch.
-          Pair with the same flag on docs-build so links.json is produced on release pushes without docs/** changes.
+          Pair with the same flag on docs-build so links.json is produced when a release branch is first created.
         type: boolean
         default: false
         required: false
@@ -63,6 +63,7 @@ jobs:
       && github.event.repository.fork == false
     runs-on: ubuntu-latest
     permissions:
+      actions: read
       contents: none
       pull-requests: read
       id-token: write
@@ -80,6 +81,17 @@ jobs:
       vale-files-match: ${{ steps.context.outputs.vale-files-match }}
       link-index-eligible: ${{ steps.link-index-branch.outputs.eligible }}
     steps:
+      - name: Download check metadata
+        id: download-metadata
+        if: github.event.workflow_run.event == 'push'
+        continue-on-error: true
+        uses: actions/download-artifact@v8
+        with:
+          name: docs-build-check-metadata
+          run-id: ${{ github.event.workflow_run.id }}
+          path: /tmp/check-metadata
+          github-token: ${{ github.token }}
+
       - name: Resolve workflow run context
         id: context
         uses: actions/github-script@v9
@@ -109,8 +121,19 @@ jobs:
 
             if (event === 'push') {
               core.setOutput('base-ref', headBranch);
-              core.setOutput('has-changes', 'true');
               core.setOutput('vale-files-match', 'false');
+
+              let hasChanges = 'true';
+              try {
+                const fs = require('fs');
+                const value = fs.readFileSync('/tmp/check-metadata/effective_any_modified', 'utf8').trim();
+                hasChanges = value === 'false' ? 'false' : 'true';
+                core.info(`Push has-changes from docs-build metadata: ${hasChanges}`);
+              } catch (err) {
+                core.warning(`Could not read check metadata: ${err.message} — falling back to has-changes=true`);
+              }
+
+              core.setOutput('has-changes', hasChanges);
               return;
             }