Adding tmate action to CI for debugging (#3138)

.github/workflows/ci.yml

@@ -88,6 +88,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -98,7 +100,17 @@ jobs:
         run: |
           echo "OPENMC_CROSS_SECTIONS=$HOME/nndc_hdf5/cross_sections.xml" >> $GITHUB_ENV
           echo "OPENMC_ENDF_DATA=$HOME/endf-b-vii.1" >> $GITHUB_ENV
-
+          # get the sha of the last branch commit
+          # for push and workflow_dispatch events, use the current reference head
+          BRANCH_SHA=HEAD
+          # for a pull_request event, use the last reference of the parents of the merge commit
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            BRANCH_SHA=$(git rev-list --parents -n 1 HEAD | rev | cut -d" " -f 1 | rev)
+          fi
+          COMMIT_MESSAGE=$(git log $BRANCH_SHA -1 --pretty=%B)
+          echo ${COMMIT_MESSAGE}
+          echo "COMMIT_MESSAGE=${COMMIT_MESSAGE}" >> $GITHUB_ENV
+          
       - name: Apt dependencies
         shell: bash
         run: |
@@ -153,6 +165,12 @@ jobs:
           CTEST_OUTPUT_ON_FAILURE=1 make test -C $GITHUB_WORKSPACE/build/
           $GITHUB_WORKSPACE/tools/ci/gha-script.sh
 
+      - name: Setup tmate debug session
+        continue-on-error: true
+        if: ${{ contains(env.COMMIT_MESSAGE, '[gha-debug]') }}
+        uses: mxschmitt/action-tmate@v3
+        timeout-minutes: 10
+      
       - name: after_success
         shell: bash
         run: |

docs/source/devguide/tests.rst

@@ -84,6 +84,30 @@ that, consider the following:
   limit the number of threads that OpenBLAS uses internally; this can be done by
   setting the :envvar:`OPENBLAS_NUM_THREADS` environment variable to 1.
 
+Debugging Tests in CI
+---------------------
+
+.. _tmate: <https://github.com/mxschmitt/action-tmate?tab=readme-ov-file#debug-your-github-actions-by-using-tmate>`_
+
+Tests can be debugged in CI using a feature called `tmate`_. CI debugging can be
+enabled by including "[gha-debug]" in the commit message. When the test fails, a
+link similar to the one shown below will be provided in the GitHub Actions
+output after failure occurs. Logging into the provided link will allow you to
+debug the test in the CI environment. The following is an example of the output
+shown in the CI log that provides the link to the tmate session:
+
+.. code-block:: text
+   :linenos:
+
+   Created new session successfully
+   ssh 2VcykjU7vNdvAzEjQcc839GM2@nyc1.tmate.io
+   https://tmate.io/t/2VcykjU7vNdvAzEjQcc839GM2
+   Entering main loop
+   Web shell: https://tmate.io/t/2VcykjU7vNdvAzEjQcc839GM2
+   SSH: ssh 2VcykjU7vNdvAzEjQcc839GM2@nyc1.tmate.io
+   ...
+
+
 Generating XML Inputs
 ---------------------