Examples

Google Cloud Storage Cache

Google Cloud Storage Cache

Using Google Cloud Storage (GCS) as a cache backend provides several advantages:

Larger storage: Store caches beyond GitHub's 10GB repository limit
Cross-repository access: Share caches between different repositories
Custom retention: Control cache lifecycle with GCS retention policies
Fallback mechanism: Automatically falls back to GitHub cache if GCS is unavailable

The following examples show how to configure GCS caching in your workflows.

Basic Example

name: Build with GCS Cache

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    
    permissions:
      contents: 'read'
      id-token: 'write' # Required for GCP workload identity federation

    steps:
    - uses: actions/checkout@v4

    # Set up Google Cloud authentication
    - id: auth
      uses: google-github-actions/auth@v2
      with:
        # Using Service Account Key JSON
        credentials_json: ${{ secrets.GCP_CREDENTIALS }}
        
        # Alternatively, use Workload Identity Federation (more secure)
        # workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
        # service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

    - name: Cache Dependencies
      id: cache-deps
      uses: danySam/gcs-cache@v1
      with:
        path: |
          ~/.npm
          node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-node-
        gcs-bucket: my-github-cache-bucket

    - name: Install Dependencies
      if: steps.cache-deps.outputs.cache-hit != 'true'
      run: npm ci

    - name: Build
      run: npm run build

Separate Restore/Save Actions

For more flexible control, you can use the restore and save actions separately:

name: Build with GCS Cache (Separate Restore/Save)

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    
    permissions:
      contents: 'read'
      id-token: 'write' # Required for GCP workload identity federation

    steps:
    - uses: actions/checkout@v4

    # Set up Google Cloud authentication
    - id: auth
      uses: google-github-actions/auth@v2
      with:
        credentials_json: ${{ secrets.GCP_CREDENTIALS }}
        # Or use workload identity federation

    - name: Restore Dependencies from Cache
      id: cache-deps-restore
      uses: danySam/gcs-cache/restore@v1
      with:
        path: |
          ~/.npm
          node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-node-
        gcs-bucket: my-github-cache-bucket

    - name: Install Dependencies
      if: steps.cache-deps-restore.outputs.cache-hit != 'true'
      run: npm ci

    - name: Build
      run: npm run build

    - name: Save Dependencies to Cache
      id: cache-deps-save
      uses: danySam/gcs-cache/save@v1
      with:
        path: |
          ~/.npm
          node_modules
        key: ${{ steps.cache-deps-restore.outputs.cache-primary-key }}
        gcs-bucket: my-github-cache-bucket

Advanced GCS Cache Examples

Cross-Repository Caching

Share caches across multiple repositories using the same GCS bucket:

name: Build with Shared GCS Cache

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    
    permissions:
      contents: 'read'
      id-token: 'write' 

    steps:
    - uses: actions/checkout@v4

    # Set up Google Cloud authentication
    - uses: google-github-actions/auth@v2
      with:
        credentials_json: ${{ secrets.GCP_CREDENTIALS }}

    - name: Shared Cross-Repo Cache
      id: shared-cache
      uses: danySam/gcs-cache@v1
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
        key: shared-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
        restore-keys: |
          shared-gradle-
        gcs-bucket: shared-company-cache-bucket
        gcs-path-prefix: gradle-cache  # Optional: organize caches in the bucket

    # Rest of your workflow

Using Workload Identity Federation (Recommended for Production)

For production environments, Google recommends Workload Identity Federation over service account keys for more secure authentication. This approach eliminates the need to manage long-lived service account keys:

name: Build with GCS Cache using Workload Identity

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    
    permissions:
      contents: 'read'
      id-token: 'write' # Required for Workload Identity Federation

    steps:
    - uses: actions/checkout@v4

    # Set up Google Cloud authentication with Workload Identity Federation
    - id: auth
      uses: google-github-actions/auth@v2
      with:
        # The workload identity provider resource name
        workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
        # The service account email address
        service_account: my-service-account@my-project.iam.gserviceaccount.com
        # Optional: Create credentials file for Google Cloud SDK
        create_credentials_file: true
        # Optional: Cleanup credentials after job completion
        cleanup_credentials: true

    - name: Cache Dependencies
      id: cache-deps
      uses: danySam/gcs-cache@v1
      with:
        path: path/to/dependencies
        key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
        gcs-bucket: my-github-cache-bucket

For detailed setup instructions, see the Google GitHub Actions Auth documentation. The basic steps include:

Create a Workload Identity Pool and Provider in Google Cloud
Configure IAM permissions for your service account
Store configuration values in GitHub Secrets
Add the auth action to your workflow with proper permissions

Using Workload Identity Federation provides enhanced security since:

No long-lived credentials need to be stored as GitHub Secrets
Access is temporary and scoped to just the running workflow
All access is fully auditable in Google Cloud logs

6.5 KiB Raw Blame History