Stop CI from clobbering commits on lockfile updates

.github/workflows/refresh-lockfiles.yml

@@ -14,20 +14,58 @@ name: Refresh Lockfiles
 
 on:
   workflow_dispatch:
+    inputs:
+      clobber:
+        description: |
+          Force the workflow to run, potentially clobbering any commits already made to the branch. 
+          Enter "yes" or "true" to run.
+        default: "no"
   schedule:
     # Run once a week on a Saturday night 
     - cron: 1 0 * * 6
 
 
 jobs:
 
+  no_clobber:
+    runs-on: ubuntu-latest
+    steps:
+      # check if the auto-update-lockfiles branch exists.  If it does, and someone other than
+      # the lockfile bot has made the head commit, abort the workflow.
+      # This job can be manually overridden by running directly from the github actions panel
+      # (known as a "workflow_dispatch") and setting the `clobber` input to "yes".
+      - uses: actions/script@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            if (context.eventName == "workflow_dispatch") {
+              const clobber = context.payload.inputs.clobber || "no";
+              if (["yes", "true", "y"].includes(clobber.trim().toLowerCase())) {
+                core.info("Manual override, continuing workflow, potentially overwriting previous commits to auto-update-lockfiles");
+                return
+              }
+            }
+            github.repos.getBranch({...context.repo, branch: "auto-update-lockfiles"}).then(res => {
+              const committer = res.data.commit.commit.committer;
+              if (committer && committer.name === "Lockfile bot") {
+                core.info("Lockfile bot was the last to push to auto-update-lockfiles. Continue.");
+              } else {
+                core.setFailed("New commits to auto-update-lockfiles since bot last ran. Abort!");
+              }
+            }).catch(err => {
+              if (err.status === 404) {
+                  core.info("auto-update-lockfiles branch not found, continue");
+              }
+            })
+
   gen_lockfiles:
     # this is a matrix job: it splits to create new lockfiles for each
     # of the CI test python versions.
     # this list below should be changed when covering more python versions
     # TODO: generate this matrix automatically from the list of available py**.yml files
     #       ref: https://tomasvotruba.com/blog/2020/11/16/how-to-make-dynamic-matrix-in-github-actions/
     runs-on: ubuntu-latest
+    needs: no_clobber
 
     strategy:
       matrix:
@@ -62,14 +100,16 @@ jobs:
           path: artifacts
 
       - name: Update lock files in repo
-        run: | 
+        run: |
           cp artifacts/artifact/*.lock requirements/ci/nox.lock
           rm -r artifacts
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@052fc72b4198ba9fbc81b818c6e1859f747d49a8
         with:
           commit-message: Updated environment lockfiles
+          committer: "Lockfile bot <[email protected]>"
+          author: "Lockfile bot <[email protected]>"
           delete-branch: true
           branch: auto-update-lockfiles
           title: Update CI environment lockfiles

docs/src/developers_guide/contributing_ci_tests.rst

@@ -66,6 +66,16 @@ and add the changed lockfiles to your pull request.
 
 New lockfiles are generated automatically each week to ensure that Iris continues to be
 tested against the latest available version of its dependencies.
+Each week the yaml files in ``requirements/ci`` are resolved by a GitHub Action.
+If the resolved environment has changed, a pull request is created with the new lock files.
+The CI test suite will run on this pull request and fixes for failed tests can be pushed to
+the ``auto-update-lockfiles`` branch to be included in the PR. 
+Once a developer has pushed to this branch, the auto-update process will not run again until
+the PR is merged, to prevent overwriting developer commits.
+The auto-updater can still be invoked manually in this situation by going to the `GitHub Actions`_
+page for the workflow, and manually running using the "Run Workflow" button.  
+By default, this will also not override developer commits.  To force an update, you must 
+confirm "yes" in the "Run Worflow" prompt.
 
 
 .. _skipping Cirrus-CI tasks:
@@ -137,3 +147,4 @@ See the `pre-commit.ci dashboard`_ for details of recent past and active Iris jo
 .. _Cirrus-CI Documentation: https://cirrus-ci.org/guide/writing-tasks/
 .. _.pre-commit-config.yaml: https://github.com/SciTools/iris/blob/master/.pre-commit-config.yaml
 .. _pre-commit.ci dashboard: https://results.pre-commit.ci/repo/github/5312648
+.. _GitHub Actions: https://github.com/SciTools/iris/actions/workflows/refresh-lockfiles.yml