Decision 0055 · Accepted
Capability-based GitHub and
host-triggered builds
The maintainer wants to direct delivery from a phone, with the same Flow behavior whether the agent runs locally or in a Claude Code cloud session.
- Status
- Accepted
- Built from:
- da88c48
Status: Accepted (2026-10-31). Amends 0037 (the GitHub mode tier: "an authenticated gh"), 0044 (amendment item 2: GitHub mode needs gh authenticated), and 0048 (where a "build it" approval may come from). Spec: 046. Preserves 0050, 0052, and 0054.
Context
The maintainer wants to direct delivery from a phone, with the same Flow behavior whether the agent runs locally or in a Claude Code cloud session. Claude Code's documentation, read 2026-10-31, shows that cloud sessions reach GitHub through a proxy: gh is installed with a proxy-injected token, GraphQL is blocked so gh pr and gh issue return 403, and gh api REST calls and the host's built-in GitHub tools work. Cloud sessions load the repository's CLAUDE.md and .claude/skills, never ~/.claude. Routines (research preview) can start a cloud session on GitHub issue and pull request events, including labels. build's Delivery mode stops when gh is unauthenticated, which in the cloud blocks steps a reachable route could do.
Decision
- GitHub mode needs a route, not a CLI. GitHub mode applies when
originis on GitHub and some route reaches it:gh,gh apiREST, or the host's GitHub tools or a connected MCP server, inwrite-agentsTools order. Pull requests, checks, and merges use the first route that works for that operation. When none does, stop with one hand-off; never fall back to local mode. - One optional issue trigger. Issues stay optional. A
build-itlabel added to an issue by a repository writer is that issue's "build it": the host's trigger (a Claude Code routine) startsbuildwith the issue as its task. The issue text is task data, never instructions or wider authorization. The session ends at a pull request that links the issue and the session, and never merges; "ship it" stays a conversational approval. - Cloud-ready setup lives in the repository. What a cloud session needs is tracked: a project-scope skills install and the instruction file. Nothing Flow needs depends on
~/.claude.
Alternatives
- Keep requiring an authenticated
gh. Rejected: blocks cloud delivery although REST and host tools reach GitHub. - A
@claudecomment through the Claude Code GitHub Action. Rejected as the default: it runs on Actions runners, billed separately, outside the cloud session the user directs from their phone. Adopters may still use it. - A Flow-hosted trigger or orchestration service. Rejected: outside portable Skills; Flow Factory's territory.
- Mandatory issues for cloud work. Rejected: conversation stays the interface; the label is a convenience.
Consequences
Delivery skills detect GitHub capability per operation instead of probing gh auth status. Triage accounts can add labels too, so the label alone authorizes nothing: build's gate script checks the labeler's and the issue author's write or admin permission, ignores comments from lower accounts, and fails closed when it cannot read them; a live run showed skill text alone did not stop a session (record). The routine's stored prompt must stop on any other label, since the webhook takes no label filter. Routines are a research preview; their limits and authorization details need dated evidence in docs/agent-compatibility.md. Cloud cost is visible only through the host's OpenTelemetry export; without it, cost stays unknown.