Add tmate actions to debug GitHub CI failures (#776)

Also, restrict GitHub CI runs on pushes/pull requests on `development`
and `main` branches.

.github/workflows/build.yml

@@ -2,15 +2,24 @@ name: Build
 
 on: 
   push:
+    branches: [development, main]
     paths-ignore:
       - 'README.md'
       - 'INSTALL.md'
       - 'docs/**'
   pull_request:
+    branches: [development, main]
     paths-ignore:
       - 'README.md'
       - 'INSTALL.md'
       - 'docs/**'
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled'
+        required: false
+        default: true
 
 jobs:
   run:
@@ -71,6 +80,10 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Setup tmate session
+      uses: mxschmitt/action-tmate@v3.13
+      if: ${{ inputs.debug_enabled }}
+
     - name: add oneAPI to apt
       if: ${{ matrix.useoneAPI }}
       shell: bash
@@ -172,3 +185,7 @@ jobs:
     - name: Upload code coverage
       if: ${{ matrix.OCCA_COVERAGE }}
       run: bash <(curl --no-buffer -s https://codecov.io/bash) -x "${GCOV}"
+
+    - name: Block to allow inspecting failures
+      run: sleep 1800
+      if: ${{ failure() && inputs.debug_enabled }}

README.md

@@ -121,6 +121,13 @@ $ occa info
 ========+======================+=================================
 ```
 
+## Debug
+
+### GitHub CI failures
+
+We use [tmate action](https://github.com/mxschmitt/action-tmate) for debugging GitHub CI workflows with a [manually triggered debug](https://github.com/mxschmitt/action-tmate?tab=readme-ov-file#manually-triggered-debug) event.
+See [GitHub docs](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow) on how to initiate a manual debug run (make sure to check the `Run the build with tmate debugging enabled` box).
+
 ## Community
 
 ### Support