Enhance reusable workflows (#80)

Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com>
Co-authored-by: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com>

Author: 3 people

.github/dependabot.yaml

@@ -0,0 +1,51 @@
+# ------------------------------------------------------------------------------
+# (c) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# ------------------------------------------------------------------------------
+#
+# ==============================================================================
+# Dependabot Configuration
+#
+# This configuration automates security updates for third-party GitHub Actions.
+# To protect our downstream consumers, all actions must be pinned to a
+# 40-character commit SHA rather than a mutable version tag.
+#
+# Custom rulesets in place:
+# 1. Monthly Schedule: Checks for updates once a month to minimize noise.
+# 2. Major Version Lock: Automated major updates (e.g., v9 to v10) are blocked
+#    to prevent unexpected breaking code changes.
+# 3. PR Grouping: All discovered minor/patch updates are bundled into a single
+#    monthly Pull Request instead of flooding the repository notifications.
+#
+# How to manually trigger a Major Update:
+# To safely upgrade an action to its next major version baseline:
+#   1. Open the workflow file.
+#   2. Leave the old SHA exactly as it is, but manually change the trailing
+#      comment tag to the new target baseline version (e.g., update the text
+#      from "# v4.0.0" to "# v5.0.0").
+#   3. Push your change. Dependabot will instantly recognize the target update
+#      and generate a new PR containing the correct, matching v5 commit hash.
+# ==============================================================================
+
+version: 2
+updates:
+  # Enable automatic tracking for GitHub Actions dependencies
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+
+    # Ignore rules to block major version jumps
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+
+    groups:
+      # Group all action updates into a single PR to reduce noise
+      # Rule applies across every single third-party action used in all workflows
+      github-actions-dependencies:
+        patterns:
+          - "*"

.github/pull_request_template.md

@@ -1,13 +1,14 @@
 # PR Summary
 
+<!-- One-line Summary -->
+
 Code Reviewer: <!-- CR id, filled by SSD -->
 
 <!-- To be completed by the developer -->
 
-<!-- Provide a brief description of the changes in this PR, including any notes
-     useful for reviewers -->
+<!-- Provide a brief description of the changes in this PR, including any notes useful for reviewers -->
 
-## Code Quality Checklist
+## :white_check_mark: Code Quality Checklist
 
 (_Some checks are automatically carried out via the CI pipeline_)
 
@@ -16,16 +17,12 @@ Code Reviewer: <!-- CR id, filled by SSD -->
 - [ ] The modified workflow's README has been updated, if required
 - [ ] The changes have been sufficiently tested (please describe)
 
-## AI Assistance and Attribution
+## :robot: AI Assistance and Attribution
 
-- [ ] Some of the content of this change has been produced with the assistance
-      of _Generative AI tool name_ (e.g., Met Office Github Copilot Enterprise,
-      Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the
-      [Simulation Systems AI policy](https://metoffice.github.io/simulation-systems/FurtherDetails/ai.html)
-      (including attribution labels)
+- [ ] Some of the content of this change has been produced with the assistance of _Generative AI tool name_ (e.g., Met Office GitHub Copilot Enterprise, GitHub Copilot Personal, ChatGPT GPT-4, etc) and I have followed the [Simulation Systems AI policy](https://metoffice.github.io/simulation-systems/FurtherDetails/ai.html) (including attribution labels)
 
 <!-- If AI has been used, please provide more details here -->
 
-# Code Review
+## :computer: Code Review
 
-- [ ] The changes are approriate and testing has been sufficient
+- [ ] The changes are appropriate and testing has been sufficient

.github/workflows/build-sphinx-docs.yaml

@@ -16,7 +16,7 @@ on:
         default: 'documentation'
       requirements:
         description: 'Path to the requirements file to install dependencies from'
-        required: true
+        required: false
         type: string
         default: 'requirements.txt'
       sphinx-opts:
@@ -40,22 +40,31 @@ on:
         type: number
         default: 5
 
+permissions:
+  contents: read
+
 jobs:
   build-sphinx-docs:
     name: Build Sphinx Docs
     runs-on: ${{ inputs.runner }}
     timeout-minutes: ${{ inputs.timeout }}
+    permissions:
+      contents: read  # Required to read repository file configurations
+      pages: write  # Required to deploy to GitHub Pages
+
     env:
       DOCS_DIR: ${{ inputs.docs-directory }}
       REQS_FILE: ${{ inputs.requirements }}
       SPHINX_OPTS: ${{ inputs.sphinx-opts }}
       BUILD_DIR: ${{ inputs.build-directory }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
 
       - name: Set up Python 3.12
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: '3.12'
           cache: 'pip'
@@ -80,7 +89,7 @@ jobs:
 
       - name: Upload artifact to GitHub Pages
         if: ${{ (github.event_name == 'push' || github.event_name == 'merge_group') && github.ref_name == 'main'}}
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5.0.0
         with:
           name: github-pages
           path: "$BUILD_DIR/html"

.github/workflows/call-track-review-project.yaml

@@ -1,3 +1,9 @@
+# ------------------------------------------------------------------------------
+# (c) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# ------------------------------------------------------------------------------
+
 name: Track Review Project
 
 on:
@@ -7,12 +13,20 @@ on:
       - completed
   workflow_dispatch:
 
+# Best Practice: Explicitly strip all top-level default permissions
+permissions: {}
+
 jobs:
   track_review_project:
+    # Granular permissions are safely locked directly to this specific execution context
+    permissions:
+      actions: read  # Required to view the status of the upstream triggered workflow run
+      repository-projects: write  # Required to add or mutate tasks inside GitHub Project 376
     uses: MetOffice/growss/.github/workflows/track-review-project.yaml@main
-    secrets: inherit
+    secrets:
+      PROJECT_ACTION_PAT: ${{ secrets.PROJECT_ACTION_PAT }}
     # Optional inputs (with default values)
     with:
-      runner: "ubuntu-22.04"
+      runner: "ubuntu-slim"
       project_org: "MetOffice"
       project_number: 376

.github/workflows/call-trigger-project-workflow.yaml

@@ -1,3 +1,9 @@
+# ------------------------------------------------------------------------------
+# (c) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# ------------------------------------------------------------------------------
+
 name: Trigger Review Project
 
 on:
@@ -6,7 +12,11 @@ on:
   pull_request_review:
   pull_request_review_comment:
 
+permissions: {}
+
 jobs:
   trigger_project_workflow:
+    permissions:
+      contents: read  # Required for checking out code or referencing internal workflow actions
+      pull-requests: write  # Required to modify or comment on pull requests within this pipeline process
     uses: MetOffice/growss/.github/workflows/trigger-project-workflow.yaml@main
-    secrets: inherit

.github/workflows/check-cr-approved.yaml

@@ -9,10 +9,13 @@ name: Check CR Approval
 on:
   workflow_call:
 
-permissions: read-all
+permissions:
+  contents: read  # Required to evaluate metadata from the triggering GitHub event context
+  pull-requests: read  # Required to check the PR reviews and approval status
 
 jobs:
   cr_check:
+    name: CR Approval
     runs-on: ubuntu-24.04
     timeout-minutes: 2
 
@@ -24,6 +27,12 @@ jobs:
           REPO: ${{ github.repository }}
           GH_TOKEN: ${{ github.token }}
         run: |
+          # Ensure context variables are present, don't run from a non-PR event
+          if [[ -z "$PR_NUMBER" ]]; then
+            echo "::error::This workflow must be triggered by a pull_request event."
+            exit 1
+          fi
+
           echo "Running on PR #$PR_NUMBER in Repository $REPO"
 
           # -- 1. Extract the assigned Code Reviewer from the PR body