refactor: create generic cache restore action (DRY)

Consolidates cache clearing + restore logic into a single reusable
action to eliminate key synthesis duplication.

Changes:
- New xahau-ga-cache-restore action (wraps clear + restore)
- Integrates cache clearing directly into restore operation
- Eliminates separate cache clearing steps
- Cache keys built once in restore action (not duplicated)

Usage:
- ccache: two restore calls (main + current branch dual-cache)
- Conan: one restore call (single cache)
- Saves use actions/cache/save@v4 directly (no wrapper needed)

Benefits:
- DRY: cache keys no longer synthesized in multiple places
- Cleaner: cache clearing automatic during restore
- Simpler: one action call instead of two steps per cache

.github/actions/xahau-ga-build/action.yml

@@ -71,29 +71,22 @@ runs:
         SAFE_BRANCH=$(echo "${{ github.ref_name }}" | tr -c 'a-zA-Z0-9_.-' '-')
         echo "name=${SAFE_BRANCH}" >> $GITHUB_OUTPUT
 
-    - name: Clear ccache if requested via commit message
-      if: inputs.ccache_enabled == 'true'
-      uses: ./.github/actions/xahau-ga-clear-cache
-      with:
-        cache-key: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ steps.safe-branch.outputs.name }}
-        cache-type: ccache
-        additional-keys: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ inputs.main_branch }}
-
     - name: Restore ccache directory for main branch
       if: inputs.ccache_enabled == 'true'
       id: ccache-restore
-      uses: actions/cache/restore@v4
+      uses: ./.github/actions/xahau-ga-cache-restore
       with:
         path: ~/.ccache-main
         key: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ inputs.main_branch }}
         restore-keys: |
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-
+        cache-type: ccache-main
 
     - name: Restore ccache directory for current branch
       if: inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name != inputs.main_branch
       id: ccache-restore-current-branch
-      uses: actions/cache/restore@v4
+      uses: ./.github/actions/xahau-ga-cache-restore
       with:
         path: ~/.ccache-current
         key: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ steps.safe-branch.outputs.name }}
@@ -101,6 +94,7 @@ runs:
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ inputs.main_branch }}
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-
+        cache-type: ccache-current
 
     - name: Configure ccache
       if: inputs.ccache_enabled == 'true'

.github/actions/xahau-ga-cache-restore/action.yml

@@ -0,0 +1,56 @@
+name: 'Cache Restore'
+description: 'Restores cache with optional clearing based on commit message tags'
+
+inputs:
+  path:
+    description: 'A list of files, directories, and wildcard patterns to cache'
+    required: true
+  key:
+    description: 'An explicit key for restoring the cache'
+    required: true
+  restore-keys:
+    description: 'An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key'
+    required: false
+    default: ''
+  cache-type:
+    description: 'Type of cache (for logging purposes, e.g., "ccache-main", "Conan")'
+    required: false
+    default: 'cache'
+  fail-on-cache-miss:
+    description: 'Fail the workflow if cache entry is not found'
+    required: false
+    default: 'false'
+  lookup-only:
+    description: 'Check if a cache entry exists for the given input(s) without downloading it'
+    required: false
+    default: 'false'
+
+outputs:
+  cache-hit:
+    description: 'A boolean value to indicate an exact match was found for the primary key'
+    value: ${{ steps.restore-cache.outputs.cache-hit }}
+  cache-primary-key:
+    description: 'The key that was used to restore the cache'
+    value: ${{ steps.restore-cache.outputs.cache-primary-key }}
+  cache-matched-key:
+    description: 'The key that was used to restore the cache (exact or prefix match)'
+    value: ${{ steps.restore-cache.outputs.cache-matched-key }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Clear cache if requested via commit message
+      uses: ./.github/actions/xahau-ga-clear-cache
+      with:
+        cache-key: ${{ inputs.key }}
+        cache-type: ${{ inputs.cache-type }}
+
+    - name: Restore cache
+      id: restore-cache
+      uses: actions/cache/restore@v4
+      with:
+        path: ${{ inputs.path }}
+        key: ${{ inputs.key }}
+        restore-keys: ${{ inputs.restore-keys }}
+        fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
+        lookup-only: ${{ inputs.lookup-only }}

.github/actions/xahau-ga-dependencies/action.yml

@@ -63,17 +63,10 @@ outputs:
 runs:
   using: 'composite'
   steps:
-    - name: Clear Conan cache if requested via commit message
-      if: inputs.cache_enabled == 'true'
-      uses: ./.github/actions/xahau-ga-clear-cache
-      with:
-        cache-key: ${{ runner.os }}-conan-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ hashFiles('**/conanfile.py') }}-${{ inputs.configuration }}
-        cache-type: Conan
-
     - name: Restore Conan cache
       if: inputs.cache_enabled == 'true'
       id: cache-restore-conan
-      uses: actions/cache/restore@v4
+      uses: ./.github/actions/xahau-ga-cache-restore
       with:
         path: ~/.conan2
         # Note: compiler-id format is compiler-version-stdlib[-gccversion]
@@ -81,6 +74,7 @@ runs:
         restore-keys: |
           ${{ runner.os }}-conan-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ hashFiles('**/conanfile.py') }}-
           ${{ runner.os }}-conan-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-
+        cache-type: Conan
 
     - name: Configure Conan
       shell: bash