Installation#

Cloud Shell (recommended)#

The fastest way to deploy gcrunner is with Google Cloud Shell. It provides a pre-configured environment with everything you need.

This opens an interactive tutorial that walks you through the full setup in about 15 minutes.

What you’ll need#

• A new GCP project with billing enabled
• A GitHub account with a repository to test against

What gets created#

Manual setup#

If you prefer to deploy manually, you can use Terraform directly.

Prerequisites#

• Terraform installed
• gcloud CLI installed and authenticated
• A GCP project with billing enabled

Deploy#

git clone https://github.com/camdenclark/gcrunner.git
cd gcrunner/terraform
gcloud storage buckets create gs://YOUR_PROJECT_ID-gcrunner-tfstate --location=us-central1
terraform init -backend-config="bucket=YOUR_PROJECT_ID-gcrunner-tfstate" -backend-config="prefix=gcrunner"
terraform apply -var="project_id=YOUR_PROJECT_ID"

Set up the GitHub App#

After Terraform completes, get the setup URL:

terraform output -raw setup_url

Open the URL in your browser, then:

1. Click Create GitHub App
2. Name the app and select where to install it
3. Select which repositories should have access to gcrunner
4. Complete the installation

The credentials (app ID, private key, webhook secret) are automatically stored in Secret Manager.

Configure your first workflow#

In any repository where you installed the GitHub App, use gcrunner in your workflow:

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: gcrunner=${{ github.run_id }}
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on gcrunner!"

Customizing your runner#

All configuration lives in the runs-on field using /-separated labels:

# Bigger machine, more disk
runs-on: gcrunner=${{ github.run_id }}/machine=c3-standard-8/disk=200gb

# No spot for production deploys
runs-on: gcrunner=${{ github.run_id }}/spot=false