Rename docs-publish.yml, add trigger summary, set ref for triggered build (#127)

Author: recrwplay

.github/workflows/docs-generate-html.yml

@@ -6,7 +6,7 @@ permissions:
 
 # Builds, verifies, and publishes docs for ONE environment, as a run entirely independent
 # of any other environment's run. Triggered (via the API, not a workflow_call) by
-# docs-publish.yml, once per environment that applies to a given push (dev, prod, or both) -
+# docs-trigger-builds.yml, once per environment that applies to a given push (dev, prod, or both) -
 # so if dev's run fails, prod's run is completely unaffected, and vice versa.
 on:
   workflow_dispatch:

.github/workflows/docs-publish.yml .github/workflows/docs-trigger-builds.yml.github/workflows/docs-publish.yml renamed to .github/workflows/docs-trigger-builds.yml

@@ -1,10 +1,11 @@
-name: "Publish docs"
+name: "Trigger docs builds"
 
 # This workflow's job is dispatching docs-generate-html.yml with the right build-ref(s)
 # for whatever just happened - it is NOT the only valid way to wire this up, and isn't
-# always the right choice.
+# always the right choice. It doesn't publish anything itself - docs-generate-html.yml
+# hands off to the (separate) docs-publish repo for that.
 #
-# Use this (docs-publish.yml -> docs-generate-html.yml) when a single trigger might
+# Use this (docs-trigger-builds.yml -> docs-generate-html.yml) when a single trigger might
 # legitimately need to build more than one environment - e.g. a manual "rebuild
 # everything" workflow_dispatch, or a repo where DOCS_DEV_BRANCH == DOCS_PROD_BRANCH (one
 # branch serving both, so every push to it always means both).
@@ -104,19 +105,36 @@ jobs:
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         env:
           BUILDS: ${{ needs.prepare-ref-env.outputs.builds }}
-          DISPATCH_REF: ${{ github.ref_name }}
         with:
           script: |
             const builds = JSON.parse(process.env.BUILDS)
+            const lines = []
             for (const build of builds) {
               await github.rest.actions.createWorkflowDispatch({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 workflow_id: 'docs-generate-html.yml',
-                ref: process.env.DISPATCH_REF,
+                // Dispatch from build.buildRef itself, NOT the branch that triggered
+                // this workflow - this run's ref becomes its real head_branch, which is
+                // exactly what docs-publish's check-build-branch inspects. Using a
+                // single fixed ref for every build here would make every dispatched
+                // run's head_branch equal whatever branch triggered THIS workflow,
+                // regardless of which environment it's actually building for - so a
+                // trigger from any branch other than build.buildRef (e.g. a versioned
+                // content branch, or the "other" branch when both are built) would
+                // always fail that check downstream, even for an otherwise-legitimate
+                // build.
+                ref: build.buildRef,
                 inputs: {
                   'build-ref': build.buildRef,
                   'publish-env': build.publishEnv,
                 },
               })
+              const envNote = build.publishEnv ? ` (publish-env override: \`${build.publishEnv}\`)` : ''
+              lines.push(`- \`docs-generate-html.yml\` for build-ref \`${build.buildRef}\`${envNote}`)
             }
+
+            await core.summary
+              .addHeading('Triggered builds')
+              .addRaw(lines.join('\n'))
+              .write()