CI: Add a new workflow to cache dvc cache (#4184)

Co-authored-by: Wei Ji <23487320+weiji14@users.noreply.github.com>

Author: seisman

.github/workflows/cache_dvc.yaml

@@ -0,0 +1,59 @@
+# Cache baseline images tracked by DVC and upload as artifacts.
+#
+# This workflow downloads dvc cache needed by PyGMT tests and uploads them as workflow
+# artifacts, which can then be accessed by other GitHub Actions workflows.
+#
+# This workflow serves as a workaround for the DagsHub authentication issue that
+# prevents PRs from forks to access the DVC remote.
+# Related issue: https://github.com/GenericMappingTools/pygmt/issues/4147
+#
+# It is scheduled to run every Sunday at 12:00 (UTC) and on the main branch if there are
+# any changes to the baseline images.
+#
+name: Cache DVC
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'pygmt/tests/baseline/*.png.dvc'
+  # pull_request:  # For testing only.
+  workflow_dispatch:
+  # Schedule runs on 12 noon every Sunday
+  schedule:
+    - cron: '0 12 * * 0'
+
+permissions: {}
+
+jobs:
+  dvc_cache:
+    name: Cache DVC baseline images
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5.0.0
+        with:
+          # fetch all history so that setuptools-scm works
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup data version control (DVC)
+        uses: iterative/setup-dvc@175771be1dc3d119268e00a896b52a4b77decb5e # v1.2.0
+
+      - name: Pull baseline image data from dvc remote
+        env:
+          DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
+        run: |
+          dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
+          dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
+
+      - name: Upload DVC cache as artifacts to GitHub
+        uses: actions/upload-artifact@v5.0.0
+        with:
+          name: dvc-cache
+          include-hidden-files: true
+          path: .dvc/cache/

.github/workflows/ci_tests.yaml

@@ -163,12 +163,22 @@ jobs:
 
       # Pull baseline image data from dvc remote (DAGsHub)
       - name: Pull baseline image data from dvc remote
+        id: dvc-pull
+        continue-on-error: true
         run: |
           uv run dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
           uv run dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
         env:
           DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
 
+      - name: Download DVC cache as artifacts from GitHub
+        if: steps.dvc-pull.outcome == 'failure'
+        run: |
+          gh run download --name dvc-cache --dir .dvc/cache/
+          uv run dvc checkout --verbose
+        env:
+          GH_TOKEN: ${{ github.token }}
+
       # Install the package that we want to test
       - name: Install the package
         run: make install

.github/workflows/ci_tests_dev.yaml

@@ -161,12 +161,22 @@ jobs:
 
       # Pull baseline image data from dvc remote (DAGsHub)
       - name: Pull baseline image data from dvc remote
+        id: dvc-pull
+        continue-on-error: true
         run: |
           dvc remote modify upstream url https://${DAGSHUB_TOKEN}@dagshub.com/GenericMappingTools/pygmt.dvc --local
           dvc pull --no-run-cache --verbose && ls -lhR pygmt/tests/baseline/
         env:
           DAGSHUB_TOKEN: ${{ secrets.DAGSHUB_TOKEN }}
 
+      - name: Download DVC cache as artifacts from GitHub
+        if: steps.dvc-pull.outcome == 'failure'
+        run: |
+          gh run download --name dvc-cache --dir .dvc/cache/
+          dvc checkout --verbose
+        env:
+          GH_TOKEN: ${{ github.token }}
+
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
         run: |

doc/maintenance.md

@@ -95,8 +95,9 @@ controlled by workflow files located in `.github/workflows`. Here we briefly
 summarize the functions of the workflows. Please refer to the comments in the
 workflow files for more details.
 
-- `benchmarks.yml`: Benchmarks the execution speed of tests to track performance of PyGMT functions
-- `cache_data.yaml`: Cache GMT remote data files and uplodas as artifacts
+- `benchmarks.yml`: Benchmark the execution speed of tests to track performance of PyGMT functions
+- `cache_data.yaml`: Cache GMT remote data files and upload as artifacts
+- `cache_dvc.yaml`: Cache baseline images tracked by DVC and upload as artifacts
 - `check-links.yml`: Check links in the repository and documentation
 - `ci_docs.yml`: Build documentation on Linux/macOS/Windows and deploy to GitHub
 - `ci_doctest.yaml`: Run all doctests on Linux/macOS/Windows