Build and deploy GitHub Actions self hosted runners to Google Cloud Anthos GKE, making them available to a given GitHub repository.

This project accompanies the "GitHub Actions self-hosted runners on Google Cloud" blog post.

A Continuous Integration job builds the image and publishes it to Google Container Registry, and a Continuous Deployment job deploys it to Google Kubernetes Engine (GKE). The self hosted runners in this cluster are made available to the GitHub repository configured via the GITHUB_REPO environment variable below.

Because a Docker-in-Docker sidecar pod has been used in this project, these self-hosted runners can also run container builds. Though this approach offers build flexibility, it requires a privileged security context and therefore extends the trust boundary to the whole cluster. Extra caution is recommended with this approach or removing the sidecar if your application doesn’t require container builds.

⚠️ Note that this use case is considered experimental and not officially supported by GitHub at this time. Additionally it’s recommended not to use self-hosted runners on public repositories for a number of security reasons.

• Create a new Google Cloud Platform project (docs)

gcloud projects create self-hosted-runner-test --name "Self Hosted Runner Test"

• Create a new Service Account (docs)

gcloud iam service-accounts create runner-admin \
    --description "Runner administrator"

• Grant roles to Service Account (docs). Note: should be restricted in production environments.

gcloud projects add-iam-policy-binding self-hosted-runner-test \
  --member serviceAccount:runner-admin@self-hosted-runner-test.iam.gserviceaccount.com \
  --role roles/admin

• Enable APIs (docs)

gcloud services enable \
    stackdriver.googleapis.com \
    compute.googleapis.com \
    container.googleapis.com \
    anthos.googleapis.com

• Create GKE cluster (docs)

gcloud container clusters create self-hosted-runner-test-cluster

• Register cluster to the environ docs

gcloud container hub memberships register self-hosted-anthos-membership \
  --project=self-hosted-runner-test-myid \
  --gke-uri=https://container.googleapis.com/v1/projects/self-hosted-runner-test-myid/locations/us-west1/clusters/self-hosted-runner-test-cluster \
  --service-account-key-file=/path-to/service-account-key.json

• Get the credentails for this cluster

gcloud container clusters get-credentials self-hosted-runner-test-cluster --region us-west1

• Use Kubernetes secrets to provide a Personal Access Token (TOKEN) and repository/organization (GITHUB_REPO) as environment variables available to your pods.

kubectl create secret generic self-hosted-runner-creds \
    --from-literal=GITHUB_REPO='<owner>/<repo>' \
    --from-literal=TOKEN='token'

• Set these as secrets in your GitHub repository:

  • GCP_PROJECT: ID of your Google Cloud Platform project, eg. self-hosted-runner-test-897234
  • GCP_KEY: Download your Service Account JSON credentials and Base64 encode them, eg. output of cat ~/path/to/my/credentials.json | base64
  • TOKEN: Personal Access Token. From the documentation, "Access tokens require repo scope for private repos and public_repo scope for public repos".

• Update these environment variables in cicd.yml according to the specific names you chose for your project:

  • GKE_CLUSTER: Name of your GKE cluster chosen above, eg. self-hosted-runner-test-cluster
  • GKE_SECRETS: Name of your secret configuration group, eg. self-hosted-runner-creds
  • GCP_REGION: The region your cluster is in, eg. us-central1
  • IMAGE: Name of your image used in ci.yml and deployment.yml
  • GITHUB_REPO: owner/repo of the repository that will use the self hosted runner, eg. octocat/sandbox

• Upon push of any image-related code to any branch, ci.yml will kick off to build and push the Docker image.
• Upon push of any code to master branch, cd.yml will kick off to deploy to Google Cloud.

• Replace Docker-in-Docker with Tekton, Buildah, etc.

We welcome contributions! See how to contribute.

MIT