GitHub als Ausführungsraum für KI-Agenten: Runbook für Copilot Coding Agent und dedizierte macOS-Runner

Ein Jahrzehnt lang hat GitHub Code, Issues, Pull Requests, Actions und Berechtigungen zu einem Graphen für menschliche Zusammenarbeit verschmolzen. Menschen schrieben Code, eröffneten PRs, prüften PRs, und bei grüner CI wurde gemergt. 2025–2026 wechselt der handelnde Akteur: Das Repository entwickelt sich vom Code-Lager zur Ausführungs-Sandbox für Agenten.

Drei Produktebenen treiben den Wandel parallel. Copilot Coding Agent (Cloud-Agent) startet ausgelöst durch Issue-Zuweisung oder Chat-Prompt eine dedizierte VM in GitHub Actions, durchsucht das Repository per RAG, plant die Aufgabe und pusht Commits in einen Draft-PR. .github/agents/ erlaubt es Teams, mehrere spezialisierte Rollen zu deklarieren – etwa einen Performance-Agenten, einen Test-Agenten und einen Doku-Agenten. Agentic Workflows (gh-aw, Technical Preview) kompiliert natürlichsprachige Markdown-Dateien aus .github/workflows/ zu Actions-YAML und lässt Copilot, Claude oder Codex in einer Sandbox ereignisgesteuerte Daueraufgaben übernehmen.

Zusammen verschiebt sich die Produktsemantik von „Mensch schreibt Code → Repository speichert Code“ zu „Mensch schreibt Ziel → Agent führt im Repository aus → Mensch prüft Draft-PR → CI/CD löst Deployment aus“. Diesen Wandel zu verstehen ist wichtiger als die Wahl eines einzelnen Tools. Der dazugehörige Compute-Vertrag (Self-hosted Runner, dedizierte Apple-Silicon-Knoten) wird zum neuen Fundament.

Viele Teams hängen Copilot Coding Agent oder Claude Code direkt an GitHub-hosted Runner. Kurzfristig wirkt das günstig. Langfristig tauchen vier Kosten auf:

• Minutenpool × lange Agentenjobs: Agentenaufgaben starten Compilation, Tests und Security-Scans mehrfach neu. Einzelne Jobs laufen häufig länger als 30 Minuten. Minutengenaue Abrechnung plus Nachbarrauschen erzeugen ein nichtlineares Monatsbudget, das frühere CI-Kostenmodelle sprengt.
• Exposition von Signierungsmaterial: Auf einem geteilten Runner werden Secrets in die Agent-Umgebung injiziert. Bei Prompt Injection oder bösartigen Abhängigkeiten bekommen Signaturzertifikate und Provisioning-Profile reale Exfiltrationswege. SafeOutputs MCP Gateway, Agent Workflow Firewall (AWF) und Threat-Detection-Job trennen die Schreibrechte des Agenten physisch von der Ausführungsumgebung.
• Unvorhersehbare Review-Last: Ein Agent kann über Nacht dutzende Draft-PRs öffnen. Ohne AGENTS.md und Custom-Agent-Leitplanken ertrinken Reviewer. GitHub verlangt deshalb bewusst eine menschliche Freigabe an Draft-PRs, bevor CI/CD startet – ein „Human-in-the-Loop“-Schalter ab Werk.
• Unterbewertetes Apple Silicon: iOS- und macOS-Projekte lassen den Agenten Xcode, Simulator und TestFlight-Uploads bedienen. DerivedData, Signing-Keychain und gepinnte Xcode-Versionen sind Pflicht. Auf generischen gehosteten macOS-Runnern bleibt das langsam und teuer. Ein dedizierter Knoten ist günstiger und auditierbar.

In ein Review getragen, schreibt sich das Fazit selbst: Ein Agenten-Ausführungsraum braucht dedizierte Rechenleistung plus expliziten Sicherheitsvertrag, nicht den nächstbesten generischen Runner.

Die folgende Tabelle ordnet drei Begriffe, die im Alltag oft verwechselt werden, damit ein Team den richtigen Einstieg wählen kann:

Die Ebenen schließen einander nicht aus. Reife Teams setzen Copilot Coding Agent als Standard-Einstieg zum „Code schreiben“, nutzen .github/agents/ zur Eingrenzung von Rollen (Test-Agent, Performance-Agent, Doku-Agent) und ergänzen Agentic Workflows für ereignisgesteuerte Daueraufgaben (rote CI analysieren, jedes neue Issue triagieren). So entsteht aus GitHub eine saubere Ausführungs-Ebene „Ereignis → Agent → kontrollierter Schreibvorgang“.

Bei jedem Konzept, das einen Agenten direkt am Repository arbeiten lässt, zählt der Sicherheitsvertrag mehr als die Modellwahl. GitHub Agentic Workflows macht diese Schicht explizit, und das Muster eignet sich für jede selbst gehostete Pipeline:

• SafeOutputs MCP Gateway: Der Agent ruft die GitHub-API nicht direkt auf. Er deklariert beabsichtigte Schreibvorgänge gegenüber dem Gateway, das sie als Artefakt puffert. Nach dem Agentenlauf validiert, sanitisiert und limitiert ein separater Job mit Schreibrechten jeden Aufruf. Der Agentenprozess bleibt stets nur-lesend und ohne Secrets.
• Agent Workflow Firewall (AWF): Der Agent läuft in einem isolierten Container; Traffic wird per iptables über einen Squid-Proxy geleitet, eine Domain-Allowlist verhindert Datenabfluss und externe Command-and-Control-Kanäle.
• Threat-Detection-Job: Bevor ein Patch angewendet wird, scannt ein sicherheitsfokussierter Agent das Diff auf Prompt-Injection, geleakte Credentials und auffällige Codemuster. Verdächtiges Material lässt den Workflow fehlschlagen.
• Branch Protection und menschliche Freigabe: Der Copilot Coding Agent pusht ausschließlich auf von ihm angelegte Branches. Draft-PRs benötigen eine menschliche Freigabe, bevor CI/CD läuft. Der Mensch bleibt das Sicherheitsventil vor jedem Deployment.

Die 2025 von OpenAI, Cursor, Jules, Amp und Factory gemeinsam entworfene AGENTS.md-Spezifikation ist die menschliche Seite des Workspace-Vertrags. Ein „README für Agenten“ im Repo-Root liefert Coding-Agenten eine vorhersehbare Stelle für Projektstruktur, Build-Befehle, Test-Befehle, Stilregeln und Sicherheitshinweise.

• Hierarchische Auflösung: Unterverzeichnisse dürfen eigene AGENTS.md tragen; der Agent nimmt die nächstgelegene zur geänderten Datei. Das Hauptrepository von OpenAI führt aktuell 88 Stück.
• Must-follow versus Should: Harte Regeln („kein Commit auf main“, „Xcode 16.2 fixieren“) stehen neben weichen Präferenzen („Swift Testing bevorzugen“). Das Agentenverhalten konvergiert.
• Ergänzung zu README: README adressiert Menschen und externe Beitragende. AGENTS.md adressiert Agenten und nimmt Build-Schritte, Long-Context-Regeln und Sicherheits-Gotchas auf, die sonst den menschlichen Text überfrachten.
• Kompatibel mit Copilot CLI: Der Copilot CLI Agent in JetBrains und VS Code unterstützt bereits globales ~/.copilot/agents/.agent.md, sodass persönliche Präferenzen auf Team-Regeln aufsetzen.

In iOS- und macOS-Projekten gehören in AGENTS.md die Xcode-Fixierungsbefehle, der xcodebuild-Einstieg, Signing-Vorbereitungen, Gates wie -strict-concurrency=complete, die Labels des dedizierten Runners und die Tabu-Verzeichnisse. Je expliziter die Regeln, desto weniger improvisiert der Agent. Das spiegelt die Checkliste „Baseline einfrieren, SSH-Baseline, Cache-Partitionierung, Signing-Isolation“ aus dem bestehenden Runbook für den NUKCLOUD-Apple-Silicon-Knoten wider; AGENTS.md ist seine agentenfreundliche Form.

Die folgenden Werte stammen aus typischen iOS-/macOS-CI- plus Agentenrollouts. Sie dienen als Anker, gemessen wird im eigenen Haus:

• Walltime einzelner Agentenjobs: „Bug fix plus Tests“ liegt mit Copilot Coding Agent meist bei 8–25 Minuten, „Modul-Refactoring plus Full Build“ bei 30–90 Minuten. Geteilte Minutenpools warten in Release-Spitzen weiterhin bei P95 von 15–45 Minuten in der Queue.
• Draft-PR-Frequenz: Mittelgroße Teams sehen nach Einführung des Copilot Coding Agent eine tägliche Draft-PR-Zahl, die um den Faktor 2 bis 5 steigt. Der Engpass verlagert sich vom „Schreiben“ zum „Reviewen“. AGENTS.md und .github/agents sind die Hebel, die das zurückbringen.
• SafeOutputs-Nutzen: Mit aktiviertem SafeOutputs und AWF hält der Agentenprozess weder GITHUB_TOKEN noch Secrets oder MCP-API-Keys. Die interne Ablehnungsrate des Threat-Detection-Jobs liegt während des Previews bei rund 0,5 bis 2 Prozent, meist false positives bei prompt-injection-artigem Inhalt.
• Vorteil dediziertes Apple Silicon: Werden auf einem NUKCLOUD-Dediziert-Knoten --concurrent-jobs 2–4 für Agentenarbeit reserviert, schließt ein voller xcodebuild-Job meist 25–40 Prozent schneller ab als auf einem generischen macOS-Runner. Mit DerivedData-Cache-Treffern kommen weitere 30–60 Prozent hinzu.
• Reviewer-Last: Der Agent führt vor Eröffnung des Draft-PRs ein Self-Code-Review durch, was den ersten menschlichen Review-Durchgang verkürzt. Im Gegenzug fokussieren Reviewer stärker auf Designabsicht und Systemgrenzen statt auf Syntax.

Ein minimal lauffähiges Runbook in Kombination mit einem dedizierten Apple-Silicon-Runner. Schritt für Schritt einführen, nicht am Tag eins die perfekte Endausbaustufe erzwingen.

1. 01
   Eine AGENTS.md schreiben: Datei im Root mit Must-follow (Xcode-Version, Build-Befehle, Tabu-Verzeichnisse, Branch Protection) und Should (Stil, Commit-Format). Wo nötig in Unterverzeichnissen ergänzen. Codex, Cursor und Copilot CLI parsen alle.
2. 02
   .github/agents/ deklarieren: Mindestens drei Rollen – Test-Agent (nur *Tests*, gesamte Test-Suite), Doku-Agent (nur .md und Changelog), Performance-Agent (erst Benchmark, dann Änderung). Tool-Calls und Pflichtschritte im Prompt einschränken.
3. 03
   Agentic Workflows (gh-aw) einführen: Issue-Triage, automatische CI-Failure-Fixes und Doku-Sweeps als Markdown. SafeOutputs aktiviert lassen, sodass der Agentenprozess nur-lesend bleibt und alle Schreibvorgänge eingeschränkte Jobs durchlaufen.
4. 04
   Dedizierten Apple-Silicon-Runner registrieren: Über die Bestellseite einen NUKCLOUD-Dediziert-Knoten buchen, als Self-hosted Runner eintragen und mit agent-macos, xcode-16, signing-isolated labeln. Die Signing-Keychain ausschließlich an Jobs mit Schreibrechten mounten.
5. 05
   Sicherheitsvertrag aufsetzen: Auf dem Knoten AWF mit Squid und iptables nachbilden. Secrets über OIDC und Cloud-KMS aus dem Runner herausziehen, sodass der Agent-Container sie nicht direkt liest. Draft-PRs erst nach menschlicher Freigabe in CI/CD freigeben.
6. 06
   Review-Loop und KPIs: Wöchentlich „Draft-PR-Zahl, Review-Latenz, manuelle Ablehnungsquote, Threat-Detection-Trefferrate“ auswerten. AGENTS.md und Custom-Agent-Prompts entsprechend nachschärfen. Den Rollout an das gestufte, rollback-fähige Tempo aus dem Runbook für Swift-6-Strikte-Concurrency-CI-Gates koppeln.

Diese Tabelle ist für das Review-Alignment gedacht. Konkrete Zahlen tragen Finanzen und Netzwerk-Team in der hauseigenen Fassung nach.

Der Punkt ist nicht „was ist billiger“, sondern „lässt sich der Agenten-Ausführungsraum schriftlich verteidigen?“. Ein dedizierter Knoten verankert SafeOutputs, AWF und menschliche Prüfdisziplin in realen Runner-Labels statt in Slogans.