Update ga workflows

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

@@ -1,11 +1,19 @@
+# -----------------------------------------------------------------------------
+# (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: Check CR approved
 
 on:
-    pull_request_review:
-        types: [submitted, edited, dismissed]
-    workflow_dispatch:
+  pull_request_review:
+    types: [submitted, edited, dismissed]
+  workflow_dispatch:
 
 jobs:
-    check_cr_approved:
-        if: ${{ github.event.pull_request.number }}
-        uses: MetOffice/growss/.github/workflows/check-cr-approved.yaml@main
+  check_cr_approved:
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+    if: ${{ github.event.pull_request.number }}
+    uses: MetOffice/growss/.github/workflows/check-cr-approved.yaml@develop

.github/workflows/cla-check.yaml

@@ -1,10 +1,29 @@
+# -----------------------------------------------------------------------------
+# (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.
+# -----------------------------------------------------------------------------
+
+# Check Contributor Licence Agreement
+
 name: Legal
 
 on:
   pull_request_target:
 
+concurrency:
+  # Automatically cancels the workflow run instantly before the
+  # engine can parse empty jobs and generate notification emails
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event.pull_request.head.repo.full_name != 'MetOffice/lfric_core' }}
+
+permissions: {}
+
 jobs:
   cla:
-    uses: MetOffice/growss/.github/workflows/cla-check.yaml@main
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+      pull-requests: write  # Required for the downstream engine to post status comments on the PR
+    uses: MetOffice/growss/.github/workflows/cla-check.yaml@develop
     with:
       runner: 'ubuntu-24.04'

.github/workflows/lint-fortran.yaml

@@ -1,10 +1,18 @@
+# -----------------------------------------------------------------------------
+# (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: Lint Fortran
 
 on:
-  pull_request_target:
+  pull_request:
 
 jobs:
   fortitude-lint:
-    uses: MetOffice/growss/.github/workflows/fortran-lint.yaml@main
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+    uses: MetOffice/growss/.github/workflows/fortran-lint.yaml@develop
     with:
       runner: 'ubuntu-24.04'

.github/workflows/sphinx-docs.yaml

@@ -0,0 +1,37 @@
+# -----------------------------------------------------------------------------
+# (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.
+# -----------------------------------------------------------------------------
+
+# Build and deploy Sphinx documentation to GitHub Pages
+
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, reopened, synchronize]
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    uses: MetOffice/growss/.github/workflows/sphinx-docs.yaml@develop
+    with:
+      python-version: "3.12.12"
+      timeout-minutes: 5
+      docs-dir: documentation
+      source-dir: documentation/source
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write

.github/workflows/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,11 +13,14 @@ on:
       - completed
 
 permissions:
-  actions: read
-  contents: read
-  pull-requests: write
+  contents: read  # Required to evaluate the event trigger metadata safely
 
 jobs:
   track_review_project:
-    uses: MetOffice/growss/.github/workflows/track-review-project.yaml@main
-    secrets: inherit
+    permissions:
+      actions: read  # Required to check out code or parse files safely
+      contents: read  # Required to read the upstream triggered workflow run artifact status
+      pull-requests: write  # Required for the downstream engine to add comments or update metadata on the PR
+    uses: MetOffice/growss/.github/workflows/track-review-project.yaml@develop
+    secrets:
+      PROJECT_ACTION_PAT: ${{ secrets.PROJECT_ACTION_PAT }}

.github/workflows/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:
@@ -7,11 +13,14 @@ on:
   pull_request_review_comment:
 
 permissions:
-  actions: read
-  contents: read
-  pull-requests: write
+  contents: read  # Required to evaluate the event trigger metadata safely
 
 jobs:
   trigger_project_workflow:
-    uses: MetOffice/growss/.github/workflows/trigger-project-workflow.yaml@main
-    secrets: inherit
+    if: github.repository == 'MetOffice/lfric_apps'
+
+    permissions:
+      actions: read  # Required to check out code or parse files safely
+      contents: read  # Required to read the upstream triggered workflow run artifact status
+      pull-requests: write  # Required for the downstream engine to add comments or update metadata on the PR
+    uses: MetOffice/growss/.github/workflows/trigger-project-workflow.yaml@develop  # zizmor: ignore[unpinned-uses]

.github/workflows/validate_symlinks.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: Validate Symlinks
 
 on:
@@ -7,4 +13,6 @@ on:
 
 jobs:
   validate_symlinks:
-    uses: MetOffice/growss/.github/workflows/validate_symlinks.yaml@main
+    permissions:
+      contents: read  # Required to evaluate the event trigger metadata safely
+    uses: MetOffice/growss/.github/workflows/validate_symlinks.yaml@develop

.github/zizmor.yml

@@ -0,0 +1,25 @@
+# ------------------------------------------------------------------------------
+# (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.
+# ------------------------------------------------------------------------------
+
+# Rules for Zizmor GitHub workflow linter. This file is used to configure which
+# rules to ignore for specific workflow files, allowing for exceptions to be
+# made where necessary while still enforcing best practices across the codebase.
+rules:
+  unpinned-uses:
+    ignore:
+      - "check-cr-approved.yaml"
+      - "cla-check.yaml"
+      - "lint-fortran.yaml"
+      - "sphinx-docs.yaml"
+      - "track-review-project.yaml"
+      - "trigger-project-workflow.yaml"
+      - "validate_symlinks.yaml"
+  dangerous-triggers:
+    ignore:
+      - "cla-check.yaml"
+      - "lint-fortran.yaml"
+      - "track-review-project.yaml"
+      - "trigger-project-workflow.yaml"

documentation/Makefile

@@ -13,7 +13,8 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 
-
+# For local deployment to ~/public_html/<repo>/<branch>
+REPO := $(notdir $(shell git rev-parse --show-toplevel))
 BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
 DEPLOYDIR	  = $(HOME)/public_html
 
@@ -29,7 +30,10 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 deploy:
-	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(DEPLOYDIR)/$(BRANCH)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(DEPLOYDIR)/$(REPO)/$(BRANCH)" $(SPHINXOPTS) $(O)
+
+lint:
+	sphinx-lint --d "horizontal-tab" --max-line-length 80 "$(SOURCEDIR)"
 
 .PHONY: clean
 clean:

documentation/source/getting_started/guide.rst

@@ -58,7 +58,7 @@ The :ref:`Technical Articles section <technical articles>`
 includes articles on several topics including the distributed memory strategy
 and implementation, the clock and calendar.
 
-A:ref:`Glossary of Terms <glossary_of_terms>` defines commonly used terms and
+A :ref:`Glossary of Terms <glossary_of_terms>` defines commonly used terms and
 is available from the right-hand side panel of each page.
 
 Finally, detailed API documentation is given for the LFRic infrastructure and

documentation/source/getting_started/index.rst

@@ -16,8 +16,8 @@ applications for training purposes or for developing and testing particular
 technical capabilities.
 
 It may be useful to look at the Glossary of Terms and the FAQs as you get
-started to familiarise yourself with various terms used in LFRic. There are 
-links to both the Glossary and FAQs on the start page and in the right-hand 
+started to familiarise yourself with various terms used in LFRic. There are
+links to both the Glossary and FAQs on the start page and in the right-hand
 navigation bar on all other pages.
 
 .. toctree::