Skip to content

BUILD-10724 migrate only when S3 is forced #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julien-carsique-sonarsource merged 1 commit into from
Mar 25, 2026
Merged

BUILD-10724 migrate only when S3 is forced #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 26 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
```
Expand Down
14 changes: 11 additions & 3 deletions action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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'
Expand Down Expand Up @@ -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"

Expand Down
Loading