Various improvements to the CI setup (ukri-excalibur#289)

* Run jobs only when relevant files are touched
* Set lower timeout for all jobs, to avoid rogue jobs to run needlessly for
  hours
* Set concurrency groups, to cancel jobs if there are new commits on the same
  branch
* More informative message for commits pushing docs preview
* Push documentation only on pushes to `main`

.github/workflows/ci.yml

@@ -4,12 +4,32 @@ on:
   push:
     branches: "main"
     tags: ["*"]
+    paths:
+      - '.github/workflows/ci.yml'
+      - 'MANIFEST.in'
+      - 'pyproject.toml'
+      - 'benchmarks/examples/**'
+      - 'benchmarks/modules/**'
+      - 'post-processing/**'
   pull_request:
+    paths:
+      - '.github/workflows/ci.yml'
+      - 'MANIFEST.in'
+      - 'pyproject.toml'
+      - 'benchmarks/examples/**'
+      - 'benchmarks/modules/**'
+      - 'post-processing/**'
   release:
 
 env:
   RFM_CONFIG_FILES: "${{ github.workspace }}/benchmarks/reframe_config.py"
 
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: always.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     name: Tests on ${{ matrix.os }} - Spack ${{ matrix.spack_version }} - Spack spec ${{ matrix.spack_spec }}

.github/workflows/docs.yml

@@ -3,14 +3,39 @@ on:
   push:
     branches:
       - main
+    paths:
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+      - 'docs/**'
+      - 'benchmarks/**/*.md'
+      - 'post-processing/**/*.md'
   pull_request:
     branches:
       - main
+    paths:
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+      - 'docs/**'
+      - 'benchmarks/**/*.md'
+      - 'post-processing/**/*.md'
+
+concurrency:
+  # Same group concurrency as the `docs_cleanup.yml` workflow, because they both
+  # git-push to the same branch, so we want to avoid clashes.  NOTE: this is
+  # different from the concurrency group below, which is to cancel successive
+  # jobs from within the branch/PR.
+  group: docs-pushing
 
 jobs:
   build:
+    timeout-minutes: 10
     name: Deploy docs
     runs-on: ubuntu-latest
+    concurrency:
+      # Skip intermediate builds: always.
+      # Cancel intermediate builds: always.
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     steps:
       - name: Checkout main
         uses: actions/checkout@v4
@@ -22,7 +47,7 @@ jobs:
 
       - name: Install mkdocs
         run: pip install mkdocs-material
-        
+
       - name: Checkout gh-pages
         uses: actions/checkout@v4
         with:
@@ -39,12 +64,18 @@ jobs:
           mkdocs build
 
       - name: Deploy docs
-        if: ${{ github.event_name == 'push' || ! github.event.pull_request.head.repo.fork }}
+        # Run only if push is to `main`, or if it's a PR not from a fork.
+        if: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') || (github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork) }}
         run: |
           cd gh-pages
           cp -fr ../site/* .
-          git add .
           git config user.name ${{github.actor}}
           git config user.email "${{github.actor_id}}+${{github.actor}}@users.noreply.github.com"
-          git commit -m "Update docs from ${{ github.sha }}"
+          git add .
+          if [[ ${{ github.event_name }} == 'pull_request' ]]; then
+              COMMIT_MESSAGE="Update docs preview from ${{ github.sha }} for PR #${{ github.event.number }}"
+          else
+              COMMIT_MESSAGE="Update docs from ${{ github.sha }}"
+          fi
+          git commit -m "${COMMIT_MESSAGE}"
           git push origin gh-pages

.github/workflows/docs_cleanup.yml

@@ -4,8 +4,14 @@ on:
   pull_request:
     types: [closed]
 
+concurrency:
+  # Same group concurrency as the `docs.yml` workflow, because they both
+  # git-push to the same branch, so we want to avoid clashes.
+  group: docs-pushing
+
 jobs:
   doc-preview-cleanup:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
       - name: Checkout gh-pages branch