CI improvements: caching, gating, and robustness (#60)

## Summary

Improvements to the CI and publish workflows. No library code is
changed.

## Changes

**Speed & hygiene** (`ci.yml`)
- Add ccache to the host `build`/`test`/`conformance` jobs, which
otherwise
  recompile all ~260 libopus `.c` files from scratch every run. Uses
apt-installed ccache + the existing pinned `actions/cache`; no new
actions.
- `concurrency` so new commits supersede stale runs. Labeling a PR no
longer
cancels a running suite, and only the `ci-run-qemu` label triggers a
QEMU run.
- `timeout-minutes` on every job (a hung build or QEMU run no longer
sits until
  the 6-hour default).
- Add `workflow_dispatch` to run CI manually from the Actions tab.

**Publish safety** (`publish.yml`)
- `verify-version` job: fail if `library.json` / `idf_component.yml`
disagree
  with the release tag before anything ships.
- `ci-gate` job: block publish unless the `CI success` aggregate passed
on the
  release commit.

**Lint reproducibility**
- Pin the lint job to `clang-tidy-18` (matching the pinned
clang-format).
  `script/clang-tidy.sh` honors a preset `$CLANG_TIDY` so the runner's
preinstalled binary can't shadow it, and errors early if that binary is
  missing.

**Branch protection**
- Add a `ci-success` aggregating job so branch protection can require
one check
  instead of enumerating every job. Skipped jobs count as passing.

Author: kahrendt

.github/workflows/ci.yml

@@ -9,18 +9,30 @@ on:
     # `labeled` lets the `ci-run-qemu` label start a run. Every job except changes/cross-qemu is
     # gated on `github.event.action != 'labeled'`, so labeling re-runs only QEMU, not the whole suite.
     types: [opened, synchronize, reopened, labeled]
+  # Manual "Run workflow" from the Actions tab. The changes job's fail-safe (unreachable base) runs
+  # the full suite including QEMU on a dispatch, which is what you want from a manual trigger.
+  workflow_dispatch:
 
 # Least privilege: every job here only reads the repo (checkout, build, test, cache). Jobs that
 # need more should add a narrower job-level permissions block rather than widening this default.
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Don't cancel an in-progress run when a label is added. The `labeled` trigger fires for every
+  # label (it exists so `ci-run-qemu` can force a QEMU run), and a labeled event shares this group,
+  # so cancelling here would kill a running suite just because the PR was labeled. New commits
+  # (push/synchronize) still supersede a run.
+  cancel-in-progress: ${{ github.event.action != 'labeled' }}
+
 jobs:
   pre-commit:
     name: Pre-commit checks
     # Skip on label-only events so labeling runs only the QEMU job (see pull_request types).
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
@@ -34,6 +46,7 @@ jobs:
     name: Static analysis
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
@@ -42,22 +55,41 @@ jobs:
       - name: Install clang-tidy
         run: |
           sudo apt-get update
-          sudo apt-get install -y clang-tidy
+          sudo apt-get install -y clang-tidy-18
 
       - name: Run clang-tidy
+        env:
+          CLANG_TIDY: clang-tidy-18
         run: ./script/clang-tidy.sh
 
   build:
     name: Build
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # libopus is ~260 .c files rebuilt from scratch in every host job; ccache reuses objects across runs.
+    env:
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           submodules: recursive
 
+      - name: Install ccache
+        run: sudo apt-get update && sudo apt-get install -y ccache
+
+      - name: Cache ccache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ${{ github.workspace }}/.ccache
+          key: ccache-build-${{ github.sha }}
+          restore-keys: ccache-build-
+
       - name: Configure CMake
-        run: cmake -B build host_examples/opus_to_wav
+        run: >
+          cmake -B build
+          -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+          host_examples/opus_to_wav
 
       - name: Build
         run: cmake --build build
@@ -66,6 +98,9 @@ jobs:
     name: Unit tests (${{ matrix.alloc_mode }})
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
     strategy:
       fail-fast: false
       matrix:
@@ -77,9 +112,20 @@ jobs:
         with:
           submodules: recursive
 
+      - name: Install ccache
+        run: sudo apt-get update && sudo apt-get install -y ccache
+
+      - name: Cache ccache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ${{ github.workspace }}/.ccache
+          key: ccache-test-${{ matrix.alloc_mode }}-${{ github.sha }}
+          restore-keys: ccache-test-${{ matrix.alloc_mode }}-
+
       - name: Configure CMake with sanitizers
         run: >
           cmake -B build -DENABLE_SANITIZERS=ON
+          -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
           -DOPUS_ALLOCATION_MODE=${{ matrix.alloc_mode }} tests
 
       - name: Build
@@ -92,11 +138,24 @@ jobs:
     name: opus_compare conformance
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           submodules: recursive
 
+      - name: Install ccache
+        run: sudo apt-get update && sudo apt-get install -y ccache
+
+      - name: Cache ccache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ${{ github.workspace }}/.ccache
+          key: ccache-conformance-${{ github.sha }}
+          restore-keys: ccache-conformance-
+
       # The RFC 8251 test vectors are static; cache them so we don't re-download every run. Keying on
       # the fetch script means the cache auto-invalidates if the vector URL ever changes.
       - name: Cache test vectors
@@ -111,7 +170,10 @@ jobs:
         run: tests/fetch_vectors.sh
 
       - name: Configure CMake
-        run: cmake -B build tests
+        run: >
+          cmake -B build
+          -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+          tests
 
       - name: Build
         run: cmake --build build
@@ -128,6 +190,7 @@ jobs:
   changes:
     name: Detect on-target changes
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     outputs:
       target: ${{ steps.filter.outputs.target }}
     steps:
@@ -162,11 +225,13 @@ jobs:
   cross-qemu:
     name: Cross (Xtensa QEMU conformance, ${{ matrix.variant }})
     needs: changes
-    # Skip on wrapper-only changes. Add the `ci-run-qemu` label to force a run.
+    # Skip on wrapper-only changes. Add the `ci-run-qemu` label to force a run. On a `labeled` event
+    # only that label triggers QEMU, so adding an unrelated label doesn't kick off a redundant run.
     if: >
-      needs.changes.outputs.target == 'true' ||
+      (github.event.action != 'labeled' && needs.changes.outputs.target == 'true') ||
       contains(github.event.pull_request.labels.*.name, 'ci-run-qemu')
     runs-on: ubuntu-latest
+    timeout-minutes: 40
     # esp-idf version matches the PlatformIO framework (esp-idf v5.4.x) so the
     # xtensa-gcc codegen is the same as the local run. Xtensa emulation is
     # native-speed on the amd64 runner.
@@ -240,6 +305,7 @@ jobs:
     name: PlatformIO Build
     if: github.event.action != 'labeled'
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     strategy:
       matrix:
         example: [decode_benchmark, encode_benchmark]
@@ -267,3 +333,31 @@ jobs:
 
       - name: Build ${{ matrix.example }}
         run: pio run -d examples/${{ matrix.example }}
+
+  # Single aggregating status for branch protection: require only "CI success" instead of every job.
+  # always() so it reports even when a job fails or the conditional cross-qemu job is skipped; skipped
+  # dependencies are treated as passing (only failure/cancelled blocks).
+  ci-success:
+    name: CI success
+    if: always()
+    needs:
+      - pre-commit
+      - lint
+      - build
+      - test
+      - conformance
+      - changes
+      - cross-qemu
+      - platformio
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Fail if any required job failed or was cancelled
+        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+        run: |
+          echo "One or more CI jobs failed or were cancelled:"
+          echo '${{ toJSON(needs) }}'
+          exit 1
+
+      - name: Report success
+        run: echo "All required CI jobs passed (skipped jobs are allowed)."

.github/workflows/publish.yml

@@ -10,8 +10,54 @@ permissions:
   contents: read
 
 jobs:
+  verify-version:
+    name: Verify version matches tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Check library.json and idf_component.yml against the release tag
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          expected="${TAG#v}"
+          lib="$(jq -r '.version' library.json)"
+          idf="$(grep -m1 '^version:' idf_component.yml | sed -e 's/^version:[[:space:]]*//' -e 's/"//g' -e 's/[[:space:]]*$//')"
+          echo "tag=$TAG expected=$expected library.json=$lib idf_component.yml=$idf"
+          fail=0
+          [ "$lib" = "$expected" ] || { echo "::error::library.json version ($lib) != release tag ($expected)"; fail=1; }
+          [ "$idf" = "$expected" ] || { echo "::error::idf_component.yml version ($idf) != release tag ($expected)"; fail=1; }
+          exit $fail
+
+  ci-gate:
+    name: CI gate
+    runs-on: ubuntu-latest
+    permissions:
+      checks: read
+    steps:
+      - name: Verify CI passed on the release commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Block the release unless the aggregate "CI success" check passed on this commit. That job
+          # (ci-success in ci.yml) needs every other job and fails if any failed or was cancelled,
+          # with skipped jobs (e.g. the conditional QEMU run) treated as passing, so gating on it
+          # alone covers the whole suite and tracks future job changes. The release tag name is the
+          # check-runs ref so the API resolves it to the underlying commit (github.sha can be an
+          # annotated tag's object SHA, which carries no check runs). Take the most recently completed
+          # "CI success" run in case the commit was built more than once.
+          conclusion="$(gh api "repos/${{ github.repository }}/commits/${{ github.event.release.tag_name }}/check-runs" \
+            --paginate --jq '.check_runs[] | select(.name == "CI success" and .status == "completed") | "\(.completed_at) \(.conclusion)"' \
+            | sort | tail -1 | awk '{print $NF}')"
+          echo "Latest completed 'CI success' conclusion: ${conclusion:-<none found>}"
+          if [ "$conclusion" != "success" ]; then
+            echo "::error::CI success did not pass on the release commit (got '${conclusion:-not found}'). Refusing to publish."
+            exit 1
+          fi
+          echo "CI success passed on the release commit; proceeding to publish."
+
   publish-platformio:
     name: Publish to PlatformIO
+    needs: [verify-version, ci-gate]
     runs-on: ubuntu-latest
     environment: platformio
     steps:
@@ -31,6 +77,7 @@ jobs:
 
   publish-espressif:
     name: Publish to Espressif
+    needs: [verify-version, ci-gate]
     runs-on: ubuntu-latest
     environment: espressif
     permissions:

script/clang-tidy.sh

@@ -11,14 +11,16 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT_DIR="$(dirname "$SCRIPT_DIR")"
 BUILD_DIR="${ROOT_DIR}/host_examples/opus_to_wav/build"
 
-# Find clang-tidy
-CLANG_TIDY=""
-for name in clang-tidy clang-tidy-18 clang-tidy-17 clang-tidy-16 clang-tidy-15; do
-    if command -v "$name" &> /dev/null; then
-        CLANG_TIDY="$name"
-        break
-    fi
-done
+# Find clang-tidy. A pre-set $CLANG_TIDY (CI pins it to clang-tidy-18) wins over PATH discovery.
+CLANG_TIDY="${CLANG_TIDY:-}"
+if [ -z "$CLANG_TIDY" ]; then
+    for name in clang-tidy clang-tidy-18 clang-tidy-17 clang-tidy-16 clang-tidy-15; do
+        if command -v "$name" &> /dev/null; then
+            CLANG_TIDY="$name"
+            break
+        fi
+    done
+fi
 
 # Check Homebrew LLVM paths on macOS
 if [ -z "$CLANG_TIDY" ]; then
@@ -30,8 +32,10 @@ if [ -z "$CLANG_TIDY" ]; then
     done
 fi
 
-if [ -z "$CLANG_TIDY" ]; then
-    echo "Error: clang-tidy not found"
+# Validate the resolved binary up front: catches both an empty result and a bogus pre-set
+# $CLANG_TIDY, instead of failing later with a bare "command not found".
+if ! command -v "$CLANG_TIDY" &> /dev/null; then
+    echo "Error: clang-tidy not found or not executable: '${CLANG_TIDY:-unset}'"
     exit 1
 fi