docs: mention public build cache for GHA (#40908)

1 files changed, 47 insertions, 23 deletions

diff --git a/lib/spack/docs/binary_caches.rst b/lib/spack/docs/binary_caches.rst
index 5f11dd6bd6..00194fc96e 100644
--- a/lib/spack/docs/binary_caches.rst
+++ b/lib/spack/docs/binary_caches.rst
@@ -216,29 +216,34 @@ other system dependencies. However, they are still compatible with tools like
     are `alternative drivers <https://docs.docker.com/storage/storagedriver/>`_.
 
 ------------------------------------
-Using a buildcache in GitHub Actions
+Spack build cache for GitHub Actions
 ------------------------------------
 
-GitHub Actions is a popular CI/CD platform for building and testing software,
-but each CI job has limited resources, making from source builds too slow for
-many applications. Spack build caches can be used to share binaries between CI
-runs, speeding up CI significantly.
+To significantly speed up Spack in GitHub Actions, binaries can be cached in
+GitHub Packages. This service is an OCI registry that can be linked to a GitHub
+repository.
 
 A typical workflow is to include a ``spack.yaml`` environment in your repository
-that specifies the packages to install:
+that specifies the packages to install, the target architecture, and the build
+cache to use under ``mirrors``:
 
 .. code-block:: yaml
 
     spack:
-      specs: [pkg-x, pkg-y]
-    packages:
-      all:
-        require: target=x86_64_v2
-    mirrors:
-      github_packages: oci://ghcr.io/<user>/<repo>
-
-And a GitHub action that sets up Spack, installs packages from the build cache
-or from sources, and pushes newly built binaries to the build cache:
+      specs:
+      - python@3.11
+      config:
+        install_tree:
+          root: /opt/spack
+          padded_length: 128
+      packages:
+        all:
+          require: target=x86_64_v2
+      mirrors:
+        local-buildcache: oci://ghcr.io/<organization>/<repository>
+
+A GitHub action can then be used to install the packages and push them to the
+build cache:
 
 .. code-block:: yaml
 
@@ -252,26 +257,35 @@ or from sources, and pushes newly built binaries to the build cache:
     jobs:
       example:
         runs-on: ubuntu-22.04
+        permissions:
+          packages: write
         steps:
         - name: Checkout
           uses: actions/checkout@v3
 
-        - name: Install Spack
-          run: |
-            git clone --depth=1 https://github.com/spack/spack.git
-            echo "$PWD/spack/bin/" >> "$GITHUB_PATH"
+        - name: Checkout Spack
+          uses: actions/checkout@v3
+          with:
+            repository: spack/spack
+            path: spack
+
+        - name: Setup Spack
+          run: echo "$PWD/spack/bin" >> "$GITHUB_PATH"
 
         - name: Concretize
           run: spack -e . concretize
 
         - name: Install
-          run: spack -e . install --no-check-signature --fail-fast
+          run: spack -e . install --no-check-signature
+
+        - name: Run tests
+            run: ./my_view/bin/python3 -c 'print("hello world")'
 
         - name: Push to buildcache
           run: |
-            spack -e . mirror set --oci-username <user> --oci-password "${{ secrets.GITHUB_TOKEN }}" github_packages
-            spack -e . buildcache push --base-image ubuntu:22.04 --unsigned --update-index github_packages
-            if: always()
+            spack -e . mirror set --oci-username ${{ github.actor }} --oci-password "${{ secrets.GITHUB_TOKEN }}" local-buildcache
+            spack -e . buildcache push --base-image ubuntu:22.04 --unsigned --update-index local-buildcache
+          if: ${{ !cancelled() }}
 
 The first time this action runs, it will build the packages from source and
 push them to the build cache. Subsequent runs will pull the binaries from the
@@ -281,6 +295,16 @@ over source builds.
 The build cache entries appear in the GitHub Packages section of your repository,
 and contain instructions for pulling and running them with ``docker`` or ``podman``.
 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using Spack's public build cache for GitHub Actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Spack offers a public build cache for GitHub Actions with a set of common packages,
+which lets you get started quickly. See the following resources for more information:
+
+* `spack/github-actions-buildcache <https://github.com/spack/github-actions-buildcache>`_
+
 ----------
 Relocation
 ----------