feat(ci performance) speculative: add registry cache variable everywhere to gha

.github/workflows/README.md

@@ -2,6 +2,21 @@
 
 Documentation for this repo GitHub actions configuration
 
+## Earthly remote cache (GHCR)
+
+CI workflows that execute `earthly` set `EARTHLY_REMOTE_CACHE` from the repository Actions variable `REMOTE_CACHE_REGISTRY`.
+
+Set `REMOTE_CACHE_REGISTRY` to a full GHCR image ref used only for cache, for example:
+
+`ghcr.io/earthly/cache/buildkit/earthly:ci`
+
+Permissions required for workflows that write cache:
+
+- `packages: write` to push/update cache layers
+- `packages: read` to pull existing cache layers
+
+For pull requests from forks (where secrets/tokens may be restricted), cache export may fail due to permissions. Cache import from public refs can still work.
+
 ## Skipping PR Workflows (DISABLED! SEE NOTE BELOW)
 
 The following is disabled due to issue https://github.com/orgs/community/discussions/13261.

.github/workflows/build-earthly.yml

@@ -35,6 +35,7 @@ jobs:
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       # Use fixed buildkitd image with Docker 29+ ulimit fix until next release

.github/workflows/ci-docker-ubuntu.yml

@@ -16,6 +16,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   # this job will output a boolean value to check whether files that require these tests to run
   # since all jobs depend on `build-earthly` job, conditionally running it will either cause all jobs to run or skip,

.github/workflows/ci-earthly-next-docker-ubuntu.yml

@@ -16,6 +16,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   build-earthly-with-next:
     permissions: write-all

.github/workflows/ci-lint-changelog.yml

@@ -13,9 +13,13 @@ jobs:
   test:
     name: +lint-changelog
     runs-on: ubuntu-24.04-arm
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/ci-podman-ubuntu.yml

@@ -16,6 +16,10 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+  packages: write
+
 jobs:
   # this job will output a boolean value to check whether files that require these tests to run
   # since all jobs depend on `build-earthly` job, conditionally running it will either cause all jobs to run or skip,

.github/workflows/ci-scheduled-podman-mac.yml

@@ -8,9 +8,13 @@ jobs:
   podman-macos-test:
     name: +testing-gha-podman
     runs-on: macos-15 # GitHub Actions the latest tag still uses macos-11, which does not have brew installed by default
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       BUILT_EARTHLY_PATH: build/darwin/amd64/earthly
 
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/ci-security.yml

@@ -6,12 +6,16 @@ on:
       - '**/go.mod'
       - '**/go.sum'
 
+env:
+  EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
+
 jobs:
   govulncheck:
     name: Go Vulnerabilities Report
     runs-on: ubuntu-24.04-arm
     permissions:
       contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
     steps:

.github/workflows/ci-staging-deploy.yml

@@ -12,6 +12,9 @@ on:
       - '.github/CODEOWNERS'
       - 'LICENSE'
 
+env:
+  EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
+
 jobs:
   build-earthly:
     permissions: write-all
@@ -199,7 +202,7 @@ jobs:
     needs: [build-earthly, prepare-release, release-image]
     runs-on: ubuntu-24.04
     permissions:
-      packages: read
+      packages: write
     env:
       FORCE_COLOR: 1
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -233,6 +236,7 @@ jobs:
     runs-on: ubuntu-24.04
     permissions:
       contents: write
+      packages: write
     env:
       FORCE_COLOR: 1
       GITHUB_USER: "earthbuild"

.github/workflows/docs-checks-links.yml

@@ -13,9 +13,13 @@ concurrency:
 jobs:
   check-broken-links:
     runs-on: "ubuntu-latest"
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/on-tag-release.yml

@@ -4,12 +4,16 @@ on:
     release:
         types: [published]
 
+env:
+    EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
+
 jobs:
     add-artifacts-to-release:
         runs-on: ubuntu-24.04-arm
         permissions:
             contents: write
             actions: read
+            packages: write
         env:
             FORCE_COLOR: 1
         steps:
@@ -30,7 +34,7 @@ jobs:
         runs-on: ubuntu-24.04-arm
         permissions:
             contents: read
-            packages: read
+            packages: write
         env:
             FORCE_COLOR: 1
         steps:

.github/workflows/release-merge-docs.yml

@@ -13,9 +13,13 @@ jobs:
   main-to-docs:
     name: merge main to docs-0.8
     runs-on: "ubuntu-latest"
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/reusable-bootstrap-integrations.yml

@@ -25,12 +25,16 @@ jobs:
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
         with:

.github/workflows/reusable-docker-build-integrations.yml

@@ -27,10 +27,14 @@ jobs:
   docker-build-integration:
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_ORG: "${{inputs.EARTHLY_ORG}}"
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/reusable-earthbuild-image-tests.yml

@@ -32,9 +32,13 @@ jobs:
   earthbuild-image-tests:
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:

.github/workflows/reusable-example.yml

@@ -41,9 +41,13 @@ jobs:
     name: ${{inputs.EXAMPLE_NAME}}-${{inputs.RUNS_ON}}-${{inputs.BINARY}}
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       EARTHLY_ORG: "${{inputs.EARTHLY_ORG}}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"

.github/workflows/reusable-export-test.yml

@@ -25,9 +25,13 @@ jobs:
     name: Export tests
     runs-on: ${{inputs.RUNS_ON}}
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:

.github/workflows/reusable-git-metadata-test.yml

@@ -29,9 +29,13 @@ jobs:
     name: +testing-gha-${{inputs.RUNS_ON}}-${{inputs.BINARY}}
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       EARTHLY_ORG: "${{inputs.EARTHLY_ORG}}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"

.github/workflows/reusable-misc-tests-1.yml

@@ -32,9 +32,13 @@ jobs:
   misc-tests-1:
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:

.github/workflows/reusable-misc-tests-2.yml

@@ -34,10 +34,11 @@ jobs:
     runs-on: ${{inputs.RUNS_ON}}
     permissions:
       contents: read
-      packages: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:

.github/workflows/reusable-push-integrations.yml

@@ -31,9 +31,13 @@ jobs:
   push-integrations:
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:

.github/workflows/reusable-race-test.yml

@@ -41,9 +41,13 @@ jobs:
     name: ${{inputs.TEST_TARGET}} (-race)
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2

.github/workflows/reusable-repo-auth-tests.yml

@@ -32,9 +32,13 @@ jobs:
     name: repo auth tests
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       SSH_PORT: "2222"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/reusable-secrets-integrations.yml

@@ -31,10 +31,14 @@ jobs:
   secret-integration:
     if: ${{ !inputs.SKIP_JOB && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) }}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_TOKEN: "${{ secrets.EARTHLY_TOKEN }}"
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"
       # Used in our github action as the token - TODO: look to change it into an input

.github/workflows/reusable-test-local.yml

@@ -36,9 +36,13 @@ jobs:
     name: test-local ${{inputs.BINARY}}
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       EARTHLY_ORG: "${{inputs.EARTHLY_ORG}}"
       DOCKERHUB_MIRROR_USERNAME: "${{ secrets.DOCKERHUB_MIRROR_USERNAME }}"
       DOCKERHUB_MIRROR_PASSWORD: "${{ secrets.DOCKERHUB_MIRROR_PASSWORD }}"

.github/workflows/reusable-test.yml

@@ -41,9 +41,13 @@ jobs:
     name: +testing-gha-${{inputs.RUNS_ON}}-${{inputs.BINARY}}
     if: ${{!inputs.SKIP_JOB}}
     runs-on: ${{inputs.RUNS_ON}}
+    permissions:
+      contents: read
+      packages: write
     env:
       FORCE_COLOR: 1
       EARTHLY_INSTALL_ID: "earthly-githubactions"
+      EARTHLY_REMOTE_CACHE: "earthly-ghcr-cache,image-manifest=true,oci-mediatypes=true,ref=${{ vars.REMOTE_CACHE_REGISTRY }}"
       EARTHLY_ORG: "${{inputs.EARTHLY_ORG}}"
       # Used in our github action as the token - TODO: look to change it into an input
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}