From d7cf702c3efd04e19bec30b9b97fb4e5b36e52a5 Mon Sep 17 00:00:00 2001 From: Neil Dewhurst Date: Fri, 9 Oct 2026 12:27:44 +0100 Subject: [PATCH 1/2] Simplify manual dispatch: drop build-ref, make publish-env a dropdown Manually dispatching Generate HTML/PDF showed three boxes where only one was ever really needed: GitHub's own built-in "Use workflow from" branch selector, our own build-ref text input (always the same branch as the selector above it, since there's no reason in this pipeline for them to differ - confirmed in both the manual case, where you'd just retype the same branch, and the automated docs-trigger-builds.yml dispatch, which already sets ref: and the build-ref input to the exact same value in the same API call), and publish-env. Dropped build-ref entirely and read github.ref_name directly instead - it never carried information github.ref_name didn't already have. publish-env can't be dropped the same way: when DOCS_DEV_BRANCH == DOCS_PROD_BRANCH, branch name alone can't tell the two builds apart, so it stays as a real override - now a type: choice dropdown (blank/dev/prod) with a hint that explains that one case in plain language instead of naming the internal vars.DOCS_DEV_BRANCH/DOCS_PROD_BRANCH variables. --- .github/workflows/docs-generate-html.yml | 27 ++++++++++------- .github/workflows/docs-generate-pdf.yml | 35 ++++++++++++----------- .github/workflows/docs-trigger-builds.yml | 5 +++- 3 files changed, 39 insertions(+), 28 deletions(-) diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml index c8960d0..bcdb29c 100644 --- a/.github/workflows/docs-generate-html.yml +++ b/.github/workflows/docs-generate-html.yml @@ -1,5 +1,5 @@ name: "Generate HTML" -run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (inputs.build-ref == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} HTML from ${{ inputs.build-ref }}" +run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (github.ref_name == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} HTML from ${{ github.ref_name }}" permissions: contents: read @@ -8,18 +8,26 @@ permissions: # of any other environment's run. Triggered (via the API, not a workflow_call) by # 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. +# +# No build-ref input: the git ref to build from is always whatever ref this run was +# itself dispatched against (the "Use workflow from" branch when triggered manually, or +# docs-trigger-builds.yml's own `ref:` when triggered automatically - which it always sets +# to the same value it also used to pass as a build-ref input here, so that separate input +# never actually carried any information github.ref_name didn't already have). Reading +# github.ref_name directly instead removes a second, redundant "which branch" box from +# manual dispatch. on: workflow_dispatch: inputs: - build-ref: - description: 'The git ref to build from' - type: string - required: true publish-env: - description: 'Override for dev/prod. Leave blank to derive it from build-ref against vars.DOCS_PROD_BRANCH - only needs setting explicitly when DOCS_DEV_BRANCH == DOCS_PROD_BRANCH, where build-ref alone cannot tell the two builds apart.' - type: string + description: 'dev or prod. Leave blank to infer from the branch - only needed if your dev and prod branches are the same (branch name alone cannot tell the two builds apart then).' + type: choice required: false default: '' + options: + - '' + - 'dev' + - 'prod' jobs: @@ -35,12 +43,11 @@ jobs: id: resolve env: PUBLISH_ENV_OVERRIDE: ${{ inputs.publish-env }} - BUILD_REF: ${{ inputs.build-ref }} PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} run: | if [[ -n "${PUBLISH_ENV_OVERRIDE}" ]]; then publish_env="${PUBLISH_ENV_OVERRIDE}" - elif [[ "${BUILD_REF}" == "${PROD_BRANCH}" ]]; then + elif [[ "${GITHUB_REF_NAME}" == "${PROD_BRANCH}" ]]; then publish_env="prod" else publish_env="dev" @@ -54,7 +61,7 @@ jobs: uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2 with: package-script: 'verify:publish' - build-ref: ${{ inputs.build-ref }} + build-ref: ${{ github.ref_name }} fetch-depth: 0 publish-env: ${{ needs.resolve-env.outputs.publish-env }} diff --git a/.github/workflows/docs-generate-pdf.yml b/.github/workflows/docs-generate-pdf.yml index 5954861..62216be 100644 --- a/.github/workflows/docs-generate-pdf.yml +++ b/.github/workflows/docs-generate-pdf.yml @@ -1,28 +1,30 @@ name: "Generate PDF" -run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (inputs.build-ref == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} PDF from ${{ inputs.build-ref }}" +run-name: "Generate ${{ inputs.publish-env != '' && inputs.publish-env || (github.ref_name == vars.DOCS_PROD_BRANCH && 'prod' || 'dev') }} PDF from ${{ github.ref_name }}" permissions: contents: read -# Mirrors docs-generate-html.yml's shape (workflow_dispatch with build-ref and -# publish-env inputs, resolve-env -> build -> publish) and its own reusable-workflow -# reference convention (a pinned neo4j/docs-tools/...@v2 tag, not a relative path - -# this repo doesn't contain reusable-docs-pdf-build.yml itself). Still simpler than -# docs-generate-html.yml in one way: there's no docs-verify step (no equivalent check -# exists yet for a PDF), and build/publish are two plain jobs rather than a -# reusable-workflow call plus a verify call. +# Mirrors docs-generate-html.yml's shape (workflow_dispatch with a publish-env input, +# resolve-env -> build -> publish) and its own reusable-workflow reference convention (a +# pinned neo4j/docs-tools/...@v2 tag, not a relative path - this repo doesn't contain +# reusable-docs-pdf-build.yml itself). Still simpler than docs-generate-html.yml in one +# way: there's no docs-verify step (no equivalent check exists yet for a PDF), and +# build/publish are two plain jobs rather than a reusable-workflow call plus a verify call. +# +# No build-ref input - see docs-generate-html.yml's own comment on why: the git ref to +# build from is always whatever ref this run was itself dispatched against. on: workflow_dispatch: inputs: - build-ref: - description: 'The git ref to build from' - type: string - required: true publish-env: - description: 'Override for dev/prod. Leave blank to derive it from build-ref against vars.DOCS_PROD_BRANCH - only needs setting explicitly when DOCS_DEV_BRANCH == DOCS_PROD_BRANCH, where build-ref alone cannot tell the two builds apart.' - type: string + description: 'dev or prod. Leave blank to infer from the branch - only needed if your dev and prod branches are the same (branch name alone cannot tell the two builds apart then).' + type: choice required: false default: '' + options: + - '' + - 'dev' + - 'prod' jobs: @@ -38,12 +40,11 @@ jobs: id: resolve env: PUBLISH_ENV_OVERRIDE: ${{ inputs.publish-env }} - BUILD_REF: ${{ inputs.build-ref }} PROD_BRANCH: ${{ vars.DOCS_PROD_BRANCH }} run: | if [[ -n "${PUBLISH_ENV_OVERRIDE}" ]]; then publish_env="${PUBLISH_ENV_OVERRIDE}" - elif [[ "${BUILD_REF}" == "${PROD_BRANCH}" ]]; then + elif [[ "${GITHUB_REF_NAME}" == "${PROD_BRANCH}" ]]; then publish_env="prod" else publish_env="dev" @@ -56,7 +57,7 @@ jobs: needs: resolve-env uses: neo4j/docs-tools/.github/workflows/reusable-docs-pdf-build.yml@v2 with: - build-ref: ${{ inputs.build-ref }} + build-ref: ${{ github.ref_name }} fetch-depth: 0 publish-env: ${{ needs.resolve-env.outputs.publish-env }} diff --git a/.github/workflows/docs-trigger-builds.yml b/.github/workflows/docs-trigger-builds.yml index 049f6ce..883a27a 100644 --- a/.github/workflows/docs-trigger-builds.yml +++ b/.github/workflows/docs-trigger-builds.yml @@ -141,7 +141,10 @@ jobs: const build = JSON.parse(process.env.BUILD) const prodBranch = process.env.PROD_BRANCH // Both docs-generate-html.yml and docs-generate-pdf.yml accept publish-env. - const inputs = { 'build-ref': build.buildRef, 'publish-env': build.publishEnv } + // Neither has a build-ref input - the ref: below is what determines the git + // ref the dispatched run actually builds from (github.ref_name inside it), + // so a separate build-ref input would only ever duplicate this same value. + const inputs = { 'publish-env': build.publishEnv } await github.rest.actions.createWorkflowDispatch({ owner: context.repo.owner, repo: context.repo.repo, From ea3382e3bed963c5e7cddf64e951318a024ff138 Mon Sep 17 00:00:00 2001 From: Neil Dewhurst Date: Fri, 9 Oct 2026 12:49:10 +0100 Subject: [PATCH 2/2] Reword publish-env hint --- .github/workflows/docs-generate-html.yml | 2 +- .github/workflows/docs-generate-pdf.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml index bcdb29c..dbe07aa 100644 --- a/.github/workflows/docs-generate-html.yml +++ b/.github/workflows/docs-generate-html.yml @@ -20,7 +20,7 @@ on: workflow_dispatch: inputs: publish-env: - description: 'dev or prod. Leave blank to infer from the branch - only needed if your dev and prod branches are the same (branch name alone cannot tell the two builds apart then).' + description: "The environment to publish to. Provide a value when the same branch publishes to both 'dev' and 'prod' environments. Otherwise, leave blank." type: choice required: false default: '' diff --git a/.github/workflows/docs-generate-pdf.yml b/.github/workflows/docs-generate-pdf.yml index 62216be..eaa3123 100644 --- a/.github/workflows/docs-generate-pdf.yml +++ b/.github/workflows/docs-generate-pdf.yml @@ -17,7 +17,7 @@ on: workflow_dispatch: inputs: publish-env: - description: 'dev or prod. Leave blank to infer from the branch - only needed if your dev and prod branches are the same (branch name alone cannot tell the two builds apart then).' + description: "The environment to publish to. Provide a value when the same branch publishes to both 'dev' and 'prod' environments. Otherwise, leave blank." type: choice required: false default: ''