EasyGithub

AI software development pipeline on GitHub: Issue → GitHub Actions → Agent Runner → Pi → PR.

When an Issue gets the ai label, a GitHub Actions job spins up a fresh machine, checks out the repository, runs an AI coding agent (Pi) on a dedicated branch, and opens a pull request.

本仓库是这套流水线的实现本体（hub）。要在你自己的仓库里让 AI 修 Issue， 见下方「在自己的仓库启用」；想给本仓库自己交 AI 任务，直接用文末/下方 ai 标签流程。

How it works (V0.1)

GitHub Issue #123 ──label: ai──▶ GitHub Actions (ubuntu, Node 24)
                                        │  npm i -g pi (pinned)
                                        ▼
                              Agent Runner (TypeScript)
                                        │  1. claim issue (ai-running)
                                        │  2. fetch issue → render TASK.md
                                        │  3. branch ai/issue-123
                                        ▼
                              Pi (deepseek-v4-flash, thinking=high, --mode json)
                                        │  analyze → edit → run checks → iterate
                                        │  (agent CLI installed on demand at runtime)
                                        ▼
                              commit → push → PR ("Fixes #123")
                                        │
                                        ▼
                              comment + labels (ai-pr / ai-failed / ai-done)

Roles (kept deliberately separated)

Piece	Responsibility
GitHub	Issues / branches / PRs / CI results
GitHub Actions	throwaway execution machine
Agent Runner	scheduling + git + PR orchestration
Pi	the only "thinking" part (can be swapped)

agent-runner/src/agents/types.ts defines CodingAgent; registry.ts currently registers pi, claude, and codex behind the same interface — the seam for swapping AI engines. Routing: issue label agent:<name> > repo variable AI_AGENT > rules in agent-runner/config/agents.json > default pi.

Requirements / costs

• GitHub Actions minutes (free tier or paid) — the job runs a full Pi session, typically several minutes.
• One provider API key stored as a repo secret: DEEPSEEK_API_KEY (DeepSeek V4; see below). Optional variables (all listed with defaults in docs/usage.md §6): AI_MODEL, AI_THINKING, AI_AGENT, AI_MAX_ATTEMPTS, AI_AUTOMERGE, AI_MAX_PRS_PER_DAY, AI_REVIEWER, AI_LOCALE.
• Zero-file targets (App mode) get their verification command from the hub, because the target has no variables of its own: agent-runner/config/repos.json (profile verify, committed and reviewable) → legacy config/verify.json → hub variable EASYGH_VERIFY_CMDS (JSON map). See docs/portability.md.

Model / provider

Pi has native DeepSeek support, so the key is a plain DeepSeek platform key — no Anthropic compatibility layer needed:

• default: deepseek-v4-flash + thinking high (cheap policy default)
• stronger: deepseek-v4-pro
• available via vars.AI_MODEL, or per-run via workflow env.

在本仓库试用（dogfood）

1. Make sure labels exist: bash scripts/create-labels.sh EasyIndie/EasyGithub
2. Open an Issue describing a bug or feature.
3. Add the ai label (optionally feature label / keyword to pick the template).
4. Watch .github/workflows/ai-agent.yml run; the bot comments progress and opens a PR.
5. Review and merge the PR (the branch/PR is auto-closed/replaced on re-run).

Retrying after a failure

Preferred: run the ai-decide workflow with action=retry (see docs/usage.md §5). It re-arms the issue, drops the old branch (and with it the old PR) and redoes the work on the latest base. Manually that is: remove ai-failed/ai-needs-input/ai-deferred, then add ai again.

PR CI

Every pull request (including AI pipeline PRs) runs npm run check via .github/workflows/ci.yml.

在自己的仓库启用（cross-repo reuse）

先选适合你的方式（按侵入性从低到高）：

• 组织内（EasyIndie）成员：GitHub App 已全组织安装 → 用 Mode 3（零文件）。
• 外部/个人仓库：仓库里不能只写注释就让 App 工作 → 用 Mode 2（推荐，1 个文件）或 Mode 1。 （也可以自建同名 GitHub App 后获得 Mode 3，见 docs/other-orgs.md。）

Mode 3 — GitHub App (zero-file; EasyIndie org only). A GitHub App (easygithub-ai, installed org-wide) lets the hub poll org Issues and write branches/PRs in any installed repo. Targets contain no workflow, no runner, no secret. Mark an Issue for AI by adding the ai label or putting easygh-ai anywhere in its title/body (title/body markers are only honoured from OWNER/MEMBER/ COLLABORATOR authors — the agent executes untrusted text, so outsiders cannot trigger it). Polling runs every 5 minutes (EasyGithub is public, so these runs are free/unmetered). Multiple organizations: set vars.EASYGH_ORGS to a comma-separated list — each org gets its own ghapp-scan matrix job and installation token (see docs/other-orgs.md). (.github/workflows/ghapp-scan.yml → agent-runner/src/dispatcher.ts); secrets live only in the hub.

Mode 2 — caller file (low-intrusion, works anywhere). One ~15-line workflow in the target calls the centralized reusable workflow + composite action in EasyGithub. Needs: admin on target (to let the installer set the DEEPSEEK_API_KEY secret + labels) and EasyGithub must be readable (public now, so any repo can use it).

Mode 1 — full copy (works anywhere). --copy overlays the whole pipeline (workflow + agent-runner/) into the target; fully self-contained, no dependency on EasyGithub.

bash scripts/install-to-repo.sh EasyIndie/<repo>    # mode 2 caller
bash scripts/install-to-repo.sh EasyIndie/<repo> --copy   # mode 1

快速上手

三种模式的命令、触发方式与验收步骤统一写在 docs/usage.md（使用手册），这里只保留模式选型：

你的情况	用哪个
就在 EasyIndie 组织内，目标仓库不想放文件	Mode 3（App，零文件）
任意仓库，允许放 1 个 workflow	Mode 2（caller，秒级触发）
任意仓库，要求完全自包含、不依赖本仓库	Mode 1（--copy，全复制）

Known platform limitation (verified): a reusable workflow invoked cross-repo cannot declare a permissions key (fails at queue time); write access comes from the caller job permissions + repo default=write. GitHub App installation tokens also cannot use the Search API or gh --paginate (dispatcher lists repos/issues directly).

Local dry run (no Actions minutes)

bash scripts/dev-run.sh EasyIndie/EasyGithub <issue-number> [model] [thinking]

Runs the exact same runner code locally (clone → branch → Pi → commit → push → PR).

Repository layout

.github/workflows/ai-agent.yml   # the pipeline
.github/workflows/ai-decide.yml  # human commands (retry/answer/cancel/waive/automerge)
.github/workflows/ai-watch.yml   # post-merge watchdog (incident + revert PR + circuit breaker)
.github/workflows/ai-retro.yml   # weekly retro issue
.github/CODEOWNERS               # which changes always need a human
agent-runner/                    # Agent Runner (TypeScript, zero runtime deps)
  config/repos.json              # per-repo profiles (see docs/portability.md)
  prompts/                       # task templates (en + zh-cn + strict example)
  src/main.ts                    # orchestration
  src/risk.ts                    # risk tiers + auto-merge predicate
  src/profile.ts                 # per-repo profile (verify/paths/agent/model/runsOn/locale)
  src/providers/                 # platform seam (github implemented)
  src/prompt.ts                  # template selection/rendering (locale + variants)
  src/git.ts, src/github.ts      # git + gh wrappers
  src/agents/{types,pi,registry}.ts
  test/                          # node:test suite (runs in CI)
eval/tasks/                      # frozen evaluation tasks (hidden tests)
docs/learnings.md                # curated context injected into TASK.md
scripts/                         # installer, dev-run, labels, branch protection, App manifest

Run npm run check before committing: it type-checks and runs the node:test suite (93 cases, including a workflow-env forwarding guard).

参考文档

• 使用手册：怎么提任务、怎么读结果、出问题怎么办 ← 从这里开始
• 端到端 AI 开发工作流（自动化边界 / 人机分工）
• 适配不同项目（仓库画像 / 自动探测 / 接入清单）
• 多 Agent 启用与模型配置
• 在其它组织中使用 EasyGithub

Status & roadmap

• V0.1 (done): single-repo, Pi/DeepSeek, Issue→PR. Verified on this repository (self-hosting).
• V0.2 (done): multi-agent seam. registry.ts registers pi, claude (Claude Code CLI) and codex (Codex CLI) behind the same CodingAgent interface. Agent selection precedence:
  1. issue label agent:<name> (per-issue), 2. repo variable AI_AGENT (forces all runs),
  2. rules in agent-runner/config/agents.json, 4. default pi. Activated with the same verification/retry loop. Pi is E2E-verified; claude/codex adapters need their CLIs + keys in the Actions environment (claude + ANTHROPIC_API_KEY/CLAUDE_MODEL, codex + OPENAI_API_KEY/CODEX_MODEL).
• V0.5 (done): portability — per-repo profiles (config/repos.json), verifyContainer, per-profile runsOn (self-hosted/macOS/Windows via ai-run.yml), platform provider seam (src/providers/, GitHub only for now), prompt locales/variants (AI_LOCALE, prompts/zh-cn, prompts/strict), and self-healing branches (rebase before push; ai-watch updates stale ai/issue-* PRs).
• V0.3/V0.4: PR-CI failure feedback for human PRs (ci.yml already runs npm run check on every PR); GitHub App webhooks, queue/task store, long-running server.

License

Business Source License 1.1 (BUSL-1.1) — see LICENSE.

• 源码公开可见；非生产用途、组织内部使用（含用本流水线开发你自己的项目）免费。
• 禁止将 EasyGithub 本身（或衍生版）作为托管/付费服务提供给第三方（AI Pipeline Service）——此类使用需取得商业授权。
• Change Date 2030-09-09；到期后自动转为 Apache License 2.0。
• 商业授权 / 合作咨询：在 Issues 留言或联系 EasyIndie 组织所有者。
• 贡献条款：目前未开放外部代码贡献（BUSL 下需先签署 CLA 才能合并外部 PR，以保证将来仍可调整协议/双许可）。欢迎以 Issue 形式反馈。