workflows/release-documentation: Rework workflow to make it testable

[tstellar]

This includes several separate changes for the workflow, which were necessary to get the testing to pass:

• Merged release-man-pages-validate-input into the release-documentation job.
• Split the release note uploading into a separate job.
• Moved the environment declaration to the upload-man-pages job.
• Stopped forcing clang as the compiler in build-docs.sh script. This was causing the runtimes build to fail, because the default Ubuntu debian packages for clang where not providing all the necessary CMake files. It seems that when you use clang as the compiler, the runtimes try to use the cmake files installed along with it.

[llvmorg-github-actions]

@llvm/pr-subscribers-github-workflow

Author: Tom Stellard (tstellar)

Changes

Removed the environment declaration from the validation job and split out the www-releases update into a separate job. This makes it safe and possible to add a pull_request trigger so we can at least test building the documentation when someone submits a pull request.

---

Full diff: https://github.com/llvm/llvm-project/pull/214304.diff

2 Files Affected:

• (modified) .github/workflows/release-documentation.yml (+57-66)
• (modified) llvm/utils/release/build-docs.sh (-6)

diff --git a/.github/workflows/release-documentation.yml b/.github/workflows/release-documentation.yml
index d0b6a9994edb5..c19148017cfec 100644
--- a/.github/workflows/release-documentation.yml
+++ b/.github/workflows/release-documentation.yml
@@ -38,76 +38,43 @@ on:
       LLVM_TOKEN_GENERATOR_PRIVATE_KEY:
         description: "Private key for our GitHub App we use for generating access tokens."
         required: true
+  # Run on pull_requests for testing purposes.
+  pull_request:
+    paths:
+      - '.github/workflows/release-documentation.yml'
+      - 'llvm/utils/release/build-docs.sh'
+    types:
+      - opened
+      - synchronize
+      - reopened
+      # When a PR is closed, we still start this workflow, but then skip
+      # all the jobs, which makes it effectively a no-op.  The reason to
+      # do this is that it allows us to take advantage of concurrency groups
+      # to cancel in progress CI jobs whenever the PR is closed.
+      - closed
+
+concurrency:
+  group: release-documentation-${{ inputs.release-version || github.event.pull_request.number }}
+  cancel-in-progress: true
 
 jobs:
-  # This job checks permissions and validates inputs to prevent potential
-  # malicious actions.  Since the release-documentation job has contents: write
-  # permissions we need to be extra careful about who can run the job and what
-  # inputs can be provided.
-  release-man-pages-validate-input:
-    name: Release Man Pages Validate Input
-    runs-on: ubuntu-24.04
-    environment:
-      name: release
-      deployment: false
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-          sparse-checkout: |
-            .github/workflows/
-
-      - name: Check Permissions
-        uses: ./.github/workflows/require-team-membership
-        with:
-          team-slug: llvm-release-managers
-          LLVM_TOKEN_GENERATOR_CLIENT_ID: ${{ secrets.LLVM_TOKEN_GENERATOR_CLIENT_ID }}
-          LLVM_TOKEN_GENERATOR_PRIVATE_KEY: ${{ secrets.LLVM_TOKEN_GENERATOR_PRIVATE_KEY }}
-
-      - name: Validate Input
-        uses: ./.github/workflows/validate-release-version
-        with:
-          release-version: ${{ inputs.release-version }}
-
   release-documentation:
     name: Build and Upload Release Documentation and Man Pages
     runs-on: ubuntu-24.04
-    needs:
-      - release-man-pages-validate-input
+    if: >-
+      github.repository_owner == 'llvm' &&
+      github.event.action != 'closed'
     outputs:
       man-page-digest: ${{ steps.man-page-digest.outputs.man-page-digest }}
       man-page-artifact-id: ${{ steps.man-page-artifact-upload.outputs.artifact-id }}
-
-      man-page-release-version: ${{ steps.vars.outputs.man-page-release-version }}
-      man-page-tarball-name: ${{ steps.vars.outputs.man-page-tarball-name }}
-      man-page-upload: ${{ steps.vars.outputs.man-page-upload }}
-      man-page-attestation-name: ${{ steps.vars.outputs.man-page-attestation-name }}
-    env:
-      upload: ${{ inputs.upload && !contains(inputs.release-version, 'rc') }}
     steps:
-      - name: Collect Variables
-        id: vars
-        env:
-          INPUTS_RELEASE_VERSION: ${{ inputs.release-version }}
-          UPLOAD_MAN_PAGES: ${{ inputs.upload }}
-        shell: bash
-        run: |
-          {
-            echo "man-page-release-version=$INPUTS_RELEASE_VERSION"
-            echo "man-page-tarball-name=llvm_man_pages-$INPUTS_RELEASE_VERSION.tar.xz"
-            echo "man-page-ref=llvmorg-$INPUTS_RELEASE_VERSION"
-            echo "man-page-upload=$UPLOAD_MAN_PAGES"
-            echo "man-page-attestation-name=$RUNNER_OS-$RUNNER_ARCH-release-man-page-attestation"
-          } >> "$GITHUB_OUTPUT"
-
       - name: Checkout LLVM
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
       - name: Validate Input
+        if: inputs.release-version
         uses: ./.github/workflows/validate-release-version
         with:
           release-version: ${{ inputs.release-version }}
@@ -129,25 +96,30 @@ jobs:
           pip3 install --require-hashes --user -r ./llvm/docs/requirements.txt
 
       - name: Build Documentation
+        id: build
         env:
           GITHUB_TOKEN: ${{ github.token }}
           INPUTS_RELEASE_VERSION: ${{ inputs.release-version }}
         run: |
-          ./llvm/utils/release/build-docs.sh -release "$INPUTS_RELEASE_VERSION" -no-doxygen
+          ./llvm/utils/release/build-docs.sh \
+            $(test -n "$INPUTS_RELEASE_VERSION" && echo -release "$INPUTS_RELEASE_VERSION" || echo -srcdir llvm) -no-doxygen
+          echo "man-page-tarball-name=$(basename $(find . -iname 'llvm_man_pages-*.tar.xz'))" >> "$GITHUB_OUTPUT"
+
 
       - name: Generate sha256 digest for man page tarball
         id: man-page-digest
         shell: bash
         env:
-          TARBALL_NAME: ${{ steps.vars.outputs.man-page-tarball-name }}
+          TARBALL_NAME: ${{ steps.build.outputs.man-page-tarball-name }}
         run: |
-            echo "man-page-digest=$(cat "$TARBALL_NAME" | sha256sum | cut -d ' ' -f 1)" >> $GITHUB_OUTPUT
+            echo "man-page-digest=$(cat "$TARBALL_NAME" | sha256sum | cut -d ' ' -f 1)" >> "$GITHUB_OUTPUT"
 
       - id: man-page-artifact-upload
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
+          name: man-pages
           path: |
-            ${{ steps.vars.outputs.man-page-tarball-name }}
+            ${{ steps.build.outputs.man-page-tarball-name }}
 
       - name: Create Release Notes Artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -155,8 +127,23 @@ jobs:
           name: release-notes
           path: docs-build/html-export/
 
+
+  upload-release-notes:
+    name: "Upload Release Notes"
+    runs-on: ubuntu-24.04
+    environment:
+      deployment: false
+      name: release
+    needs:
+      - release-documentation
+    if: >-
+      github.event_name != 'pull_request' &&
+      inputs.upload &&
+      !contains(inputs.release-version, 'rc')
+    permissions:
+      contents: read
+    steps:
       - name: Clone www-releases
-        if: env.upload
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           repository: ${{ github.repository_owner }}/www-releases
@@ -165,15 +152,19 @@ jobs:
           path: www-releases
           persist-credentials: false
 
+      - name: Download Release Notes Artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        id: download-artifact
+        with:
+          name: release-notes
+          path: ${{ github.workspace }}/www-releases/${{ inputs.release-version }}
+
       - name: Upload Release Notes
-        if: env.upload
         env:
           PUSH_TOKEN: ${{ secrets.LLVMBOT_WWW_RELEASES_PUSH }}
           GH_TOKEN: ${{ secrets.WWW_RELEASES_TOKEN }}
           INPUTS_RELEASE_VERSION: ${{ inputs.release-version }}
         run: |
-          mkdir -p www-releases/$INPUTS_RELEASE_VERSION
-          mv ./docs-build/html-export/* www-releases/$INPUTS_RELEASE_VERSION
           cd www-releases
           git checkout -b $INPUTS_RELEASE_VERSION
           git add $INPUTS_RELEASE_VERSION
@@ -203,10 +194,10 @@ jobs:
        id: man-page-artifact-upload
        uses: $/.github/workflows/upload-release-artifact
        with:
-         release-version: ${{ needs.release-documentation.outputs.man-page-release-version }}
+         release-version: ${{ inputs.release-version }}
          artifact-id: ${{ needs.release-documentation.outputs.man-page-artifact-id }}
-         attestation-name: ${{ needs.release-documentation.outputs.man-page-attestation-name }}
+         attestation-name: ${{ runner.os }}-${{ runner.arch }}-release-man-page-attestation
          digest: ${{ needs.release-documentation.outputs.man-page-digest }}
-         upload: ${{ needs.release-documentation.outputs.man-page-upload }}
+         upload: ${{ inputs.upload }}
          LLVM_TOKEN_GENERATOR_CLIENT_ID: ${{ secrets.LLVM_TOKEN_GENERATOR_CLIENT_ID }}
          LLVM_TOKEN_GENERATOR_PRIVATE_KEY: ${{ secrets.LLVM_TOKEN_GENERATOR_PRIVATE_KEY }}
diff --git a/llvm/utils/release/build-docs.sh b/llvm/utils/release/build-docs.sh
index 648c829a62618..3c80af1317d11 100755
--- a/llvm/utils/release/build-docs.sh
+++ b/llvm/utils/release/build-docs.sh
@@ -141,12 +141,6 @@ else
    echo "Doxygen: disabled"
 fi
 
-# This is just to ensure we're using the right compiler
-# When running this locally, the script otherwise might
-# prefer GCC.
-export CC=clang
-export CXX=clang++
-
 cmake -G Ninja $srcdir -B $builddir \
                -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;polly;flang${extra_man_page_projects}" \
                -DCMAKE_BUILD_TYPE=Release \

[tstellar]

/cherry-pick e310250

[tstellar]

/cherry-pick e310250

[llvmbot]

/pull-request #214834