From 7a60a9988f9bfcd17df13c862f5360cd4de176d9 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 5 Aug 2026 13:15:25 +0200 Subject: [PATCH 1/5] Preview the website on documentation pull requests test-with-website already checked out FlowFuse/website next to this repository and built the whole site with the pull request's docs, because docs-sync.mjs prefers a sibling checkout over cloning main. It then threw the output away after the link check. That build is now FlowFuse/website's site-preview.yml, called from here, so this repository stops carrying a second copy of the website pipeline and picks up changes to it as the Nuxt migration progresses. When the caller is a pull request from a branch in this repository it also uploads the result to Netlify under a docs-pr- alias and reports the URL on the pull request. The upload is an aliased, unpublished deploy: no --prod, and no --build, so netlify.toml's build command (which reindexes Algolia) never runs against a preview and flowfuse.com keeps serving whatever it served before. test-with-website survives as a gate job so the check name and the publish dependency are unchanged. --- .github/workflows/docs.yml | 86 +++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bea1575ed9..25298fa52f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,6 +7,13 @@ on: pull_request: paths: - 'docs/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.event.number || github.ref }} + # Only the newest push to a pull request is worth previewing. Pushes to main are never + # cancelled, so a publish cannot be interrupted by the next docs merge. + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: test: runs-on: ubuntu-latest @@ -22,56 +29,41 @@ jobs: run: npm ci - name: Test Documentation Links run: npm run test:docs + # The build lives in FlowFuse/website so this repository does not carry a second copy of + # it. Tracking @main means changes to the website build or deploy are picked up here. + # NOTE: pinned to the website branch until FlowFuse/website#5515 merges, then move to @main. + website: + name: Build the website with these docs + permissions: + contents: read + deployments: write + pull-requests: write + uses: FlowFuse/website/.github/workflows/site-preview.yml@docs-preview-shared-build + with: + docs_repository: ${{ github.repository }} + docs_ref: ${{ github.sha }} + # Pull requests from forks receive no secrets, so they get the build and the link + # check without an upload. + deploy_preview: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }} + preview_alias: docs-pr-${{ github.event.pull_request.number }} + pr_number: ${{ github.event.pull_request.number || 0 }} + secrets: + ci_app_id: ${{ secrets.GH_BOT_APP_ID }} + ci_app_key: ${{ secrets.GH_BOT_APP_KEY }} + netlify_auth_token: ${{ secrets.NETLIFY_AUTH_TOKEN }} + netlify_site_id: ${{ secrets.NETLIFY_SITE_ID }} + # A reusable workflow reports its checks as "caller job / called job". This gate keeps the + # original context name and the publish dependency below intact. test-with-website: runs-on: ubuntu-latest name: Test Documentation with website + needs: website + if: always() steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - path: 'flowfuse' - - name: Check out website repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - repository: 'FlowFuse/website' - path: 'website' - - name: Generate a token - id: generate_token - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 - with: - app-id: ${{ secrets.GH_BOT_APP_ID }} - private-key: ${{ secrets.GH_BOT_APP_KEY }} - owner: ${{ github.repository_owner }} - repositories: blueprint-library - - name: Check out FlowFuse/blueprint-library repository (to access the blueprints) - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - repository: 'FlowFuse/blueprint-library' - ref: main - path: 'blueprint-library' - token: ${{ steps.generate_token.outputs.token }} - - name: Cache image pipeline output - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 - with: - key: img-pipeline-cache - path: website/_site/img - - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - cache: 'npm' - cache-dependency-path: './website/package-lock.json' - - run: npm run docs - working-directory: 'website' - - run: npm run blueprints - working-directory: 'website' - - name: Install Dependencies - run: npm install - working-directory: 'website' - - name: Build the forge - run: npm run build:nuxt:skip-images - working-directory: 'website' - - uses: untitaker/hyperlink@9375bc4063712ad490d5eb3d54df0b6aade15e54 # 0.3.2 - with: - args: website/nuxt/dist/ --check-anchors --sources website/src + - name: Require the website build to have succeeded + run: | + echo "website result: ${{ needs.website.result }}" + [ "${{ needs.website.result }}" = "success" ] publish: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest @@ -88,7 +80,7 @@ jobs: private-key: ${{ secrets.GH_BOT_APP_KEY }} owner: ${{ github.repository_owner }} repositories: website - + - name: Trigger website rebuild uses: benc-uk/workflow-dispatch@31e2b3319479a63f0ab15bf800eff9e913504e26 # v1.3.2 with: From da91e29e939a36adfaacf6c554ab7352edce24a0 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 5 Aug 2026 13:15:50 +0200 Subject: [PATCH 2/5] Run the docs workflow on changes to the docs workflow Without this the pull request that changes docs.yml does not trigger it, so the build and the preview upload go unverified. --- .github/workflows/docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 25298fa52f..671d366379 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -7,6 +7,8 @@ on: pull_request: paths: - 'docs/**' + # A change to this workflow should be exercised by this workflow. + - '.github/workflows/docs.yml' concurrency: group: ${{ github.workflow }}-${{ github.event.number || github.ref }} From 3127bbcbef456684fc9f3d624bab20e1a47320a4 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 12 Aug 2026 18:17:28 +0200 Subject: [PATCH 3/5] Point the website preview at the shared build workflow site-preview.yml no longer exists on FlowFuse/website. The definition moved to FlowFuse/github-actions-workflows as build_website.yml, so the old reference resolved to nothing. The inputs and secrets are unchanged, only the ref moves. --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 671d366379..c83e9e6cfa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,16 +31,16 @@ jobs: run: npm ci - name: Test Documentation Links run: npm run test:docs - # The build lives in FlowFuse/website so this repository does not carry a second copy of - # it. Tracking @main means changes to the website build or deploy are picked up here. - # NOTE: pinned to the website branch until FlowFuse/website#5515 merges, then move to @main. + # The build lives in FlowFuse/github-actions-workflows so this repository does not carry a + # second copy of it, and FlowFuse/website's own CI calls the same definition. The release + # job there moves build_website/v1 on each release, so build changes are picked up here. website: name: Build the website with these docs permissions: contents: read deployments: write pull-requests: write - uses: FlowFuse/website/.github/workflows/site-preview.yml@docs-preview-shared-build + uses: FlowFuse/github-actions-workflows/.github/workflows/build_website.yml@build_website/v1 with: docs_repository: ${{ github.repository }} docs_ref: ${{ github.sha }} From 70b53b895cffc46170dfe24e70fe4ff7fe7a3cff Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Fri, 14 Aug 2026 12:09:22 +0200 Subject: [PATCH 4/5] Simplify the concurrency group to github.ref --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c83e9e6cfa..cf4b9a87bf 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,7 +11,7 @@ on: - '.github/workflows/docs.yml' concurrency: - group: ${{ github.workflow }}-${{ github.event.number || github.ref }} + group: ${{ github.workflow }}-${{ github.ref }} # Only the newest push to a pull request is worth previewing. Pushes to main are never # cancelled, so a publish cannot be interrupted by the next docs merge. cancel-in-progress: ${{ github.event_name == 'pull_request' }} From b59f6f4756656809a0ba63325e93ff55aea84509 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Fri, 14 Aug 2026 13:16:10 +0200 Subject: [PATCH 5/5] Drop the test-with-website gate job The gate existed only to keep publishing the old check name. A reusable workflow reports as "caller job / called job", so the website build now reports as "Build the website with these docs / Build and check" and publish depends on it directly. --- .github/workflows/docs.yml | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cf4b9a87bf..d54a03bdb4 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -54,24 +54,12 @@ jobs: ci_app_key: ${{ secrets.GH_BOT_APP_KEY }} netlify_auth_token: ${{ secrets.NETLIFY_AUTH_TOKEN }} netlify_site_id: ${{ secrets.NETLIFY_SITE_ID }} - # A reusable workflow reports its checks as "caller job / called job". This gate keeps the - # original context name and the publish dependency below intact. - test-with-website: - runs-on: ubuntu-latest - name: Test Documentation with website - needs: website - if: always() - steps: - - name: Require the website build to have succeeded - run: | - echo "website result: ${{ needs.website.result }}" - [ "${{ needs.website.result }}" = "success" ] publish: if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest needs: - test - - test-with-website + - website name: Publish Documentation steps: - name: Generate token