From 0ab9153184b3956f83ab176459aca10b76743fdc Mon Sep 17 00:00:00 2001 From: Julien Carsique Date: Tue, 24 Mar 2026 19:03:15 +0100 Subject: [PATCH] BUILD-10724 migrate only when S3 is forced --- README.md | 46 ++++++++++++++++++++++++++-------------------- action.yml | 14 +++++++++++--- 2 files changed, 37 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index db10dd1..47bada3 100644 --- a/README.md +++ b/README.md @@ -69,20 +69,20 @@ These must be committed since GitHub Actions runs them directly. ## Inputs -| Input | Description | Required | Default | -|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| -| `path` | Files, directories, and wildcard patterns to cache | Yes | | -| `key` | Explicit key for restoring and saving cache | Yes | | -| `restore-keys` | Ordered list of prefix-matched keys for fallback | No | | -| `fallback-to-default-branch` | Automatically add a fallback restore key pointing to the default branch cache (S3 backend only). Disable if you want strict branch isolation. | No | `false` | -| `fallback-branch` | Optional maintenance branch for fallback restore keys (pattern: `branch-*`, S3 backend only). If not set, the repository default branch is used. | No | | -| `environment` | Environment to use (dev or prod, S3 backend only) | No | `prod` | -| `upload-chunk-size` | Chunk size for large file uploads (bytes) | No | | -| `enableCrossOsArchive` | Enable cross-OS cache compatibility | No | `false` | -| `fail-on-cache-miss` | Fail workflow if cache entry not found | No | `false` | -| `lookup-only` | Only check cache existence without downloading | No | `false` | -| `backend` | Force specific backend: `github` or `s3`. Takes priority over `CACHE_BACKEND` env var and auto-detection. | No | | -| `import-github-cache` | Import GitHub cache to S3 when no S3 cache exists (migration mode, S3 backend only). Takes priority over `CACHE_IMPORT_GITHUB` env var. | No | `true` | +| Input | Description | Required | Default | +|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------| +| `path` | Files, directories, and wildcard patterns to cache | Yes | | +| `key` | Explicit key for restoring and saving cache | Yes | | +| `restore-keys` | Ordered list of prefix-matched keys for fallback | No | | +| `fallback-to-default-branch` | Automatically add a fallback restore key pointing to the default branch cache (S3 backend only). Disable if you want strict branch isolation. | No | `false` | +| `fallback-branch` | Optional maintenance branch for fallback restore keys (pattern: `branch-*`, S3 backend only). If not set, the repository default branch is used. | No | | +| `environment` | Environment to use (dev or prod, S3 backend only) | No | `prod` | +| `upload-chunk-size` | Chunk size for large file uploads (bytes) | No | | +| `enableCrossOsArchive` | Enable cross-OS cache compatibility | No | `false` | +| `fail-on-cache-miss` | Fail workflow if cache entry not found | No | `false` | +| `lookup-only` | Only check cache existence without downloading | No | `false` | +| `backend` | Force specific backend: `github` or `s3`. Takes priority over `CACHE_BACKEND` env var and auto-detection. | No | | +| `import-github-cache` | Import GitHub cache to S3 when no S3 cache exists (migration mode, S3 backend only). Takes priority over `CACHE_IMPORT_GITHUB` env var. | No | `true` when backend is explicitly forced to `s3`, `false` when auto-detected | ## Backend Selection @@ -107,22 +107,28 @@ Migration mode bridges this gap: when using the S3 backend and no S3 cache exist from GitHub Actions cache using the original key. The S3 post-job step then saves the restored content to S3, pre-provisioning it for subsequent runs. -Migration mode is **enabled by default** for S3 backend. Once all relevant entries have been migrated to S3, disable it to avoid -the overhead of the GitHub fallback attempt on every cache miss. +Migration mode is **enabled by default when the S3 backend is explicitly forced** (`backend: s3` input or `CACHE_BACKEND=s3` env var), +which is the typical migration scenario. It is disabled by default when the S3 backend is auto-detected (private/internal repository), +since those repositories have always used S3 and have no GitHub cache entries to migrate. -**Disable resolution order** (first match wins): +Once all relevant entries have been migrated to S3, disable it to avoid the overhead of the GitHub fallback attempt on every cache miss. + +**Resolution order** (first match wins): 1. **`import-github-cache: 'false'`** — action input in the step 2. **`CACHE_IMPORT_GITHUB=false`** — environment variable at job or workflow level (can be sourced from a repository variable) -3. Default: `true` +3. **`true`** if backend was explicitly forced to `s3` (migration scenario) +4. **`false`** if backend was auto-detected (no prior GitHub cache) **Disabling via repository variable** (recommended for gradual rollout): ```yaml +env: + CACHE_BACKEND: s3 # forces S3 for all cache steps, including those in reusable actions + CACHE_IMPORT_GITHUB: ${{ vars.CACHE_IMPORT_GITHUB }} # source from repository variable for easy toggle without workflow changes + jobs: build: - env: - CACHE_IMPORT_GITHUB: ${{ vars.CACHE_IMPORT_GITHUB }} steps: - uses: SonarSource/gh-action_cache@v1 ``` diff --git a/action.yml b/action.yml index a75ac5c..dbab774 100644 --- a/action.yml +++ b/action.yml @@ -61,10 +61,13 @@ runs: REPO_VISIBILITY: ${{ github.event.repository.visibility }} FORCED_BACKEND: ${{ inputs.backend }} run: | + BACKEND_SOURCE="auto" if [[ "$FORCED_BACKEND" == "github" || "$FORCED_BACKEND" == "s3" ]]; then CACHE_BACKEND="$FORCED_BACKEND" + BACKEND_SOURCE="forced" echo "Using forced backend from input: $CACHE_BACKEND" elif [[ "$CACHE_BACKEND" == "github" || "$CACHE_BACKEND" == "s3" ]]; then + BACKEND_SOURCE="forced" echo "Using backend from CACHE_BACKEND environment variable: $CACHE_BACKEND" else # If visibility is not available in the event, try to get it from the API @@ -85,6 +88,7 @@ runs: fi echo "cache-backend=$CACHE_BACKEND" >> "$GITHUB_OUTPUT" + echo "backend-source=$BACKEND_SOURCE" >> "$GITHUB_OUTPUT" - name: Cache with GitHub Actions (public repos) if: steps.cache-backend.outputs.cache-backend == 'github' @@ -132,17 +136,21 @@ runs: shell: bash env: INPUT_IMPORT_GITHUB_CACHE: ${{ inputs.import-github-cache }} + BACKEND_SOURCE: ${{ steps.cache-backend.outputs.backend-source }} run: | - # Resolution order: input → CACHE_IMPORT_GITHUB env var → default true + # Resolution order: input → CACHE_IMPORT_GITHUB env var → true if backend was explicitly forced (migration scenario) → false if [[ -n "$INPUT_IMPORT_GITHUB_CACHE" ]]; then IMPORT_GITHUB="$INPUT_IMPORT_GITHUB_CACHE" echo "Using import mode from input: $IMPORT_GITHUB" elif [[ -n "${CACHE_IMPORT_GITHUB:-}" ]]; then IMPORT_GITHUB="$CACHE_IMPORT_GITHUB" echo "Using import mode from CACHE_IMPORT_GITHUB environment variable: $IMPORT_GITHUB" - else + elif [[ "$BACKEND_SOURCE" == "forced" ]]; then IMPORT_GITHUB="true" - echo "Using default import mode: $IMPORT_GITHUB" + echo "Using default import mode (backend explicitly forced to S3 — migration scenario): $IMPORT_GITHUB" + else + IMPORT_GITHUB="false" + echo "Using default import mode (backend auto-detected — no prior GitHub cache): $IMPORT_GITHUB" fi echo "import-github=$IMPORT_GITHUB" >> "$GITHUB_OUTPUT"