How cyclenerd/google-cloud-github-runner works
The product provisions ephemeral, regional Google Compute Engine runners for GitHub Actions and includes a web flow for configuring the GitHub App. The primary runtime path is a GitHub workflow-job webhook through signature verification and lifecycle handling to runner creation or deletion. Setup separately exchanges GitHub App configuration and stores credentials. Source excerpts support the application calls; README statements support the broader GCP deployment capabilities. Terraform internals were not sampled, so infrastructure relationships are limited to documented links.
Main entry points: webhook.py Webhook endpoint · setup.py Setup routes · webhook_service.py Webhook processing · gcloud_client.py Compute client
Components 17
Web application
- Flask application
app/__init__.py - Webhook endpoint
app/routes/webhook.py - Signature verification
app/utils/security.py
GitHub App setup
- Setup routes
app/routes/setup.py - GitHub App setup
app/services/github_service.py - Configuration storage
app/services/config_service.py
Runner lifecycle
- Webhook processing
app/services/webhook_service.py - GitHub API client
app/clients/github_client.py - Compute client
app/clients/gcloud_client.py
Google Cloud infrastructure
- Secret Manager
gcp/secret-manager.tf - Cloud Run service
gcp/cloud-run.tf - Runner templates
gcp/compute-vm.tf - Compute Engine
gcp/compute-vm.tf - Artifact Registry
gcp/artifact-registry.tf - VPC networking
gcp/net-vpc.tf
Other components
- Operator
- GitHub
Connections 20
- Operator → Setup routes: configures app
README.md - GitHub → Webhook endpoint: sends events
README.md - Flask application → Webhook endpoint: registers route
app/__init__.py - Flask application → Setup routes: registers routes
app/__init__.py - Webhook endpoint → Signature verification: verifies signature
app/routes/webhook.py - Webhook endpoint → Webhook processing: dispatches jobs
app/routes/webhook.py - Setup routes → GitHub App setup: generates and exchanges
app/routes/setup.py - Setup routes → Configuration storage: stores credentials
app/routes/setup.py - Configuration storage → Secret Manager: writes secrets
app/services/config_service.py - GitHub App setup → GitHub: exchanges app code
app/services/github_service.py - Webhook processing → GitHub API client: requests registration token
app/services/webhook_service.py - Webhook processing → Compute client: creates or deletes runner
app/services/webhook_service.py - GitHub API client → GitHub: requests runner token
app/clients/github_client.py - Compute client → Compute Engine: manages instances
app/clients/gcloud_client.py - Compute client → Runner templates: selects template
app/clients/gcloud_client.py - Cloud Run service → Webhook endpoint: hosts application
README.md - Cloud Run service → Secret Manager: uses stored credentials
README.md - Artifact Registry → Cloud Run service: supplies container image
README.md - VPC networking → Compute Engine: provides networking
README.md - GitHub → Compute Engine: runs jobs on ephemeral VMs
README.md