Skip to content

CLOUD_SHELL_TUTORIAL.md

Latest commit

 

History

History
150 lines (96 loc) · 4.6 KB

CLOUD_SHELL_TUTORIAL.md

File metadata and controls

150 lines (96 loc) · 4.6 KB

Self-Hosted GitHub Actions Runners for Google Cloud

Welcome 👋!

This tutorial guides you through deploying the self-hosted GitHub Actions Runners using Google Cloud Shell.

Prerequisites: A GCP project with billing enabled. The Owner role is the easiest option for this tutorial. If the Owner role is not possible, see gcp/README.md for the specific roles required.

Click the Start button to move to the next step.

Step 1: Project Setup

Select or create a project:

Enable the required APIs:

Step 2: Configure Environment

Set Google Cloud project ID. Replace with your current Google Cloud project ID:

export GOOGLE_CLOUD_PROJECT="<walkthrough-project-id/>"

Configure gcloud to use this project:

gcloud config set project "$GOOGLE_CLOUD_PROJECT"
gcloud auth application-default set-quota-project "$GOOGLE_CLOUD_PROJECT"

Step 3: Verify Organization Policies

Crucial Step: If you are deploying within an organization (e.g., a company account), certain policies might block public access to Cloud Run.

Check Ingress (Should be allowAll: true):

gcloud org-policies describe "run.allowedIngress" --effective --project="$GOOGLE_CLOUD_PROJECT" --quiet

If these are restrictive, you may need to ask your Organization Admin to adjust them or use a project outside the organization. See gcp/README.md for policy details.

Step 4: Deploy with Terraform

The Terraform version pre-installed in Google Cloud Shell is too old. Install a current Terraform version:

curl "https://releases.hashicorp.com/terraform/1.14.5/terraform_1.14.5_linux_amd64.zip" -o "$HOME/terraform.zip"
unzip "$HOME/terraform.zip" terraform -d "$HOME"
export PATH="$HOME:$PATH"

Navigate to the gcp directory:

cd gcp

Create a terraform.tfvars file with your configuration.

Google Cloud project ID:

printf 'project_id = "%s"\n' "$GOOGLE_CLOUD_PROJECT" > terraform.tfvars

(Optional) Google Cloud region:

echo "region = \"us-central1\"" >> terraform.tfvars

(Optional) Google Cloud zone:

echo "zone = \"b\"" >> terraform.tfvars

For more details, see gcp/README.md. You find there a list of all variables and their default values.

Initialize Terraform:

$HOME/terraform init

Apply the configuration:

$HOME/terraform apply
  • Review the plan when prompted.
  • Type yes and press Enter to confirm.

Step 5: Complete Setup

Once Terraform completes successfully, it will output a service_url.

  1. Copy the service_url (e.g., https://google-cloud-github-runner-xyz-uc.a.run.app).

  2. Open your browser and navigate to service_url.

    Authentication Required: You will be prompted for HTTP Basic Authentication credentials:

    • Username: cloud
    • Password: Your Google Cloud Project ID <walkthrough-project-id/> (the value you set in GOOGLE_CLOUD_PROJECT)

  3. Click Setup GitHub App, then install it on your target Organization or Repository.

Step 6: Update Workflows

Configure your GitHub Actions CI/CD to use the runners. The runs-on key must match the name of the GCE Instance Template (e.g., gcp-ubuntu-latest or gcp-ubuntu-24-04-8core-arm).

jobs:
  test:
    runs-on: gcp-ubuntu-latest  # Must match GCE Template Name
    steps:
      - run: echo "Hello from Google Cloud!"

Optional: Migrate Terraform State to GCS

By default, Terraform stores state locally. It's highly recommended to migrate this state to a remote Google Cloud Storage (GCS) backend.

Copy providers.tf.gcs to providers.tf (configured for GCS backend):

cp providers.tf.gcs providers.tf

Run $HOME/terraform init -migrate-state to copy your local state to the bucket:

$HOME/terraform init -migrate-state

Done 🎉

You can now use the self-hosted GitHub Actions Runners on Google Cloud.