Diese Seite wurde von der Cloud Translation API übersetzt.

GitHub-Runner mit Cloud Run-Worker-Pools hosten

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

Sie stellen einen Cloud Run-Worker-Pool bereit, um diese Arbeitslast zu verarbeiten, und optional eine Cloud Run-Funktion, um die Skalierung des Worker-Pools zu unterstützen.

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.

Codebeispiel abrufen

So rufen Sie das gewünschte Codebeispiel ab:

Klonen Sie das Beispiel-Repository auf Ihren lokalen Computer:

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

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. Es registriert sich mit einem Token, das Sie erstellen, 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 ein neuer Job in der Warteschlange ist, 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:

Legen Sie Ihre Projekt-ID in gcloud fest:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.
So erstellen Sie ein neues Dienstkonto für Identity and Access Management:
```
gcloud iam service-accounts create gh-runners
```

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:

Melden Sie sich in Ihrem GitHub-Konto an.
Rufen Sie auf GitHub die Seite Settings > Developer Settings > Personal Access Tokens (Einstellungen > Entwicklereinstellungen > Persönliche Zugriffstokens) auf.
Klicken Sie auf Neues Token erstellen und wählen Sie Neues Token erstellen (klassisch) aus.
Erstellen Sie ein neues Token mit dem Bereich „repo“.
Klicken Sie auf Generate token (Token generieren).
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.

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.

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

Rufen Sie den Beispielcode für den Worker-Pool auf:
```
cd worker-pool-container
```
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 wird 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 geheimen Wert für den Webhook:

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.

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:

Rufen Sie den Beispielcode für den Webhook auf:
```
cd ../autoscaler
```

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.

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

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:

Melden Sie sich in Ihrem GitHub-Konto an.
Rufen Sie Ihr GitHub-Repository auf.
Klicken Sie auf Einstellungen.
Klicken Sie unter „Code und Automatisierung“ auf Webhooks.
Klicken Sie auf Add webhook (Webhook hinzufügen).
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“ (Aktionen) 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.