GitHub-Runner mit Cloud Run-Worker-Pools hosten

In dieser Anleitung erfahren Sie, wie Sie selbstgehostete GitHub-Runner in Worker-Pools verwenden, um die in Ihrem GitHub-Repository definierten Workflows auszuführen.

Sie stellen einen Cloud Run-Worker-Pool zur Verarbeitung dieser Arbeitslast bereit und optional eine Cloud Run-Funktion zur Unterstützung der Skalierung des Worker-Pools.

Selbst gehostete GitHub-Runner

In einem GitHub Actions-Workflow sind Runner die Maschinen, auf denen Jobs ausgeführt werden. Ein Runner kann beispielsweise Ihr Repository lokal klonen, Testsoftware installieren und dann Befehle ausführen, mit denen Ihr Code ausgewertet wird.

Sie können selbst gehostete Runner verwenden, um GitHub Actions auf Cloud Run-Workerpool-Instanzen auszuführen. In dieser Anleitung wird gezeigt, wie Sie einen Pool von Runnern automatisch skalieren, basierend auf der Anzahl der laufenden und nicht geplanten Jobs. Der Pool kann sogar auf null skaliert werden, wenn keine Jobs vorhanden sind.

Ziele

In dieser Anleitung wird Folgendes beschrieben:

  • Cloud Run-Worker-Pool in Cloud Run bereitstellen
  • Cloud Run-Funktion zur Unterstützung der Skalierung des Worker-Pools bereitstellen
  • Erstellen Sie Secret Manager-Secrets, um Tokens und Secrets sicher zu speichern.
  • Stellen Sie einen selbst gehosteten GitHub-Runner zur Unterstützung eines GitHub-Repositorys bereit.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

  1. 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.

  2. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the Cloud Run, Secret Manager, Artifact Registry, and Cloud Build APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    7. Erforderliche Rollen

    Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Anleitung benötigen:

    Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

    Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

    Sie benötigen die Berechtigung zum Bearbeiten der Einstellungen für ein GitHub-Repository, um die selbstgehosteten Runner zu konfigurieren. Das Repository kann einem Nutzer oder einer Organisation gehören.

Codebeispiel abrufen

So rufen Sie das gewünschte Codebeispiel ab:

  1. Klonen Sie das Beispiel-Repository auf Ihren lokalen Computer:

    git clone https://github.com/GoogleCloudPlatform/cloud-run-samples

  2. Wechseln Sie in das Verzeichnis, das den Cloud Run-Beispielcode enthält:

    cd cloud-run-samples/github-runner

Kerncode verstehen

Das Beispiel wird als Worker-Pool und Autoscaler implementiert, wie im Folgenden beschrieben.

Worker-Pool

Der Worker-Pool wird mit einem Dockerfile konfiguriert, das auf dem von GitHub erstellten Image actions/runner basiert.

Die gesamte Logik ist in diesem Bild enthalten, abgesehen von einem kleinen Hilfsskript.

FROM ghcr.io/actions/actions-runner:2.329.0

# Add scripts with right permissions.
USER root
# hadolint ignore=DL3045
COPY start.sh start.sh
RUN chmod +x start.sh

# Add start entrypoint with right permissions.
USER runner
ENTRYPOINT ["./start.sh"]

Dieses Hilfsskript wird beim Start des Containers ausgeführt und registriert sich mit einem von Ihnen erstellten Token als temporäre Instanz im konfigurierten Repository. Das Skript definiert auch, welche Aktionen ausgeführt werden sollen, wenn der Container skaliert wird.

# Configure the current runner instance with URL, token and name.
mkdir /home/docker/actions-runner && cd /home/docker/actions-runner
echo "GitHub Repo: ${GITHUB_REPO_URL} for ${RUNNER_PREFIX}-${RUNNER_SUFFIX}"
./config.sh --unattended --url ${GITHUB_REPO_URL} --pat ${GH_TOKEN} --name ${RUNNER_NAME}

# Function to cleanup and remove runner from Github.
cleanup() {
   echo "Removing runner..."
   ./config.sh remove --unattended --pat ${GH_TOKEN}
}

# Trap signals.
trap 'cleanup; exit 130' INT
trap 'cleanup; exit 143' TERM

# Run the runner.
./run.sh & wait $!

Autoscaling

Der Autoscaler ist eine Funktion, die den Worker-Pool hochskaliert, wenn sich ein neuer Job in der Warteschlange befindet, oder herunterskaliert, wenn ein Job abgeschlossen ist. Dazu wird die Cloud Run API verwendet, um die aktuelle Anzahl der Worker im Pool zu prüfen und diesen Wert nach Bedarf anzupassen.

try:
    current_instance_count = get_current_worker_pool_instance_count()
except ValueError as e:
    return f"Could not retrieve instance count: {e}", 500

# Scale Up: If a job is queued and we have available capacity
if action == "queued" and job_status == "queued":
    print(f"Job '{job_name}' is queued.")

    if current_instance_count < MAX_RUNNERS:
        new_instance_count = current_instance_count + 1
        try:
            update_runner_instance_count(new_instance_count)
            print(f"Successfully scaled up to {new_instance_count} instances.")
        except ValueError as e:
            return f"Error scaling up instances: {e}", 500
    else:
        print(f"Max runners ({MAX_RUNNERS}) reached.")

# Scale Down: If a job is completed, check to see if there are any more pending
# or in progress jobs and scale accordingly.
elif action == "completed" and job_status == "completed":
    print(f"Job '{job_name}' completed.")

    current_queued_actions, current_running_actions = get_current_actions()
    current_actions = current_queued_actions + current_running_actions

    if current_queued_actions >= 1:
        print(
            f"GitHub says {current_queued_actions} are still pending."
            f"Won't change scaling ({current_instance_count})."
        )
    elif current_queued_actions == 0 and current_running_actions >= 1:
        print(
            f"GitHub says no queued actions, but {current_running_actions} running actions."
            f"Won't change scaling ({current_instance_count})."
        )
    elif current_actions == 0:
        print(f"GitHub says no pending actions. Scaling to zero.")
        update_runner_instance_count(0)
        print(f"Successfully scaled down to zero.")
    else:
        print(
            f"Detected an unhandled state: {current_queued_actions=}, {current_running_actions=}"
        )
else:
    print(
        f"Workflow job event for '{job_name}' with action '{action}' and "
        f"status '{job_status}' did not trigger a scaling action."
    )

IAM konfigurieren

In dieser Anleitung wird ein benutzerdefiniertes Dienstkonto mit den erforderlichen Mindestberechtigungen für die Verwendung der bereitgestellten Ressourcen verwendet. So richten Sie das Dienstkonto ein:

  1. Legen Sie Ihre Projekt-ID in gcloud fest:

    gcloud config set project PROJECT_ID

    Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

  2. So erstellen Sie ein neues Dienstkonto für Identity and Access Management:

    gcloud iam service-accounts create gh-runners

  3. Gewähren Sie dem Dienstkonto Berechtigungen, um als Dienstkonto für Ihr Projekt zu agieren:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member "serviceAccount:gh-runners@PROJECT_ID.iam.gserviceaccount.com" \
  --role=roles/iam.serviceAccountUser

    Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

GitHub-Informationen abrufen

In der GitHub-Dokumentation zum Hinzufügen selbstgehosteter Runner wird empfohlen, Runner über die GitHub-Website hinzuzufügen. Dort wird dann ein bestimmtes Token für die Authentifizierung bereitgestellt.

In dieser Anleitung werden Runner dynamisch hinzugefügt und entfernt. Dazu ist ein statisches GitHub-Token erforderlich.

Für diese Anleitung müssen Sie ein GitHub-Token mit Zugriff zum Interagieren mit dem ausgewählten Repository erstellen.

GitHub-Repository identifizieren

In dieser Anleitung steht die Variable GITHUB_REPO für den Namen des Repositorys. Dies ist der Teil des GitHub-Repository-Namens, der nach dem Domainnamen steht, sowohl für persönliche Nutzer- als auch für Organisations-Repositories.

Sie verweisen sowohl bei Repositories im Besitz von Nutzern als auch bei Repositories im Besitz von Organisationen auf den Repository-Namen, der nach dem Domainnamen steht.

In dieser Anleitung:

  • Für https://github.com/myuser/myrepo ist GITHUB_REPO gleich myuser/myrepo.
  • Für https://github.com/mycompany/ourrepo ist GITHUB_REPO gleich mycompany/ourrepo.

Zugriffstoken erstellen

Sie müssen ein Zugriffstoken auf GitHub erstellen und es sicher in Secret Manager speichern:

  1. Melden Sie sich in Ihrem GitHub-Konto an.
  2. Rufen Sie auf GitHub die Seite Settings > Developer Settings > Personal Access Tokens (Einstellungen > Entwicklereinstellungen > Persönliche Zugriffstokens) auf.
  3. Klicken Sie auf Neues Token erstellen und wählen Sie Neues Token erstellen (klassisch) aus.
  4. Erstellen Sie ein neues Token mit dem Bereich „repo“.
  5. Klicken Sie auf Generate token (Token generieren).
  6. Kopieren Sie das generierte Token.

Secret-Wert erstellen

Nehmen Sie das Secret-Token, das Sie gerade erstellt haben, speichern Sie es in Secret Manager und legen Sie Zugriffsberechtigungen fest.

  1. Erstellen Sie das Secret in Secret Manager:

    echo -n "GITHUB_TOKEN" | gcloud secrets create github_runner_token --data-file=-

    Ersetzen Sie GITHUB_TOKEN durch den Wert, den Sie aus GitHub kopiert haben.

  2. Gewähren Sie Zugriff auf das neu erstellte Secret:

    gcloud secrets add-iam-policy-binding github_runner_token \
  --member "serviceAccount:gh-runners@PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/secretmanager.secretAccessor"

Worker-Pool bereitstellen

Cloud Run-Worker-Pool zum Verarbeiten von GitHub-Aktionen erstellen Für diesen Pool wird ein Image verwendet, das auf dem von GitHub erstellten actions/runner-Image basiert.

Cloud Run-Worker-Pool einrichten

  1. Rufen Sie den Beispielcode für den Worker-Pool auf:

    cd worker-pool-container

  2. Stellen Sie den Worker-Pool bereit:

    gcloud beta run worker-pools deploy WORKER_POOL_NAME \
  --region WORKER_POOL_LOCATION \
  --source . \
  --scaling 1 \
  --set-env-vars GITHUB_REPO=GITHUB_REPO \
  --set-secrets GITHUB_TOKEN=github_runner_token:latest \
  --service-account gh-runners@PROJECT_ID.iam.gserviceaccount.com \
  --memory 2Gi \
  --cpu 4

    Ersetzen Sie Folgendes:

    • WORKER_POOL_NAME: der Name des Worker-Pools
    • WORKER_POOL_LOCATION die Region des Worker-Pools
    • GITHUB_REPO ist der Name des ermittelten GitHub-Repositorys.
    • PROJECT_ID: die Google Cloud -Projekt-ID

    Wenn Sie Cloud Run-Quellbereitstellungen in diesem Projekt zum ersten Mal verwenden, werden Sie aufgefordert, ein Standard-Artifact Registry-Repository zu erstellen.

Worker-Pool verwenden

Sie haben jetzt eine einzelne Instanz in Ihrem Worker-Pool, die bereit ist, Jobs von GitHub Actions anzunehmen.

Um zu prüfen, ob Sie die Einrichtung Ihres selbstgehosteten Runners abgeschlossen haben, rufen Sie eine GitHub-Aktion in Ihrem Repository auf.

Damit Ihre Aktion Ihre selbst gehosteten Runner verwendet, müssen Sie den Job einer GitHub-Aktion ändern. Ändern Sie im Job den Wert von runs-on in self-hosted.

Wenn Ihr Repository noch keine Aktionen enthält, können Sie der Schnellstartanleitung für GitHub Actions folgen.

Nachdem Sie eine Aktion für die Verwendung der selbstgehosteten Runner konfiguriert haben, führen Sie die Aktion aus.

Prüfen Sie, ob die Aktion in der GitHub-Oberfläche erfolgreich abgeschlossen wurde.

GitHub Runner Autoscaler bereitstellen

Sie haben einen Worker in Ihrem ursprünglichen Pool bereitgestellt, sodass jeweils nur eine Aktion verarbeitet werden kann. Je nach CI-Nutzung müssen Sie Ihren Pool möglicherweise skalieren, um eine große Menge an zu erledigender Arbeit zu bewältigen.

Nachdem Sie den Worker-Pool mit einem aktiven GitHub-Runner bereitgestellt haben, konfigurieren Sie den Autoscaler so, dass Worker-Instanzen basierend auf dem Jobstatus in der Aktionswarteschlange bereitgestellt werden.

Bei dieser Implementierung wird auf ein workflow_job-Ereignis gewartet. Wenn ein Workflow-Job erstellt wird, wird der Worker-Pool hochskaliert. Sobald der Job abgeschlossen ist, wird er wieder herunterskaliert. Der Pool wird nicht über die konfigurierte maximale Anzahl von Instanzen hinaus skaliert und auf null skaliert, wenn alle ausgeführten Jobs abgeschlossen sind.

Sie können diesen Autoscaler an Ihre Arbeitslasten anpassen.

Webhook-Secret-Wert erstellen

So erstellen Sie einen Secret-Wert für den Webhook:

  1. Erstellen Sie ein Secret Manager-Secret, das einen beliebigen Stringwert enthält.

    echo -n "WEBHOOK_SECRET" | gcloud secrets create github_webhook_secret --data-file=-

    Ersetzen Sie WEBHOOK_SECRET durch einen beliebigen Stringwert.

  2. Gewähren Sie dem Autoscaler-Dienstkonto Zugriff auf das Secret:

    gcloud secrets add-iam-policy-binding github_webhook_secret \
  --member "serviceAccount:gh-runners@PROJECT_ID.iam.gserviceaccount.com" \
  --role "roles/secretmanager.secretAccessor"

Funktion für den Empfang von Webhook-Anfragen bereitstellen

So stellen Sie die Funktion zum Empfangen von Webhook-Anfragen bereit:

  1. Rufen Sie den Beispielcode für den Webhook auf:

    cd ../autoscaler

  2. Stellen Sie die Cloud Run-Funktion bereit:

    gcloud run deploy github-runner-autoscaler \
  --function github_webhook_handler \
  --region WORKER_POOL_LOCATION \
  --source . \
  --set-env-vars GITHUB_REPO=GITHUB_REPO \
  --set-env-vars WORKER_POOL_NAME=WORKER_POOL_NAME \
  --set-env-vars WORKER_POOL_LOCATION=WORKER_POOL_LOCATION \
  --set-env-vars MAX_RUNNERS=5 \
  --set-secrets GITHUB_TOKEN=github_runner_token:latest \
  --set-secrets WEBHOOK_SECRET=github_webhook_secret:latest \
  --service-account gh-runners@PROJECT_ID.iam.gserviceaccount.com \
  --allow-unauthenticated

    Ersetzen Sie Folgendes:

    • GITHUB_REPO – der Teil des Namens Ihres GitHub-Repositorys nach dem Domainnamen
    • WORKER_POOL_NAME: der Name des Worker-Pools
    • WORKER_POOL_LOCATION die Region des Worker-Pools
    • REPOSITORY_NAME ist der Name des GitHub-Repositorys.

  3. Notieren Sie sich die URL, unter der Ihr Dienst bereitgestellt wurde. Sie benötigen diesen Wert in einem späteren Schritt.

  4. Gewähren Sie dem Dienstkonto die Berechtigungen zum Aktualisieren Ihres Worker-Pools:

    gcloud alpha run worker-pools add-iam-policy-binding WORKER_POOL_NAME \
  --member "serviceAccount:gh-runners@PROJECT_ID.iam.gserviceaccount.com" \
  --role=roles/run.developer

    Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

GitHub-Webhook erstellen

So erstellen Sie den GitHub-Webhook:

  1. Melden Sie sich in Ihrem GitHub-Konto an.
  2. Rufen Sie Ihr GitHub-Repository auf.
  3. Klicken Sie auf Einstellungen.
  4. Klicken Sie unter „Code und Automatisierung“ auf Webhooks.
  5. Klicken Sie auf Add webhook (Webhook hinzufügen).

  6. Geben Sie Folgendes ein:

    1. Geben Sie unter Payload URL (Nutzlast-URL) die URL der Cloud Run-Funktion ein, die Sie zuvor bereitgestellt haben.

      Die URL sieht so aus: https://github-runner-autoscaler-PROJECTNUM.REGION.run.app, wobei PROJECTNUM die eindeutige numerische Kennung Ihres Projekts und REGION die Region ist, in der Sie den Dienst bereitgestellt haben.

    2. Wählen Sie für Inhaltstyp die Option application/json aus.

    3. Geben Sie für Secret den zuvor erstellten Wert WEBHOOK_SECRET ein.

    4. Wählen Sie für SSL-Überprüfung die Option SSL-Überprüfung aktivieren aus.

    5. Wählen Sie für „Welche Ereignisse sollen diesen Webhook auslösen?“ die Option Einzelne Ereignisse auswählen aus.

    6. Wählen Sie bei der Ereignisauswahl Workflow-Jobs aus. Heben Sie die Auswahl aller anderen Optionen auf.

    7. Klicken Sie auf Add webhook (Webhook hinzufügen).

Worker-Pool herunterskalieren

Der Webhook ist jetzt eingerichtet, sodass Sie keinen persistenten Worker im Pool benötigen. So wird auch sichergestellt, dass keine Worker ausgeführt werden, wenn keine Arbeit zu erledigen ist, wodurch Kosten gesenkt werden.

  • So passen Sie Ihren Pool für die Skalierung auf null an:

    gcloud beta run worker-pools update WORKER_POOL_NAME \
  --region WORKER_POOL_LOCATION \
  --scaling 0

Autoscaling-Runner verwenden

Um zu prüfen, ob Ihr Autoscaling-Runner ordnungsgemäß funktioniert, führen Sie eine Aktion aus, die Sie zuvor für runs-on: self-hosted konfiguriert haben.

Sie können den Fortschritt Ihrer GitHub-Aktionen auf dem Tab „Actions“ Ihres Repositorys verfolgen.

Sie können die Ausführung Ihrer Webhook-Funktion und Ihres Worker-Pools prüfen, indem Sie den Tab „Logs“ der Cloud Run-Funktion bzw. des Cloud Run-Worker-Pools aufrufen.

Bereinigen

Damit Ihrem Google Cloud -Konto keine zusätzlichen Kosten in Rechnung gestellt werden, löschen Sie alle Ressourcen, die Sie mit dieser Anleitung bereitgestellt haben.

Projekt löschen

Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen, löschen Sie die für die Anleitung erstellten Ressourcen.

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Anleitungsressourcen löschen

  1. Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben. Für Cloud Run-Dienste fallen erst Kosten an, wenn sie Anfragen empfangen.

    Führen Sie den folgenden Befehl aus, um Ihren Cloud Run-Dienst zu löschen:

    gcloud run services delete SERVICE-NAME

    Ersetzen Sie SERVICE-NAME durch den Namen Ihres Dienstes.

    Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.

  2. Entfernen Sie die Konfiguration der Standardregion gcloud, die Sie während der Einrichtung für die Anleitung hinzugefügt haben:

     gcloud config unset run/region

  3. Entfernen Sie die Projektkonfiguration:

     gcloud config unset project

  4. Löschen Sie andere Google Cloud Ressourcen, die in dieser Anleitung erstellt wurden:

Nächste Schritte