Test Infrastructure

This repository defines the GitHub repository configurations and test infrastructure for testing GitHub Actions.

This is not an officially supported Google product, and it is not covered by a Google Cloud support contract. To report bugs or request features in a Google Cloud product, please contact Google Cloud support.

Principles

The test infrastructure uses the following principles:

• There is value in reduction of choice and sane defaults. We minimize the number of Terraform variables and conditionals to optimize for readability.

• Only introduce Terraform variables when they are explicitly needed and have sane default values.

• Minimize dependencies on external modules unless they add significant value or mask significant complexity.

Design

Each project has its own Google Cloud Service Account and Workload Identity Federation Provider for authentication and authorization. Repositories are automatically configured with GitHub variables that inject these configuration variables as:

• PROJECT_ID
• SERVICE_ACCOUNT_EMAIL
• WIF_PROVIDER_NAME

Authentication to the WIF provider is guarded by the organization ID (forks won't have access) and the numeric repository ID. Using IDs prevents against replay naming attacks.

Additionally, there is an organization secret (accessible to all repos) ACTIONS_BOT_TOKEN which is a GitHub Personal Access Token for our GitHub Actions bot. This is largely for authoring commits, since the Google CLA cannot be signed by the GitHub Actions bot.

Additional per-repository variables and secrets and configuration should reside inside the project Terraform file.

Setup

1. (First time only) Create a terraform.tfvars file with the following information:

   # This is the project ID of your Google Cloud project. You must create the Google Cloud project in advance.
   project_id = "TODO"
   
   # This is the GitHub organization name.
   github_organization_name = "TODO"

2. Install and configure the Google Cloud SDK, and authenticate as a principle that has permissions to manage resources in the given "project_id".

   gcloud auth login --update-adc

3. Create a GitHub Personal Access Token with permissions to administer repositories and configuration over the target organization defined in "github_organization_name".

   If you use the gh cli, you can generate an access token automatically:

   export GITHUB_TOKEN="$(gh auth token)"

   If you do not use the gh cli, you will need to create a Personal Access Token (PAT):

   Creating Person Access Tokens in the GitHub documentation.

   Save this as the environment variable GITHUB_TOKEN:

   export GITHUB_TOKEN="TODO"

   If you start a new shell, you will need to export the token again. For this reason, we recommend storing the token in a password manager so you do not have to generate a new one each time.

Creating new repos

After following the internal team documentation to get legal approval for a new repository, follow these steps to bootstrap a new project.

1. Create a new Terraform file with the naming convention:

   project_<reponame>.tf
   

2. Define the project module, or copy-paste an existing project as a skeleton. Make sure you properly define the repository name, description, labels, and ACLs. The following default ACLs are always added:

   google-github-actions-bot (triage)
   @google-github-actions/maintainers (admin)
   

3. Add any other resources the project will need, such as secrets or IAM permissions. Note that the project module automatically configures Workload Identity Federation and provides a service account email as an output.

4. If you need to enable any new Google Cloud services, add them in the main.tf file.

5. Since Google's internal system will have already created the repository, you must import it into the Terraform state. You only need to do this the first time.

   terraform import module.<repo_name>.github_repository.repo <repo_name>

   For example, to import the setup-gcloud repo:

   terraform import module.setup-gcloud.github_repository.repo setup-gcloud

6. Run terraform apply to provision the changes. To limit to just your new project, run a targeted apply:

   terraform apply -target module.<repo_name>

Rotating Service Account Keys

Only a few repositories rely on Service Account Key JSON files, mostly to test that the GitHub Action works with exported keys. To rotate all the keys, run this script:

./scripts/rotate-service-account-keys

The script searches for and taints all google_service_account_key resources and runs terraform apply.