This tutorial shows you how to use self-hosted GitHub runners on worker pools to execute the workflows defined in your GitHub repository, and scale your worker pool with Cloud Run External Metrics Autoscaling (CREMA).
About self-hosted GitHub runners
In a GitHub Actions workflow, runners are the machines that execute jobs. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.
You can use self-hosted runners to run GitHub Actions on Cloud Run worker pool instances. This tutorial shows you how to automatically scale a pool of runners based on the number of running and unscheduled jobs.
Objectives
In this tutorial, you will:
Add self-hosted GitHub runners to support a GitHub repository, and create Secret Manager secrets to securely store tokens and secrets.
Deploy a Cloud Run worker pool to Cloud Run and use the worker pool to accept jobs from GitHub actions.
Deploy the autoscaler CREMA service to scale your worker pool.
Test your CREMA service by verifying logs.
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage,
use the pricing calculator.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Cloud Run, Secret Manager, Parameter Manager, Artifact Registry, and Cloud Build APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.- Install and initialize the gcloud CLI.
- Update components:
gcloud components update
- Set the following configuration variables for CREMA used in this tutorial:
PROJECT_ID=PROJECT_ID CREMA_SERVICE_ACCOUNT_NAME=crema-service-account@$PROJECT_ID.iam.gserviceaccount.com CREMA_REPO_NAME=crema AR_REGION=us-central1
- You incur charges for your Cloud Run scaling service based on how often you trigger scaling. For more information, estimate costs with the pricing calculator.
Required roles
To get the permissions that you need to complete the tutorial, ask your administrator to grant you the following IAM roles on your project:
- Artifact Registry Repository Administrator (
roles/artifactregistry.repoAdmin) - Cloud Build Editor (
roles/cloudbuild.builds.editor) - Cloud Run Admin (
roles/run.admin) - Create Service Accounts (
roles/iam.serviceAccountCreator) - Secret Manager Admin (
roles/secretmanager.admin) - Service Account User (
roles/iam.serviceAccountUser) - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer) - Storage Admin (
roles/storage.admin) - Parameter Manager Admin (
roles/parametermanager.admin)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
You need permission to edit the settings on a GitHub repository to configure the self-hosted runners. The repository can be user-owned, or an organisation owned repository.
GitHub recommends using self-hosted runners with private repositories only.
Create a custom service account
This tutorial uses a custom service account with the minimum permissions required to use the provisioned resources. To set up the service account, do the following:
gcloud iam service-accounts create crema-service-account \
--display-name="CREMA Service Account"
Add self-hosted GitHub runners
To add self-hosted GitHub runners, follow the instructions in adding self-hosted runners in the GitHub documentation.
Identify the GitHub repository
In this tutorial, the GITHUB_REPO variable represents the repository name. This is the part of the name that you find after the domain name for both personal user repositories and organization repositories. For example:
- If your domain URL is
https://github.com/myuser/myrepo, the GITHUB_REPO ismyuser/myrepo. - If your domain URL is
https://github.com/mycompany/ourrepo, the GITHUB_REPO ismycompany/ourrepo.
Create access token
Create a GitHub access token to dynamically add and remove runners by interacting with your selected repository. To create an access token on GitHub and save it in the Secret Manager, follow these steps:
- Ensure you are logged into your GitHub account.
- Navigate to GitHub's Settings > Developer Settings > Personal Access Tokens > Tokens (classic) page.
- Click Generate new token, and select Generate new token (classic).
- For the token scope, select the repo checkbox.
- Click Generate token.
- Copy the generated token.
For more information on access tokens see Authentication requirements in GitHub documentation.
Create a secret for your access token using Secret Manager
Take the secret token you created in the previous step, and store it in Secret Manager. To set access permissions, follow these steps:
Create the secret in Secret Manager:
echo -n "GITHUB_TOKEN" | gcloud secrets create github_runner_token --data-file=-Replace the GITHUB_TOKEN with the value you copied from GitHub.
Grant the
roles/secretmanager.secretAccessorto your custom service account to access your newly created secret:gcloud secrets add-iam-policy-binding github_runner_token \ --member "serviceAccount:$CREMA_SERVICE_ACCOUNT_NAME" \ --role "roles/secretmanager.secretAccessor"
Deploy a worker pool
Create a Cloud Run worker pool to process GitHub actions. This pool will use an image based on the GitHub-created actions/runner image. To deploy a worker pool, follow these steps:
Clone the sample repository to your local machine to retrieve the code sample for use:
git clone https://github.com/GoogleCloudPlatform/cloud-run-samplesChange to the directory that contains the Cloud Run sample code:
cd cloud-run-samples/github-runner/worker-pool-containerDeploy the worker pool:
gcloud run worker-pools deploy WORKER_POOL_NAME \ --region us-central1 \ --source . \ --instances 1 \ --set-env-vars GITHUB_REPO=GITHUB_REPO \ --set-secrets GITHUB_TOKEN=github_runner_token:latest \ --service-account $CREMA_SERVICE_ACCOUNT_NAME \ --memory 2Gi \ --cpu 4Replace the following:
- WORKER_POOL_NAME: the name of the worker pool
- WORKER_POOL_LOCATION: the region of the worker pool
- GITHUB_REPO: the GitHub repo name
If this is the first time using Cloud Run source deploys in this project, Cloud Run prompts you to create a default Artifact Registry repository.
Understand the code sample
The worker pool is configured with a Dockerfile that is based on the GitHub-created actions/runner image: