auth/docs/EXAMPLES.md

Examples for Authenticating to Google Cloud from GitHub Actions

Consider using the Markdown TOC to make browsing these samples easier.

These examples assume you have completed all corresponding Setup Instructions.

Direct Workload Identity Federation

This example shows authenticating directly with Workload Identity Federation. Google Cloud Resources must have the Workload Identity Pool as a principalSet as an IAM permission.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    - id: 'auth'
      uses: 'google-github-actions/auth@v3'
      with:
        project_id: 'my-project'
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'

    # Use 'steps.auth.outputs.auth_token' in subsequent steps as a bearer token.
    #
    # - run: |-
    #   curl -H 'Bearer: ${{ steps.auth.outputs.auth_token }}' https://...
    #

Workload Identity Federation through a Service Account

This example shows authenticating to Google Cloud by proxying through a Service Account. Future authentication calls will be made with the Service Account's OAuth 2.0 Access token.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    - uses: 'google-github-actions/auth@v3'
      with:
        project_id: 'my-project'
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    # NOTE: 'steps.auth.outputs.auth_token' will be a federated authentication
    # token, it does not correspond to the service account. To get a token for
    # the service account, specify the 'token_format' parameter and use the
    # 'accesss_token' output.
    #
    # - uses: 'google-github-actions/auth@v3'
    #   with:
    #     workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
    #     service_account: 'my-service-account@my-project.iam.gserviceaccount.com'
    #     token_format: 'access_token'
    #
    # - run: |-
    #   curl -H 'Bearer: ${{ steps.auth.outputs.access_token }}' https://...
    #

Service Account Key JSON

This example demonstrates authenticating via a Google Cloud Service Account Key JSON. After you export a Google Cloud Service Account Key, insert the value into a GitHub Secret named 'GOOGLE_CREDENTIALS'.

jobs:
  job_id:
    steps:
    - uses: 'actions/checkout@v7'

    - uses: 'google-github-actions/auth@v3'
      with:
        credentials_json: '${{ secrets.GOOGLE_CREDENTIALS }}'

Configuring gcloud

This example demonstrates using this GitHub Action to configure authentication for the gcloud CLI tool.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v7'

    - id: 'auth'
      uses: 'google-github-actions/auth@v3'
      with:
        project_id: 'my-project'
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'

    - name: 'Set up Cloud SDK'
      uses: 'google-github-actions/setup-gcloud@v2'

Generating an OAuth 2.0 Access Token

This example demonstrates using this GitHub Action to generate an OAuth 2.0 Access Token for authenticating to Google Cloud.

Note

The default lifetime is 1 hour, but you can request up to 12 hours if you set the constraints/iam.allowServiceAccountCredentialLifetimeExtension organization policy.

Important

If you authenticate via credentials_json, the service account must have roles/iam.serviceAccountTokenCreator on itself.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v7'

    - id: 'auth'
      uses: 'google-github-actions/auth@v3'
      with:
        token_format: 'access_token' # <--
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'
        access_token_lifetime: '300s' # optional, default: '3600s' (1 hour)

    # Example of using the output. The token is usually provided as a Bearer
    # token.
    - id: 'access-secret'
      run: |-
        curl https://secretmanager.googleapis.com/v1/projects/my-project/secrets/my-secret/versions/1:access \
          --header "Authorization: Bearer ${{ steps.auth.outputs.access_token }}"

Generating an ID Token (JWT)

This example demonstrates using this GitHub Action to generate a Google Cloud ID Token for authenticating to Google Cloud. This is commonly used when invoking a Cloud Run service.

Important

If you authenticate via credentials_json, the service account must have roles/iam.serviceAccountTokenCreator on itself.

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v7'

    - id: 'auth'
      uses: 'google-github-actions/auth@v3'
      with:
        token_format: 'id_token' # <--
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'
        id_token_audience: 'https://myapp-uvehjacqzq.a.run.app' # required, value depends on target
        id_token_include_email: true

    # Example of using the output. The token is usually provided as a Bearer
    # token.
    - id: 'invoke-service'
      run: |-
        curl https://myapp-uvehjacqzq.a.run.app \
          --header "Authorization: Bearer ${{ steps.auth.outputs.id_token }}"

    # Example of using ID token in Python code
    - id: 'python-example'
      run: |-
        python -c "
        import os
        import requests

        # ID token is available as environment variable
        id_token = os.environ.get('GOOGLE_ID_TOKEN', '${{ steps.auth.outputs.id_token }}')

        # Use the token to invoke a Cloud Run service
        response = requests.get(
            'https://myapp-uvehjacqzq.a.run.app',
            headers={'Authorization': f'Bearer {id_token}'}
        )
        print(response.text)
        "

Using Default Credentials with Scopes in Python

When using Workload Identity Federation with Python libraries, you may need to add scopes before refreshing credentials:

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v7'

    - id: 'auth'
      uses: 'google-github-actions/auth@v3'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: 'my-service-account@my-project.iam.gserviceaccount.com'

    - id: 'python-auth'
      run: |-
        python -c "
        from google.auth import default
        from google.auth.transport.requests import Request

        # Get default credentials
        credentials, project = default()

        # Add scopes before refreshing for impersonation
        credentials = credentials.with_scopes(
            ['https://www.googleapis.com/auth/cloud-platform']
        )

        # Refresh to get the token
        credentials.refresh(request=Request())

        # Now you can use the credentials
        print(f'Access token: {credentials.token}')
        if hasattr(credentials, 'id_token'):
            print(f'ID token: {credentials.id_token}')
        "