Skip to content

Architecture

Jump to bottom
GSD Planner edited this page May 26, 2026 · 1 revision

Architecture

System Overview

ci-autopilot is an autonomous CI repair agent built on GitHub Actions and a Python 3.12 stdlib agent. It detects GitHub Actions failures, queues them as GitHub Issues, and dispatches repair operations via Codex. The system runs on a self-hosted Windows runner and coordinates the full lifecycle from failure detection to a merged PR fix.

Data Flow

flowchart LR
    A["GitHub Actions\nfailure detected"] --> B["autopilot-failure-intake\n(intake workflow)"]
    B --> C["Issue queue\n(queued label)"]
    C --> D["agent/poll_once.py\n(Python 3.12)"]
    D --> E["Codex\n(repair dispatch)"]
    E --> F["PR / fix\ncommitted"]
    F --> G["CI passes\n(ci.yml)"]
    G --> H["Merge"]
Loading

Step-by-step:

  1. A workflow run (fixer.yml, runner-smoke-test.yml) fails
  2. autopilot-failure-intake.yml fires on workflow_run completed with failure conclusion
  3. The intake workflow creates a GitHub Issue labeled queued with failure context
  4. agent/poll_once.py runs on the self-hosted runner (triggered by fixer.yml)
  5. The agent polls /repos/{owner}/{repo}/issues?state=open&labels=queued
  6. For each queued issue, the agent dispatches a repair task to Codex
  7. Codex opens a PR with the fix
  8. ci.yml validates the PR (Python 3.12 syntax check on ubuntu-latest)
  9. On CI pass, the PR is eligible for merge

Components

GitHub Actions Workflows

Workflow Trigger Purpose
ci.yml push/PR to main Python 3.12 syntax check; provides CI badge
fixer.yml workflow_dispatch, repository_dispatch, daily 02:00 Main autopilot: runs agent on self-hosted runner
autopilot-failure-intake.yml workflow_run completed (failure) Captures failures as queued issues
autopilot-create-issue.yml workflow_run completed Creates issues via actions/github-script
runner-smoke-test.yml workflow_dispatch Validates self-hosted runner is operational
runner-health.yml workflow_dispatch Manual runner health check

Agent Runtime

agent/poll_once.py — Python 3.12 stdlib-only agent.

  • Uses only: json, os, subprocess, sys, urllib, typing
  • No external packages; requirements.txt is comment-only
  • Reads GITHUB_TOKEN / GH_TOKEN from environment
  • Falls back to gh CLI if no token in environment
  • Polls the issue queue and logs queued issues for repair dispatch
  • Reads target repo from GITHUB_REPOSITORY env var (default: Coding-Autopilot-System/ci-autopilot)

agent/__init__.py — Empty package marker.

Control Plane (GitHub Issues)

ci-autopilot uses GitHub Issues as a lightweight control plane:

Label Meaning
queued Issue is waiting to be processed by the agent
autofix Issue is eligible for automated remediation
in-progress Being processed by the runner
done Resolved or superseded
runner-offline Runner health alert (legacy — cron trigger removed)

Runner Infrastructure

  • Host: Windows machine (MyLocalPC) running as a GitHub Actions self-hosted runner service
  • Location: C:\actions-runner
  • Scope: Registered to Coding-Autopilot-System/ci-autopilot
  • CI jobs (ubuntu-latest): Run on GitHub-hosted ephemeral runners (not the self-hosted runner)

Design Goals

  • Deterministic execution on a dedicated host
  • Clear separation between orchestration (GitHub Actions) and execution (Python agent)
  • Safe automation — all fixes go through PRs; CI must pass; no direct merges
  • Audit trail — GitHub Actions logs are the primary source of truth
  • Minimal dependencies — stdlib-only agent; no pip install required in CI

Observability

  • CI badge: ci.yml on main branch — visible on README
  • GitHub Actions logs: Actions tab is the primary audit trail
  • Host logs: C:\src\ci-autopilot\logs (if agent logging is enabled)
  • Runner status: gh api repos/Coding-Autopilot-System/ci-autopilot/actions/runners

Related Documentation

Clone this wiki locally