Deploying to GCP from GitHub Actions
This tutorial will show you how to use the Defang GitHub Action to deploy your project to GCP from your GitHub Actions workflow.
Prerequisites
The following steps will guide you through setting up a GitHub Actions workflow that can assume a role in your GCP account using OpenID Connect (OIDC) and deploy your project using the Defang GitHub Action. The role which will be assumed must have a trust relationship with an OIDC identity provider (IdP) for GitHub Actions, and that trust relationship must be configured to allow the specific repository and branch to assume the role. This ultimately allows the GitHub Actions workflow to securely access your GCP resources without needing to store long-lived GCP credentials in your repository.
Step 1 - Identify your GCP Project ID
To configure the GitHub Action to assume a role in your GCP project, you'll need your GCP Project ID.
- gcloud CLI
- GCP Console
You can list all of the projects you have access to with the following command:
gcloud projects list --format="value(projectId)"
export PROJECT_ID="my-project-123456" # export the project ID you want to use
Identify the appropriate project ID from the list and keep it handy for the next steps.
- Go to the GCP Console.
- Click on the project dropdown in the top navigation bar.
- Identify the appropriate project from the list.
- Your Project ID will be listed next to the project name.
Step 2 - Create a deployer Service Account
- gcloud CLI
- GCP Console
Using the gcloud CLI:
gcloud iam service-accounts create "deployer" \
--description="Service account used by Defang for deployment" \
--display-name="Deployer" \
--project="${PROJECT_ID}"
Using the GCP Console:
- Go to the Service Accounts page in the GCP Console.
- Click "Create Service Account" at the top of the page.
- For the Service account name, enter "Deployer"
- For the Service account ID, enter "deployer"
- For the Service account description, enter "Service account used by Defang for deployment"
- Click "Create and Continue"
- In the "Grant this service account access to the project" section, select the "Owner" role from the dropdown.
- Click "Continue"
- Click "Done"
Step 2 - Create a Workload Identity Pool
To configure the GitHub Action to assume a role in your GCP account, you'll need to create a Workload Identity Pool and a Workload Identity Provider in your GCP project.
Always add an Attribute Condition to restrict entry into the Workload Identity Pool.
We recommend replacing YOUR_REPOSITORY_OWNER and YOUR_REPOSITORY_NAME with your actual GitHub repository owner and name in the next step, and adjusting the assertion.ref condition to match your deployment branch. If you want to allow access from any branch, you can omit the assertion.ref condition.
We also recommend configuring GitHub Actions Environments. If you do not configure environments, you can omit the assertion.environment condition below.
- gcloud CLI
- GCP Console
Using the gcloud CLI:
Create a Workload Identity Pool
gcloud iam workload-identity-pools create "defang-github-actions-pool" \
--project="${PROJECT_ID}" \
--location="global" \
--display-name="Defang Github Actions Pool" \
--description="Allow Defang to deploy from Github Actions"
Add a Workload Identity Provider to the Pool
gcloud iam workload-identity-pools providers create-oidc "defang-github-actions-provider" \
--project="${PROJECT_ID}" \
--location="global" \
--workload-identity-pool="defang-github-actions-pool" \
--display-name="Defang Github Actions Provider" \
--issuer-uri="https://token.actions.githubusercontent.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner,attribute.environment=assertion.environment,attribute.ref=assertion.ref" \
--attribute-condition="assertion.repository_owner == YOUR_REPOSITORY_OWNER && assertion.repository == 'YOUR_REPOSITORY_NAME' && assertion.ref == 'refs/heads/main' && assertion.environment == 'YOUR_ENVIRONMENT'" \
Using the GCP Console:
Create a Workload Identity Pool
- Go to the Workload Identity Pools page in the GCP Console.
- If you haven't created a pool before, click "Get started", or "Create Pool" if you have.
- For the Name field, enter "Defang Github Actions Pool"
- For the Pool ID field, enter "defang-github-actions-pool"
- For the Description field, enter "Allow Defang to deploy from Github Actions"
- Make sure "Enabled pool" is toggled to the "on" position.
- Click "Continue"
Add a Workload Identity Provider
- After creating the Workload Identity Pool, you should be on the "Add Provider" page. If not, navigate to the Workload Identity Pools page, click on the "defang-github-actions-pool", and then click "Add Provider".
- Select the "OpenID Connect (OIDC)" provider from the "Select a Provider" dropdown.
- For the Provider Name field, enter "Defang Github Actions Provider"
- For the Provider ID field, enter "defang-github-actions-provider"
- For the Issuer URI field, enter
https://token.actions.githubusercontent.com - You do not need to upload a JSON Web Key Set (JWKS) URI, so leave that field blank.
- Use the default audience
- Click "Save"
Configure Provider Attributes
- For the
google.subjectattribute, theOIDC 1attribute should be set toassertion.sub. - Add a new attribute mapping for
attribute.repository_ownerand set it toassertion.repository_owner. - Add a new attribute mapping for
attribute.repositoryand set it toassertion.repository. - Add a new attribute mapping for
attribute.environmentand set it toassertion.environment. - Add a new attribute mapping for
attribute.refand set it toassertion.ref.
Configure Attribute Conditions
- Click on "Add Condition"
- For the Condition CEL, we recommend entering the following condition, replacing
YOUR_REPOSITORY_OWNERandYOUR_REPOSITORY_NAMEwith your actual GitHub repository owner and name.
attribute.repository_owner == 'YOUR_REPOSITORY_OWNER' && attribute.repository == 'YOUR_REPOSITORY_NAME' && attribute.ref == 'refs/heads/main'
- Click "Save"
Step 3 - Grant your GCP service account access to the Workload Identity Pool
- gcloud CLI
- GCP Console
Using the gcloud CLI:
Get the ID of the Workload Identity Pool we just created
WORKLOAD_IDENTITY_POOL_ID=$(gcloud iam workload-identity-pools describe "defang-github-actions-pool" \
--project="${PROJECT_ID}" \
--location="global" \
--format="value(name)") | awk -F/ '{print $6}')
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:deployer@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/owner"
--member="principalSet://iam.googleapis.com/${WORKLOAD_IDENTITY_POOL_ID}/attribute.repository/${REPO}"
Using the GCP Console:
- Open the GCP Console and navigate to the Workload Identity Pool page for the pool we just created.
- Click "Grant access" at the top of the page.
- Click "Grant access using service account impersonation"
- Select the "Deployer" service account we created earlier.
- Select principals:
a. Select
repositoryfrom the "Attribute name" dropdown. b. Enter your GitHub repository name in the "Attribute value" field. - Click the "Save" button.
Step 4 - Create a new GitHub Actions workflow
In your GitHub repository, create a new file at .github/workflows/deploy.yml with the following content:
name: Deploy with Defang
on:
push:
branches:
- main # Change this to your default branch if it's not 'main'
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
env:
GCP_PROJECT_ID: # Provide your GCP Project ID
steps:
- name: Configure GCP Credentials for Prod
uses: "google-github-actions/auth@v2"
with:
service_account: "deployer@${{ env.GCP_PROJECT_ID }}.iam.gserviceaccount.com"
workload_identity_provider: "projects/${{ env.GCP_PROJECT_ID }}/locations/global/workloadIdentityPools/defang-github-actions-pool/providers/defang-github-actions-provider"
token_format: access_token
access_token_scopes: https://www.googleapis.com/auth/cloud-platform
- name: Checkout Repo
uses: actions/checkout@v4
- name: Deploy
uses: DefangLabs/defang-github-action@v1.2.1
with:
mode: "balanced"
provider: "gcp"
Full documentation for configuring AWS and GCP credentials can be found in the Defang GitHub Action repository.