Authenticate to Google Cloud from GitHub Actions

These instructions use the [gcloud][gcloud] command-line tool.

• Create a Workload Identity Pool:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools create "github" \       --project="${PROJECT_ID}" \       --location="global" \       --display-name="GitHub Actions Pool"

• Get the full ID of the Workload Identity Pool:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools describe "github" \       --project="${PROJECT_ID}" \       --location="global" \       --format="value(name)"

This value should be of the format:

projects/123456789/locations/global/workloadIdentityPools/github

• Create a Workload Identity Provider in that pool:

# TODO: replace ${PROJECTID} and ${GITHUBORG} with your values below.
gcloud iam workload-identity-pools providers create-oidc "my-repo" \       --project="${PROJECT_ID}" \       --location="global" \       --workload-identity-pool="github" \       --display-name="My GitHub repo Provider" \       --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repositoryowner=assertion.repositoryowner" \       --attribute-c \       --issuer-uri="https://token.actions.githubusercontent.com"

> ❗️ IMPORTANT You must map any claims in the incoming token to > attributes before you can assert on those attributes in a CEL expression > or IAM policy!

• Extract the Workload Identity Provider resource name:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools providers describe "my-repo" \       --project="${PROJECT_ID}" \       --location="global" \       --workload-identity-pool="github" \       --format="value(name)"

Use this value as the workloadidentityprovider value in the GitHub Actions YAML:

- uses: 'google-github-actions/auth@v3'
      with:
        project_id: 'my-project'
        workloadidentityprovider: '...' # "projects/123456789/locations/global/workloadIdentityPools/github/providers/my-repo"

> ❗️ IMPORTANT The project_id input is optional, but may be required > by downstream authentication systems such as the gcloud CLI. > Unfortunately we cannot extract the project ID from the Workload Identity > Provider, since it requires the project number. > > It is technically possible to convert a project number into a project > ID, but it requires permissions to call Cloud Resource Manager, and we > cannot guarantee that the Workload Identity Pool has those permissions.

• As needed, allow authentications from the Workload Identity Pool to Google

The following example shows granting access from a GitHub Action in a specific repository a secret in Google Secret Manager.

# TODO: replace ${PROJECTID}, ${WORKLOADIDENTITYPOOLID}, and ${REPO}
    # with your values below.
    #
    # ${REPO} is the full repo name including the parent GitHub organization,
    # such as "my-org/my-repo".
    #
    # ${WORKLOADIDENTITYPOOL_ID} is the full pool id, such as
    # "projects/123456789/locations/global/workloadIdentityPools/github".
gcloud secrets add-iam-policy-binding "my-secret" \       --project="${PROJECT_ID}" \       --role="roles/secretmanager.secretAccessor" \       --member="principalSet://iam.googleapis.com/${WORKLOADIDENTITYPOOL_ID}/attribute.repository/${REPO}"

Review the [GitHub documentation][github-oidc] for a complete list of options and values. This GitHub repository does not seek to enumerate every possible combination.

These instructions use the [gcloud][gcloud] command-line tool.

• (Optional) Create a Google Cloud Service Account. If you already have a

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam service-accounts create "my-service-account" \       --project "${PROJECT_ID}"

• Create a Workload Identity Pool:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools create "github" \       --project="${PROJECT_ID}" \       --location="global" \       --display-name="GitHub Actions Pool"

• Get the full ID of the Workload Identity Pool:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools describe "github" \       --project="${PROJECT_ID}" \       --location="global" \       --format="value(name)"

This value should be of the format:

projects/123456789/locations/global/workloadIdentityPools/github

• Create a Workload Identity Provider in that pool:

# TODO: replace ${PROJECTID} and ${GITHUBORG} with your values below.
gcloud iam workload-identity-pools providers create-oidc "my-repo" \       --project="${PROJECT_ID}" \       --location="global" \       --workload-identity-pool="github" \       --display-name="My GitHub repo Provider" \       --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repositoryowner=assertion.repositoryowner" \       --attribute-c \       --issuer-uri="https://token.actions.githubusercontent.com"

> ❗️ IMPORTANT You must map any claims in the incoming token to > attributes before you can assert on those attributes in a CEL expression > or IAM policy!

• Allow authentications from the Workload Identity Pool to your Google Cloud

# TODO: replace ${PROJECTID}, ${WORKLOADIDENTITYPOOLID}, and ${REPO}
    # with your values below.
    #
    # ${REPO} is the full repo name including the parent GitHub organization,
    # such as "my-org/my-repo".
    #
    # ${WORKLOADIDENTITYPOOL_ID} is the full pool id, such as
    # "projects/123456789/locations/global/workloadIdentityPools/github".
gcloud iam service-accounts add-iam-policy-binding "my-service-account@${PROJECT_ID}.iam.gserviceaccount.com" \       --project="${PROJECT_ID}" \       --role="roles/iam.workloadIdentityUser" \       --member="principalSet://iam.googleapis.com/${WORKLOADIDENTITYPOOL_ID}/attribute.repository/${REPO}"

Review the [GitHub documentation][github-oidc] for a complete list of options and values. This GitHub repository does not seek to enumerate every possible combination.

• Extract the Workload Identity Provider resource name:

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam workload-identity-pools providers describe "my-repo" \       --project="${PROJECT_ID}" \       --location="global" \       --workload-identity-pool="github" \       --format="value(name)"

Use this value as the workloadidentityprovider value in the GitHub Actions YAML:

- uses: 'google-github-actions/auth@v3'
      with:
        service_account: '...' # my-service-account@my-project.iam.gserviceaccount.com
        workloadidentityprovider: '...' # "projects/123456789/locations/global/workloadIdentityPools/github/providers/my-repo"

• As needed, grant the Google Cloud Service Account permissions to access

# TODO: replace ${PROJECT_ID} with your value below.
gcloud secrets add-iam-policy-binding "my-secret" \       --project="${PROJECT_ID}" \       --role="roles/secretmanager.secretAccessor" \       --member="serviceAccount:my-service-account@${PROJECT_ID}.iam.gserviceaccount.com"

These instructions use the [gcloud][gcloud] command-line tool.

• (Optional) Create a Google Cloud Service Account. If you already have a

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam service-accounts create "my-service-account" \       --project "${PROJECT_ID}"

• Create a Service Account Key JSON for the Service Account.

# TODO: replace ${PROJECT_ID} with your value below.
gcloud iam service-accounts keys create "key.json" \       --iam-account "my-service-account@${PROJECT_ID}.iam.gserviceaccount.com"

• Upload the contents of this file as a GitHub Actions

Use the name of the GitHub Actions secret as the credentials_json value in the GitHub Actions YAML:

- uses: 'google-github-actions/auth@v3'
      with:
        credentialsjson: '${{ secrets.GOOGLECREDENTIALS }}' # Replace with the name of your GitHub Actions secret