Fix terminology: deployment branch policies, not branch protection ru… #4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. It doesn't publish anything itself - docs-generate-html.yml | |
| # hands off to the (separate) docs-publish repo for that. | |
| # | |
| # 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). | |
| # | |
| # If your repo instead has clean, separate dev/prod branches (e.g. dev and main), you | |
| # almost certainly do NOT want this: a commit to dev should only ever build staging, and | |
| # a commit to main should only ever build prod - never both from one commit, since | |
| # they're different content on different branches. For that shape, skip this file | |
| # entirely and give docs-generate-html.yml its own direct `on: push: branches: [...]` | |
| # trigger per environment instead (see docs-aura's docs-generate-html.yml for that | |
| # pattern) - simpler, and structurally can't build the wrong branch's content into the | |
| # wrong environment. | |
| permissions: | |
| contents: read | |
| actions: write | |
| # Edit the branches list below to match your repository: it must be the union of every | |
| # branch listed in BOTH your staging and prod Antora publish.yml playbooks (content | |
| # sources' `branches`). prepare-ref-env's logic below assumes this - it doesn't inspect | |
| # the playbooks itself, it just trusts that if this workflow ran at all, the branch that | |
| # triggered it is a real content branch for at least one of the two environments. | |
| on: | |
| push: | |
| branches: | |
| - 'dev' | |
| workflow_dispatch: | |
| # Set DEV_BRANCH to your staging branch. | |
| # Set PROD_BRANCH if you also publish to neo4j.com/docs; omit it for staging-only repos. | |
| env: | |
| DEV_BRANCH: 'dev' | |
| # PROD_BRANCH: 'main' | |
| jobs: | |
| prepare-ref-env: | |
| name: Set builds to trigger | |
| runs-on: ubuntu-latest | |
| outputs: | |
| # JSON array of {buildRef, publishEnv} - one entry per independent | |
| # docs-generate-html.yml run to trigger. publishEnv is left '' except in the one | |
| # case where it's genuinely ambiguous (see below) - docs-generate-html.yml derives | |
| # it itself from build-ref against its own vars.DOCS_PROD_BRANCH whenever | |
| # publishEnv is blank. | |
| builds: ${{ steps.set-ref-env.outputs.builds }} | |
| steps: | |
| - name: Set builds | |
| id: set-ref-env | |
| run: | | |
| dev_branch="${{ env.DEV_BRANCH }}" | |
| prod_branch="${{ env.PROD_BRANCH }}" | |
| # Rules: | |
| # - No separate prod branch configured -> staging only, always (nothing to | |
| # double up). | |
| # - DEV_BRANCH == PROD_BRANCH -> both, always (one branch serves both, so | |
| # there's no "the other one didn't change" case to worry about). | |
| # - The triggering branch IS the dev branch -> staging only (a change on dev | |
| # has no bearing on prod's already-published content). | |
| # - Anything else (including a push to the prod branch, or any other branch) | |
| # -> both. We deliberately don't try to be clever about only rebuilding | |
| # the one that "actually changed" - e.g. a branch that's fallen out of the | |
| # dev set but is still in the prod set would be misdetected either way, so | |
| # we just always rebuild everything except the one case (dev branch) we | |
| # know for certain doesn't affect prod. | |
| if [[ -z "${prod_branch}" ]]; then | |
| builds=$(jq -nc --arg dev "$dev_branch" \ | |
| '[{buildRef:$dev,publishEnv:""}]') | |
| elif [[ "${dev_branch}" == "${prod_branch}" ]]; then | |
| # build-ref alone can't distinguish these two - same branch - so publishEnv | |
| # has to be passed explicitly here, or docs-generate-html.yml's derivation | |
| # would resolve both to the same environment. | |
| builds=$(jq -nc --arg b "$dev_branch" \ | |
| '[{buildRef:$b,publishEnv:"dev"},{buildRef:$b,publishEnv:"prod"}]') | |
| elif [[ "${GITHUB_REF}" == "refs/heads/${dev_branch}" ]]; then | |
| builds=$(jq -nc --arg dev "$dev_branch" \ | |
| '[{buildRef:$dev,publishEnv:""}]') | |
| else | |
| builds=$(jq -nc --arg dev "$dev_branch" --arg prod "$prod_branch" \ | |
| '[{buildRef:$dev,publishEnv:""},{buildRef:$prod,publishEnv:""}]') | |
| fi | |
| echo "builds=${builds}" >> $GITHUB_OUTPUT | |
| # Trigger docs-generate-html.yml as its own separate run, once per build - not a | |
| # workflow_call (which would keep them all in this one run) - so each is fully | |
| # independent: if one run fails, the others are unaffected, and each ends up with a | |
| # plain "docs" artifact exactly like a run does today (no name collisions, since | |
| # they're separate runs, not jobs sharing one run). | |
| trigger-generate-html: | |
| name: Trigger builds | |
| needs: prepare-ref-env | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Dispatch docs-generate-html.yml for each build | |
| uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 | |
| env: | |
| BUILDS: ${{ needs.prepare-ref-env.outputs.builds }} | |
| PROD_BRANCH: ${{ env.PROD_BRANCH }} | |
| with: | |
| script: | | |
| const builds = JSON.parse(process.env.BUILDS) | |
| const prodBranch = process.env.PROD_BRANCH | |
| for (const build of builds) { | |
| await github.rest.actions.createWorkflowDispatch({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| workflow_id: 'docs-generate-html.yml', | |
| // 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, | |
| }, | |
| }) | |
| // Mirrors resolve-env's own derivation for display purposes only - the | |
| // real derivation happens inside the dispatched run, this is just to show | |
| // what it will resolve to when no explicit override was passed. | |
| const env = build.publishEnv || (build.buildRef === prodBranch ? 'prod' : 'dev') | |
| core.summary.addRaw(`Triggered \`docs-generate-html.yml\` on branch \`${build.buildRef}\` for \`${env}\``, true) | |
| } | |
| await core.summary.write() |