tf-gcp-bootstrap

Terraform module for wiring GitHub Actions or other CI automation to a pre-provisioned Terraform service account in Google Cloud.

It is intended to be a small, reusable root module with secure-by-design defaults that are suitable for public-sector delivery and review.

The module does two things:

• Grants a host CI service account permission to impersonate the target Terraform service account.
• Assigns baseline and optional project-level IAM roles to the target Terraform service account in the target project.

What this module manages

For the target Google Cloud project, this module creates:

• google_service_account_iam_member bindings for each impersonation role in impersonation_roles.
• google_project_iam_member bindings for the target Terraform service account.

The target service account always receives these baseline project roles:

• roles/serviceusage.serviceUsageConsumer
• roles/iam.viewer

You can add more project roles with target_service_account_additional_roles.

A minimal publishable example is available in examples/minimal.

Usage

module "terraform_ci_setup" {
   source = "github.com/datasciencecampus/tf-gcp-bootstrap"

   project_id                 = "my-gcp-project"
   host_service_account_email = "github-actions@host-project.iam.gserviceaccount.com"
   target_service_account_email = "terraform@my-gcp-project.iam.gserviceaccount.com"

   target_service_account_additional_roles = [
      "roles/storage.admin",
      "roles/compute.viewer",
   ]
}

For reproducible downstream use, pin a release tag once published:

module "terraform_ci_setup" {
   source = "github.com/datasciencecampus/tf-gcp-bootstrap?ref=v0.1.0"

   project_id                   = "my-gcp-project"
   host_service_account_email   = "github-actions@host-project.iam.gserviceaccount.com"
   target_service_account_email = "terraform@my-gcp-project.iam.gserviceaccount.com"
}

Run Terraform from the repository root:

terraform init
terraform plan
terraform apply

Inputs and behavior

• project_id identifies the Google Cloud project where IAM bindings are applied.
• host_service_account_email is the CI identity that needs to impersonate the Terraform service account.
• target_service_account_email is the pre-existing service account used for Terraform operations in the target project.
• impersonation_roles defaults to roles/iam.serviceAccountTokenCreator.
• target_service_account_additional_roles lets you add project-level permissions beyond the built-in baseline roles.

This module assumes the target service account already exists before Terraform is applied.

The host CI service account email is required because the module always creates explicit impersonation bindings for the target Terraform service account.

Releases

GitHub Releases are managed with Release Please on pushes to main.

• Merge releasable changes with Conventional Commit subjects such as fix:, feat:, or feat!:.
• Release Please keeps a release PR up to date and creates the GitHub release and tag when that PR is merged.
• The tracked module version lives in version.txt and release notes are written to CHANGELOG.md.

If release PRs created by GitHub Actions are blocked, enable Allow GitHub Actions to create and approve pull requests in the repository Actions settings.

Requirements

Name	Version
terraform	>= 1.5.0, < 2.0.0
google	>= 6.0.0, < 8.0.0

Providers

Name	Version
google	7.33.0

Modules

No modules.

Resources

Name	Type
google_project_iam_member.target_service_account_additional_roles	resource
google_service_account_iam_member.impersonation	resource

Inputs

Name	Description	Type	Default	Required
host_service_account_email	Email of the host CI service account allowed to impersonate the target Terraform service account.	string	n/a	yes
impersonation_roles	IAM roles granted on the target service account to the host CI service account.	list(string)	[ "roles/iam.serviceAccountTokenCreator" ]	no
project_id	Google Cloud project ID for the target environment.	string	n/a	yes
target_service_account_additional_roles	Additional IAM roles to assign to the target Terraform service account.	list(string)	[]	no
target_service_account_email	Email of the pre-provisioned target Terraform service account in this project.	string	n/a	yes

Outputs

Name	Description
host_service_account_email	Email address of the host CI service account allowed to impersonate the target Terraform service account.
target_service_account_email	Email address of the target Terraform service account.