Erstellen von agentenbasierten GitHub-Workflows

Informationen zum Erstellen von GitHub agentenbasierte Workflows

Sie können GitHub agentenbasierte Workflows mit einem Coding-Agenten (empfohlen) oder manuell erstellen. Ein Workflow ist eine Markdown-Datei in .github/workflows/, die YAML-Frontmatter für die Konfiguration und Anweisungen in natürlicher Sprache für den KI-Agenten enthält.

Um einen agentischen Workflow zu erstellen, definieren Sie den Workflow in Markdown, kompilieren ihn in eine .lock.yml Datei, übernehmen beide Dateien, und führen Sie ihn dann durch GitHub Actions Trigger oder die GitHub CLI.

Dieser Artikel konzentriert sich auf die wichtigsten Aufgaben: Erstellen, Aktualisieren und Wiederverwenden von Workflows. Für vollständige technische Details und zusätzliche Muster verwenden Sie die GitHub agentenbasierte Workflows Dokumentationswebsite.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

• Ein KI-Konto: GitHub Copilot, , Anthropic Claude, OpenAI Codexoder Google Gemini

• Ein GitHub Repository, in dem Sie Schreibzugriff haben

• GitHub Actions für das Repository aktiviert

• GitHub CLI (gh) v2.0.0 oder höher installiert und authentifiziert

  Führen Sie zum Überprüfen der Version gh --version aus. Führen Sie zum Authentifizieren Folgendes aus:

  gh auth login --scopes repo,workflow
  

• Die Erweiterung GitHub agentenbasierte Workflows für das installierte GitHub CLI:

  gh extension install github/gh-aw
  

  Wenn Sie GitHub CLI Version 2.90.0 oder höher verwenden, werden Sie beim Ausführen eines beliebigen gh aw Befehls automatisch aufgefordert, die Erweiterung zu installieren, falls sie noch nicht installiert ist.

Authentication

Sie können die Authentifizierung mit Ihrem ausgewählten KI-Modul (Codierungs-Agent) auf zwei Arten einrichten:

• Verwenden der integrierten GITHUB_TOKEN für die Abrechnung der Organisation (empfohlen). Diese Option ist eigens für die GitHub Copilot Engine vorgesehen und kann nur von Repositorien verwendet werden, die einer Organisation mit einem GitHub Copilot-Plan gehören.
• Verwenden eines personal access token oder API-Schlüssels für persönliche Repositories und KI-Engines von Drittanbietern.

Verwenden der integrierten GITHUB_TOKEN

Wenn Sie GitHub Copilot in einem organisationseigenen Repository verwenden, können Sie das integrierte GITHUB_TOKEN von GitHub Actions anstelle eines personal access token verwenden. Dadurch wird die Nutzung des Workflows Ihrer Organisation direkt in Rechnung gestellt, und es ist nicht mehr nötig, einen personal access token geheimen Schlüssel für Copilot-Anfragen zu verwalten. So richten Sie dies ein:

1. Ihr Organisationsadministrator sollte in den Copilot-Einstellungen die Richtlinie „Nutzung von Copilot CLI zulassen, die der Organisation in Rechnung gestellt wird“ aktivieren, falls sie dort nicht bereits aktiviert ist.
2. Für Workflows, die Sie einer Organisation berechnen möchten, fügen Sie copilot-requests: write in den Frontmatter des Workflows permissions ein.

Aktivieren der Organisationsabrechnung

"Zulassen der Verwendung von Copilot CLI, die der Organisation in Rechnung gestellt wird" muss in GitHub Copilot Richtlinieneinstellungen aktiviert sein. Wenn die Richtlinie "Copilot CLI" bereits aktiviert ist, ist die Abrechnungsrichtlinie standardmäßig aktiviert.

1. Klicke in der rechten oberen Ecke von GitHub auf dein Profilbild und dann auf Your organizations.

2. Wählen Sie eine Organisation aus, indem Sie darauf klicken.

3. Klicke unter dem Organisationsnamen auf Settings. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.

   

4. Klicken Sie in der Randleiste auf Copilot"Richtlinien", und klicken Sie dann auf "Richtlinien".

5. Aktivieren Sie "Copilot CLI", und aktivieren Sie dann "Verwendung von Copilot CLI zulassen, die der Organisation in Rechnung gestellt wird.".

Abrechnung eines Workflows an eine Organisation

Beim Erstellen eines Workflows müssen Sie copilot-requests: write unter permissions im Workflow-Frontmatter angeben. Wenn diese Berechtigung festgelegt ist, wird das Token GitHub Actions für Copilot Anforderungen verwendet, und COPILOT_GITHUB_TOKEN wird für diese Anforderungen ignoriert. Wenn das Token GitHub Actions nicht über GitHub Copilot Zugriff aus der Organisation verfügt, schlägt der Workflow fehl, wenn er Copilot Anforderungen sendet, und Sie sollten stattdessen COPILOT_GITHUB_TOKEN konfigurieren.

permissions:
  contents: read
  copilot-requests: write

Verwendung eines personal access token oder API-Schlüssels

Für persönliche Repositorys oder KI-Engines von Drittanbietern müssen Sie ein Repository-Geheimnis erstellen, das einen personal access token oder API-Schlüssel speichert. Für GitHub Copilot liegt das Geheimnis in COPILOT_GITHUB_TOKEN, das eine feinkörnige personal access token speichert.

Bei Verwendung gh aw add-wizardwerden Sie vom Setupfluss aufgefordert, diesen geheimen Schlüssel zu erstellen. Wenn Sie einen agentenbasierten Workflow über die GitHub-Weboberfläche oder manuell erstellen, müssen Sie das Secret zunächst selbst in den Secrets Ihres Repositorys GitHub Actions hinzufügen, entweder in der GitHub-Benutzeroberfläche oder in der CLI mit gh aw secrets set. Anweisungen finden Sie unter Authentifizierungsreferenz.

Erstellen eines Workflows

Die empfohlene Methode zum Erstellen agentische Workflows besteht darin, einen CLI-Codierungs-Agent oder VS-Code zu verwenden. Dadurch erhalten Sie einen geführten Ablauf, um den Workflow zu erstellen, zu kompilieren und zu committen.

Verwenden eines CLI-Codierungs-Agents oder VS-Codes

1. Verwenden Sie die GitHub CLIGitHub agentenbasierte Workflows-Erweiterung (gh aw), um das Repository für die agentenbasierte Inhaltserstellung zu initialisieren (empfohlen bei der ersten Einrichtung in einem Repository):

   gh aw init
   

   Dadurch werden Fähigkeiten, Anweisungen und ein benutzerdefinierter Agent für die Erstellung agentischer Workflows hinzugefügt, sodass Coding-Agents Workflows effektiver erstellen und bearbeiten können.

2. Starten Sie Ihren Coding-Agent im Kontext Ihres Repositorys (zum Beispiel Copilot CLI oder im VS Code-Agent-Modus).

3. Geben Sie eine Eingabeaufforderung ein, die die agentic-workflows Fähigkeit erwähnt und Ihren gewünschten Workflow beschreibt:

   Copilot prompt

   /agentic-workflows Create a new workflow that creates a daily report on
   recent activity in the repository, delivered as
   an issue.
   

4. Der Agent erstellt den Workflow und kompiliert den Workflow mithilfe der GitHub CLI.

5. Überprüfen Sie den Workflow, und bitten Sie den Agent, die Dateien zu übernehmen und zu pushen.

6. Starten Sie den Workflow über die GitHub Actions Registerkarte oder mit GitHub CLI ausführen:

   gh aw run YOUR-WORKFLOW-NAME
   

Andere Erstellungsmethoden

Sie können auch agentische Workflows erstellen:

• In der GitHub Weboberfläche. Weitere Informationen finden Sie unter Creating workflows in the GitHub web interface.
• Manuell. Sehen Sie sich das Erstellen von Workflows durch manuelle Bearbeitung an.

Referenz zur Workflow-Struktur

Jede Workflowmarkdowndatei weist zwei Teile auf:

Abschnitt	Purpose
YAML-Frontmatter	Definiert Trigger (on), Berechtigungen, sichere Ausgaben und das KI-Modul.
Markdown-Inhalt	Anweisungen in natürlicher Sprache, denen der KI-Agent bei der Ausführung des Workflows folgt.

Wichtige Frontmatter-Felder:

Feld	Description
on	Der Ereignisauslöser (gleiche Syntax wie bei GitHub Actions-Triggern).
permissions	Dem Agenten gewährte Repository-Berechtigungen. Wird standardmäßig auf read-all festgelegt.
safe-outputs	Schreiboperationen, die der Agent ausführen darf (z. B. create-issue, add-comment, create-pull-request).
engine	Das zu verwendende KI-Modul (copilot ist der Standardwert; claude, codex, und gemini wird auch unterstützt).

Die vollständige Frontmatterreferenz finden Sie in der GitHub agentenbasierte Workflows Frontmatterdokumentation.

Beispiel für agentischen Workflow

Das folgende Beispiel ist ein vereinfachter wöchentlicher Aktivitätsbericht zu Issues für ein Repository.

---
on: weekly on monday

permissions:
  issues: read
  copilot-requests: write

network: defaults

tools:
  github:
    toolsets: [issues]

safe-outputs:
  create-issue:

---

# Weekly issue activity report

Review issue activity from the last 7 days in this repository.

Create a GitHub issue that includes:

- Total issues opened and closed this week.
- The top recurring themes from issue titles and descriptions.
- A short list of notable issues that still need attention.
- Two or three actionable recommendations for maintainers.

Keep the report concise and action-oriented.

Aktualisieren eines Workflows

So aktualisieren Sie einen vorhandenen Workflow:

1. Bearbeiten Sie die Workflow-Markdown-Datei in .github/workflows/.

2. Neu kompilieren, um die Sperrdatei zu aktualisieren:

   gh aw compile
   

3. Committen und pushen Sie beide aktualisierten Dateien.

4. Öffnen Sie einen Pull Request, und überprüfen Sie die GitHub Actions Prüfungen.

Ausführliche Anleitungen zur Bearbeitung finden Sie unter "Workflows bearbeiten".

Erneutes Verwenden von Workflows

Sie können Workflows auch aus externen Repositorys importieren, auf die Sie zugreifen können. Zum Beispiel können Sie einen Workflow aus githubnext/agentics hinzufügen:

gh aw add-wizard githubnext/agentics/daily-repo-status

Für eine nicht interaktive Einrichtung können Sie gh aw add verwenden und optional eine Version festlegen.

Wenn Sie einen Workflow importieren, speichert GitHub CLI einen source:-Wert im Frontmatter, damit Sie ihn später mit gh aw update aus Upstream aktualisieren können.

Importieren Sie Workflows nur aus Quellen, die Sie vertrauen, und überprüfen Sie, was ein Workflow vor dem Hinzufügen zu Ihrem Repository tut. Markierte private: true Workflows können nicht in andere Repositorys importiert werden.

Wenn Sie einen importierten Workflow aktualisieren, versucht GitHub CLI, lokale Änderungen beizubehalten. Wenn es zu Konflikten beim Zusammenführen kommt, beheben Sie sie und führen Sie gh aw compile erneut aus.

Weitere Informationen finden Sie unter "Erneutes Verwenden von Workflows".

Nächste Schritte

• Workflowbeispiele, erweiterte Muster, Leitfäden und Informationen zur Problembehandlung finden Sie auf der DokumentationswebsiteGitHub agentenbasierte Workflows.