From 75b49c7c8e48aa6bafe7bf17935a590a7fada068 Mon Sep 17 00:00:00 2001
From: Thilina Ratnayaka <thilinarmtb@users.noreply.github.com>
Date: Thu, 21 Nov 2024 10:48:18 -0600
Subject: [PATCH] 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 | 17 +++++++++++++++++
 README.md                   |  7 +++++++
 2 files changed, 24 insertions(+)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 3c64ce58e..5884add6c 100644
--- a/.github/workflows/build.yml
+++ b/.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 }}
diff --git a/README.md b/README.md
index 979232f77..e5d3eaede 100644
--- a/README.md
+++ b/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