action.yml

name: S3 Cache action
description: Cache files on S3 with branch-specific paths for granular permissions
author: SonarSource

inputs:
  path:
    description: A list of files, directories, and wildcard patterns to cache and restore
    required: true
  key:
    description: An explicit key for restoring and saving the cache
    required: true
  restore-keys:
    description: An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key
  upload-chunk-size:
    description: The chunk size used to split up large files during upload, in bytes
  enableCrossOsArchive:
    description: When enabled, allows to save or restore caches that can be restored or saved respectively on other platforms
    default: false
  fail-on-cache-miss:
    description: Fail the workflow if cache entry is not found
    default: false
  lookup-only:
    description: Check if a cache entry exists for the given input(s) (key, restore-keys) without downloading the cache
    default: false
  environment:
    description: Environment to use ('dev' or 'prod', 's3' backend only).
    default: prod
  fallback-branch:
    description: >
      Explicit fallback branch for restore keys (pattern 'branch-*', 's3' backend only).
      Always honoured when set, regardless of 'fallback-to-default-branch'.
      If not set, the repository default branch is used when 'fallback-to-default-branch' is true.
  fallback-to-default-branch:
    description: >
      When enabled, automatically adds a fallback restore key pointing to the default branch cache.
      Only applies to the S3 backend.
    default: 'true'
  backend:
    description: >
      Force cache backend ('github' or 's3'). If not set, falls back to the CACHE_BACKEND environment variable if defined,
      then automatically determined based on repository visibility.

outputs:
  cache-hit:
    description: A boolean value to indicate an exact match was found for the primary key
    value: ${{ steps.github-cache.outputs.cache-hit || steps.s3-cache.outputs.cache-hit }}

runs:
  using: composite
  steps:
    - name: Determine cache backend
      id: cache-backend
      shell: bash
      env:
        GITHUB_TOKEN: ${{ github.token }}
        REPO_VISIBILITY: ${{ github.event.repository.visibility }}
        FORCED_BACKEND: ${{ inputs.backend }}
      run: |
        if [[ "$FORCED_BACKEND" == "github" || "$FORCED_BACKEND" == "s3" ]]; then
          CACHE_BACKEND="$FORCED_BACKEND"
          echo "Using forced backend from input: $CACHE_BACKEND"
        elif [[ "$CACHE_BACKEND" == "github" || "$CACHE_BACKEND" == "s3" ]]; then
          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
          if [[ -z "$REPO_VISIBILITY" || "$REPO_VISIBILITY" = "null" ]]; then
            REPO_VISIBILITY=$(curl -s -H "Authorization: token ${{ github.token }}" \
              "https://api.github.com/repos/${{ github.repository }}" | \
              jq -r '.visibility // "private"')
          fi
          echo "Repository visibility: $REPO_VISIBILITY"

          if [[ "$REPO_VISIBILITY" == "public" ]]; then
            CACHE_BACKEND="github"
            echo "Using GitHub cache for public repository"
          else
            CACHE_BACKEND="s3"
            echo "Using S3 cache for private/internal repository"
          fi
        fi

        echo "cache-backend=$CACHE_BACKEND" >> "$GITHUB_OUTPUT"

    - name: Cache with GitHub Actions (public repos)
      if: steps.cache-backend.outputs.cache-backend == 'github'
      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
      id: github-cache
      with:
        path: ${{ inputs.path }}
        key: ${{ inputs.key }}
        restore-keys: ${{ inputs.restore-keys }}
        upload-chunk-size: ${{ inputs.upload-chunk-size }}
        enableCrossOsArchive: ${{ inputs.enableCrossOsArchive }}
        fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
        lookup-only: ${{ inputs.lookup-only }}

    - name: Set action path for scripts
      if: steps.cache-backend.outputs.cache-backend == 's3'
      shell: bash
      run: |
        ACTION_PATH_CACHE="${{ github.action_path }}"
        echo "ACTION_PATH_CACHE=$ACTION_PATH_CACHE" >> "$GITHUB_ENV"

    - name: Setup S3 cache credentials
      if: steps.cache-backend.outputs.cache-backend == 's3'
      id: aws-auth
      uses: SonarSource/gh-action_cache/credential-setup@v1
      with:
        environment: ${{ inputs.environment }}

    - name: Prepare cache keys
      if: steps.cache-backend.outputs.cache-backend == 's3'
      shell: bash
      id: prepare-keys
      env:
        INPUT_KEY: ${{ inputs.key }}
        INPUT_RESTORE_KEYS: ${{ inputs.restore-keys }}
        INPUT_FALLBACK_BRANCH: ${{ inputs.fallback-branch }}
        INPUT_FALLBACK_TO_DEFAULT_BRANCH: ${{ inputs.fallback-to-default-branch }}
        GITHUB_TOKEN: ${{ github.token }}
        GITHUB_REPOSITORY: ${{ github.repository }}
      run: $ACTION_PATH_CACHE/scripts/prepare-keys.sh

    - name: Cache on S3
      if: steps.cache-backend.outputs.cache-backend == 's3'
      uses: runs-on/cache@50350ad4242587b6c8c2baa2e740b1bc11285ff4 # v4.3.0
      id: s3-cache
      env:
        RUNS_ON_S3_BUCKET_CACHE: sonarsource-s3-cache-${{ inputs.environment }}-bucket
        AWS_DEFAULT_REGION: eu-central-1
        AWS_REGION: eu-central-1
        # Step-level env: overrides GITHUB_ENV values for this step
        AWS_ACCESS_KEY_ID: ${{ steps.aws-auth.outputs.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ steps.aws-auth.outputs.AWS_SECRET_ACCESS_KEY }}
        AWS_SESSION_TOKEN: ${{ steps.aws-auth.outputs.AWS_SESSION_TOKEN }}
        # Clear profile so SDK uses env credentials, not ~/.aws/credentials
        AWS_PROFILE: ''
        AWS_DEFAULT_PROFILE: ''
      with:
        path: ${{ inputs.path }}
        key: ${{ steps.prepare-keys.outputs.branch-key }}
        restore-keys: ${{ steps.prepare-keys.outputs.branch-restore-keys }}
        upload-chunk-size: ${{ inputs.upload-chunk-size }}
        enableCrossOsArchive: ${{ inputs.enableCrossOsArchive }}
        fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
        lookup-only: ${{ inputs.lookup-only }}

    - name: Credential guard for S3 cache save
      if: steps.cache-backend.outputs.cache-backend == 's3'
      uses: SonarSource/gh-action_cache/credential-guard@v1
      with:
        credentials-file: ${{ steps.aws-auth.outputs.credentials-file }}

branding:
  icon: upload-cloud
  color: blue