Unified CI workflow for smarter PR gating

.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+  actions: read
+  packages: read
+
+jobs:
+  # Compute once which path groups changed; every other job references these
+  # outputs. dorny/paths-filter handles PR base diff, push base diff, and
+  # empty results on non-diff events (workflow_dispatch); the `if:` guards
+  # below explicitly opt manual runs back into running everything.
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    outputs:
+      builds: ${{ steps.filter.outputs.builds }}
+      tests:  ${{ steps.filter.outputs.tests }}
+      docs:   ${{ steps.filter.outputs.docs }}
+      cpp_checks: ${{ steps.filter.outputs.cpp_checks }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d  # v4.0.1
+        id: filter
+        with:
+          filters: |
+            builds:
+              - src/**
+              - include/**
+              - benchmarks/**
+              - cpp-example-collection
+              - cpp-example-collection/**
+              - client-sdk-rust/**
+              - cmake/**
+              - docker/**
+              - CMakeLists.txt
+              - CMakePresets.json
+              - build*
+              - .build*
+              - vcpkg.json
+              - .github/workflows/ci.yml
+              - .github/workflows/builds.yml
+            tests:
+              - src/**
+              - include/**
+              - client-sdk-rust/**
+              - cmake/**
+              - .token_helpers/**
+              - CMakeLists.txt
+              - CMakePresets.json
+              - build*
+              - .build*
+              - vcpkg.json
+              - .github/workflows/ci.yml
+              - .github/workflows/tests.yml
+            docs:
+              - README.md
+              - include/**
+              - docs/**
+              - scripts/generate-docs.sh
+              - .github/workflows/ci.yml
+              - .github/workflows/generate-docs.yml
+              - .github/workflows/publish-docs.yml
+              - "!AGENTS.md"
+            cpp_checks:
+              - src/**
+              - include/**
+              - benchmarks/**
+              - client-sdk-rust/**
+              - cmake/**
+              - CMakeLists.txt
+              - CMakePresets.json
+              - scripts/clang-format.sh
+              - scripts/clang-tidy.sh
+              - .clang-format
+              - .clang-tidy
+              - .github/workflows/ci.yml
+              - .github/workflows/cpp-checks.yml
+
+  builds:
+    name: Builds
+    needs: changes
+    if: ${{ needs.changes.outputs.builds == 'true' || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/builds.yml
+    secrets: inherit
+
+  tests:
+    name: Tests
+    needs: changes
+    if: ${{ needs.changes.outputs.tests == 'true' || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/tests.yml
+    secrets: inherit
+
+  # license-check is cheap (seconds) and broad enough that it should run on
+  # every PR.
+  license-check:
+    name: License Check
+    uses: ./.github/workflows/license_check.yml
+
+  cpp-checks:
+    name: C++ Checks
+    needs: changes
+    if: ${{ needs.changes.outputs.cpp_checks == 'true' || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/cpp-checks.yml
+
+  generate-docs:
+    name: Generate Docs
+    needs: changes
+    if: ${{ needs.changes.outputs.docs == 'true' || github.event_name == 'workflow_dispatch' }}
+    uses: ./.github/workflows/generate-docs.yml
+
+  # Context: GitHub repository rulesets "required checks" actually need a job name to list.
+  # This job is an aggregate job
+  ci:
+    name: CI
+    runs-on: ubuntu-latest
+    # List all the jobs that need to succeed for the CI to pass
+    needs:
+      - changes
+      - builds
+      - tests
+      - license-check
+      - cpp-checks
+      - generate-docs
+    if: always()
+    steps:
+      - name: Verify required CI jobs
+        uses: suzuki-shunsuke/required-status-check-action@2b5a46064846b09381852c2c4217e898f639e768  # v0.1.3
+        with:
+          needs: ${{ toJson(needs) }}

.github/workflows/cpp-checks.yml

@@ -0,0 +1,111 @@
+name: C++ Checks
+
+# Called by top-level ci.yml
+on:
+  workflow_call: {}
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  clang-format:
+    name: clang-format
+    runs-on: ubuntu-latest
+    continue-on-error: false
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # No submodules: scripts/clang-format.sh only walks our own src/ tree
+          fetch-depth: 1
+
+      - name: Install clang-format 22
+        run: |
+          set -eux
+          # Pin clang-format 22 to match the current macOS Homebrew LLVM
+          # Ubuntu 24.04's default clang-format ships with LLVM 18
+          sudo install -m 0755 -d /etc/apt/keyrings
+          wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
+            | sudo tee /etc/apt/keyrings/llvm.asc >/dev/null
+          sudo chmod a+r /etc/apt/keyrings/llvm.asc
+          codename=$(lsb_release -cs)
+          echo "deb [signed-by=/etc/apt/keyrings/llvm.asc] http://apt.llvm.org/${codename}/ llvm-toolchain-${codename}-22 main" \
+            | sudo tee /etc/apt/sources.list.d/llvm-22.list >/dev/null
+          sudo apt-get update
+          sudo apt-get install -y clang-format-22
+          sudo ln -sf /usr/bin/clang-format-22 /usr/local/bin/clang-format
+          clang-format --version
+
+      - name: Run clang-format
+        env:
+          FORMAT_BLOB_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: ./scripts/clang-format.sh
+
+  clang-tidy:
+    name: clang-tidy
+    runs-on: ubuntu-latest
+    continue-on-error: false
+
+    steps:
+      - name: Checkout (with submodules)
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          fetch-depth: 1
+
+      - name: Install dependencies
+        run: |
+          set -eux
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential cmake ninja-build pkg-config \
+            llvm-dev libclang-dev clang \
+            libssl-dev wget ca-certificates gnupg
+
+      - name: Install clang-tidy 19 (for ExcludeHeaderFilterRegex support)
+        run: |
+          set -eux
+          # Ubuntu 24.04 apt ships clang-tidy 18, which doesn't understand
+          # ExcludeHeaderFilterRegex (added in 19). Pull clang-tidy 19 from
+          # the upstream LLVM apt repository and pin the unversioned names.
+          sudo install -m 0755 -d /etc/apt/keyrings
+          wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key \
+            | sudo tee /etc/apt/keyrings/llvm.asc >/dev/null
+          sudo chmod a+r /etc/apt/keyrings/llvm.asc
+          codename=$(lsb_release -cs)
+          echo "deb [signed-by=/etc/apt/keyrings/llvm.asc] http://apt.llvm.org/${codename}/ llvm-toolchain-${codename}-19 main" \
+            | sudo tee /etc/apt/sources.list.d/llvm-19.list >/dev/null
+          sudo apt-get update
+          sudo apt-get install -y clang-tidy-19 clang-tools-19
+          sudo ln -sf /usr/bin/clang-tidy-19 /usr/local/bin/clang-tidy
+          sudo ln -sf /usr/bin/run-clang-tidy-19 /usr/local/bin/run-clang-tidy
+          clang-tidy --version
+          run-clang-tidy --help | head -1 || true
+
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+        with:
+          toolchain: stable
+
+      - name: Set Linux build environment
+        run: |
+          echo "CXXFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
+          echo "CFLAGS=-Wno-deprecated-declarations" >> "$GITHUB_ENV"
+          LLVM_VERSION=$(llvm-config --version | cut -d. -f1)
+          echo "LIBCLANG_PATH=/usr/lib/llvm-${LLVM_VERSION}/lib" >> "$GITHUB_ENV"
+
+      - name: CMake configure
+        run: cmake --preset linux-release
+
+      - name: Generate protobuf headers
+        run: cmake --build build-release --target livekit_proto
+
+      - name: Run clang-tidy
+        env:
+          TIDY_BLOB_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        # This script is intended to be run locally and in CI. It will auto-detect
+        # the GHA environment and add PR annotations and a run summary.
+        # As of writing all warnings are treateded as errors to avoid tech debt build up
+        run: ./scripts/clang-tidy.sh --fail-on-warning

.github/workflows/docker-images.yml

@@ -15,8 +15,11 @@ on:
       - CMakePresets.json
       - cmake/**
       - data/**
+      - cpp-example-collection
       - docker/Dockerfile.base
       - docker/Dockerfile.sdk
+      - .github/workflows/docker-images.yml
+      - .github/workflows/docker-validate.yml
 
 permissions:
   contents: read
@@ -89,7 +92,7 @@ jobs:
             fi
 
             case "${path}" in
-              docker/Dockerfile.sdk|src/*|include/*|client-sdk-rust/*|cmake/*|data/*|CMakeLists.txt|build.sh|build.cmd|build.h.in|.build-info.json.in|CMakePresets.json)
+              docker/Dockerfile.sdk|src/*|include/*|client-sdk-rust/*|cmake/*|data/*|cpp-example-collection|CMakeLists.txt|build.sh|build.cmd|build.h.in|.build-info.json.in|CMakePresets.json|.github/workflows/docker-images.yml|.github/workflows/docker-validate.yml)
                 sdk_changed=true
                 ;;
             esac

.github/workflows/docker-validate.yml

@@ -9,10 +9,6 @@ permissions:
   contents: read
   packages: read
 
-env:
-  # Pinned commit for cpp-example-collection smoke build (https://github.com/livekit-examples/cpp-example-collection)
-  CPP_EXAMPLE_COLLECTION_REF: bbf0fdf72dac2239117213475449565686f8c58b
-
 jobs:
   validate-x64:
     name: Validate Docker image (linux-x64)
@@ -23,6 +19,11 @@ jobs:
       github.event.workflow_run.head_branch == 'main'
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
       - name: Resolve image name
         id: refs
         shell: bash
@@ -52,7 +53,8 @@ jobs:
 
       - name: Build cpp-example-collection against installed SDK
         run: |
-          docker run -e CPP_EX_REF="${{ env.CPP_EXAMPLE_COLLECTION_REF }}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
             set -euxo pipefail
             git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
             cd /tmp/cpp-example-collection
@@ -71,6 +73,11 @@ jobs:
       github.event.workflow_run.head_branch == 'main'
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 1
+
       - name: Resolve image name
         id: refs
         shell: bash
@@ -100,7 +107,8 @@ jobs:
 
       - name: Build cpp-example-collection against installed SDK
         run: |
-          docker run -e CPP_EX_REF="${{ env.CPP_EXAMPLE_COLLECTION_REF }}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
+          cpp_ex_ref="$(git rev-parse HEAD:cpp-example-collection)"
+          docker run -e CPP_EX_REF="${cpp_ex_ref}" --rm "${{ steps.refs.outputs.sdk_image }}" bash -lc '
             set -euxo pipefail
             git clone https://github.com/livekit-examples/cpp-example-collection.git /tmp/cpp-example-collection
             cd /tmp/cpp-example-collection

.github/workflows/generate-docs.yml

@@ -10,16 +10,9 @@ permissions:
 # The artifact is attached to the workflow run so reviewers can download a preview,
 # but also to verify the documentation artifact is valid for subsequent release runs
 # that will publish them to the LiveKit docs web page: https://docs.livekit.io/reference/client-sdk-cpp/
+# Called by top-level ci.yml on PRs. PR trigger lives in the parent
+# so a single "CI" check gates every PR regardless of paths.
 on:
-  pull_request:
-    branches: ["main"]
-    paths:
-      - include/**
-      - src/**
-      - docs/**
-      - scripts/generate-docs.sh
-      - .github/workflows/generate-docs.yml
-      - .github/workflows/publish-docs.yml
   workflow_call:
     inputs:
       version:

.github/workflows/make-release.yml

@@ -13,11 +13,6 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
-  # sccache caches rustc invocations across runs. RUSTC_WRAPPER is exported
-  # only after the setup step verifies the GHA cache backend is reachable, so
-  # transient cache backend failures fall back to uncached rustc instead of
-  # failing the build.
-  SCCACHE_GHA_ENABLED: "true"
   VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
   VCPKG_DEFAULT_TRIPLET: x64-windows-static-md
   VCPKG_DEFAULT_HOST_TRIPLET: x64-windows-static-md
@@ -140,21 +135,16 @@ jobs:
         if: matrix.name == 'macos-x64'
         run: rustup target add x86_64-apple-darwin
 
-      # ---------- Setup sccache ----------
-      - name: Setup sccache
-        uses: mozilla-actions/sccache-action@054db53350805f83040bf3e6e9b8cf5a139aa7c9 # v0.0.7
-
-      - name: Enable sccache wrapping (probe first)
+      # ---------- Cache Cargo ----------
+      # Key the target cache on the client-sdk-rust submodule SHA (Cargo.lock is
+      # pinned inside the submodule and froze the old cache). No clean step runs
+      # in this workflow, so the combined actions/cache post-job save captures
+      # the populated target/ correctly once the key busts on a submodule bump.
+      - name: Resolve Rust submodule SHA
+        id: rust_sha
         shell: bash
-        run: |
-          if sccache --start-server >/dev/null 2>&1; then
-            echo "RUSTC_WRAPPER=sccache" >> "$GITHUB_ENV"
-            echo "::notice::sccache enabled (RUSTC_WRAPPER=sccache)"
-          else
-            echo "::warning::sccache backend unreachable; building without compile cache this run"
-          fi
+        run: echo "sha=$(git -C client-sdk-rust rev-parse HEAD)" >> "$GITHUB_OUTPUT"
 
-      # ---------- Cache Cargo ----------
       - name: Cache Cargo registry
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
@@ -170,7 +160,7 @@ jobs:
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: client-sdk-rust/target/
-          key: ${{ runner.os }}-${{ matrix.name }}-cargo-target-${{ hashFiles('client-sdk-rust/Cargo.lock') }}
+          key: ${{ runner.os }}-${{ matrix.name }}-cargo-target-${{ steps.rust_sha.outputs.sha }}
           restore-keys: |
             ${{ runner.os }}-${{ matrix.name }}-cargo-target-