ci: bundle Mkdocs site into Releases (#41355)

As we now perform the Mkdocs build as part of the main repo, we can
now attach the docs site build into the GitHub Release artifacts as part
of our release pipeline.

For folks who are running versions behind the "bleeding edge" of
Renovate, this is very useful, as they can now grab a copy of the built
documentation for their given Renovate version.

This allows folks to take the `mkdocs-site.tgz` and upload it to static
hosting, without restoring to workarounds[0] that can make it more
difficult.

Because we're now building the docs site as part of the release, we need
to upload the built artifact to then be used by our deploy step.

As the deploy step no longer needs to build the docs site, we can
simplify this.

However, if the release hasn't occurred (because there are no commit(s)
that need a release right now) we still need to rebuild the docs site,
in case there are docs-only changes.

[0]: https://www.jvt.me/posts/2024/11/19/renovate-private-docs/

Co-authored-by: Claude Sonnet 4.5 <jamie.tanna+github-copilot@mend.io>

Author: jamietanna

.github/workflows/build.yml

@@ -845,6 +845,16 @@ jobs:
           echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
           echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.repository_owner }} --password-stdin
 
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@94a823180e06fcde4ad29308721954a521c96ed0 # v4.4
+        with:
+          python-version-file: .python-version
+          version: ${{ env.PDM_VERSION }}
+          cache: true
+
+      - name: Install pdm dependencies
+        run: pdm install
+
       - name: Check dry run
         run: |
           if [[ "${{github.event_name}}" == "workflow_dispatch" && "${{ github.event.inputs.dryRun }}" != "true"  ]]; then
@@ -860,9 +870,30 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           LOG_LEVEL: debug
 
+      - name: Build mkdocs site for deployment (when no release)
+        if: github.ref_name == 'main'
+        run: |
+          # If there wasn't a release, we won't have executed `tools/prepare-release.ts`, and the mkdocs site won't be built, but we do want it built regardless, so we can update the docs site
+          if [[ ! -f tmp/mkdocs-site.tgz ]]; then
+            latest_tag=$(gh release view --json tagName -q .tagName)
+            pnpm mkdocs build --version "$latest_tag"
+            mkdir -p tmp
+            tar -czf tmp/mkdocs-site.tgz -C tools/mkdocs/site .
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload docs artifact for deployment
+        if: github.ref_name == 'main'
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: mkdocs-site
+          path: tmp/mkdocs-site.tgz
+          retention-days: 1
+
       - run: df -h
 
-  build-deploy-docs-site:
+  deploy-docs-site:
     if: ${{ github.repository == 'renovatebot/renovate' && github.ref_name == 'main' && github.event_name == 'push' }}
     needs:
       - setup-build
@@ -878,40 +909,16 @@ jobs:
 
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          show-progress: false
-
-      - name: Setup Node.js
-        uses: ./.github/actions/setup-node
-        with:
-          node-version: ${{ needs.setup-build.outputs.node-version }}
-          os: ${{ runner.os }}
-
-      - name: Setup PDM
-        uses: pdm-project/setup-pdm@94a823180e06fcde4ad29308721954a521c96ed0 # v4.4
+      - name: Download mkdocs site from release
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
-          python-version-file: .python-version
-          version: ${{ env.PDM_VERSION }}
-          cache: true
-
-      - name: Install pdm dependencies
-        run: pdm install
+          name: mkdocs-site
+          path: tmp
 
-      - name: Determine latest release tag (whether we've released as part of this build or not)
-        id: latest_release
+      - name: Extract docs site
         run: |
-          latest_release=$(gh release view --json tagName -q .tagName)
-          echo "release_tag=$latest_release" >> "$GITHUB_OUTPUT"
-        env:
-          GH_TOKEN: ${{ github.token }}
-
-      # Rebuild the docs site to make sure that we have the version specified in the JSON Schema and page footer
-      - name: Build mkdocs for Renovate ${{ steps.latest_release.outputs.release_tag }}
-        run: pnpm mkdocs build --version ${{ steps.latest_release.outputs.release_tag }}
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
+          mkdir -p tools/mkdocs/site
+          tar -xzf tmp/mkdocs-site.tgz -C tools/mkdocs/site
 
       # Per https://github.com/renovatebot/helm-charts/issues/3752, when we migrated the docs site from renovatebot/renovatebot.github.io to renovatebot/renovate, the `/helm-charts/` repository would no longer work as a subdomain, due to a known GitHub Pages limitation
       - name: Mirror helm-charts/index.yaml from helm-charts' GitHub Pages site
@@ -950,9 +957,9 @@ jobs:
 
   notify-docs-failure:
     runs-on: ubuntu-latest
-    if: ${{ always() && (github.repository == 'renovatebot/renovate' && github.ref_name == 'main' && github.event_name == 'push') && (needs.build-deploy-docs-site.result == 'failure' || needs.build-deploy-docs-site.result == 'timed_out') }}
+    if: ${{ always() && (github.repository == 'renovatebot/renovate' && github.ref_name == 'main' && github.event_name == 'push') && (needs.deploy-docs-site.result == 'failure' || needs.deploy-docs-site.result == 'timed_out') }}
     needs:
-      - build-deploy-docs-site
+      - deploy-docs-site
     steps:
       - name: Post to Slack
         id: slack

.releaserc.json

@@ -11,6 +11,10 @@
           {
             "path": "tmp/docs.tgz",
             "label": "docs.tgz"
+          },
+          {
+            "path": "tmp/mkdocs-site.tgz",
+            "label": "mkdocs-site.tgz"
           }
         ]
       }

tools/prepare-release.ts

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import fs from 'fs-extra';
 import { logger } from '../lib/logger/index.ts';
 import { generateDocs } from './docs/index.ts';
 import { bake } from './utils/docker.ts';
@@ -33,6 +34,7 @@ void (async () => {
   logger.info(`Preparing v${opts.version?.toString()} ...`);
   build();
   await generateDocs(undefined, undefined, opts.version?.toString());
+  await buildMkdocs(opts.version?.toString());
   await bake('build', opts);
 })();
 
@@ -50,3 +52,52 @@ function build(): void {
     logger.debug(`Build succeeded:\n${res.stdout || res.stderr}`);
   }
 }
+
+async function buildMkdocs(version: string | undefined): Promise<void> {
+  logger.info('Building Mkdocs site ...');
+
+  const mkdocsArgs = ['mkdocs', 'build'];
+  if (version) {
+    mkdocsArgs.push('--version', version);
+  }
+
+  const mkdocsRes = exec('pnpm', mkdocsArgs);
+
+  if (mkdocsRes.signal) {
+    logger.error(`Signal received: ${mkdocsRes.signal}`);
+    process.exit(-1);
+  } else if (mkdocsRes.exitCode) {
+    logger.error(
+      `Error occurred building mkdocs:\n${mkdocsRes.stderr || mkdocsRes.stdout}`,
+    );
+    process.exit(mkdocsRes.exitCode);
+  } else {
+    logger.debug(
+      `Mkdocs build succeeded:\n${mkdocsRes.stdout || mkdocsRes.stderr}`,
+    );
+  }
+
+  // Package the mkdocs site to attach to the release
+  logger.info('Packaging Mkdocs site ...');
+  await fs.ensureDir('tmp');
+
+  const tarRes = exec('tar', [
+    '-czf',
+    'tmp/mkdocs-site.tgz',
+    '-C',
+    'tools/mkdocs/site',
+    '.',
+  ]);
+
+  if (tarRes.signal) {
+    logger.error(`Signal received: ${tarRes.signal}`);
+    process.exit(-1);
+  } else if (tarRes.exitCode) {
+    logger.error(
+      `Error occurred creating mkdocs-site.tgz:\n${tarRes.stderr || tarRes.stdout}`,
+    );
+    process.exit(tarRes.exitCode);
+  } else {
+    logger.info('Mkdocs site packaged successfully to tmp/mkdocs-site.tgz');
+  }
+}