GitHub sync

github_sync is the singleton workflow that turns GitHub activity into work. It polls — there are no webhooks — and runs every github_sync_minutes (default 5). Force a run from the TUI (s) or POST /api/tasks/sync.

Steps

Step	Action
check_auth	Verify gh auth and that github_repo is set
fetch_issues	List issues matching the pickup labels
process_issues	Retry pending needs_human writes, then start task_lifecycle for eligible issues
review_external_prs	Review open PRs the agent did not open
record_sync	Persist the sync timestamp

Issue pickup

Pickup is label-driven:

• pickup_labels (config, comma-separated) selects issues. Empty means all issues are eligible.
• The default label is steelframe:work-on-this.
• steelframe:needs_human blocks re-pickup. An issue carrying it is skipped, including after the agent parks it. If the park’s label write failed (for example, GitHub was unreachable when the run ended), the write is retried at the start of every sync and the entity is held out of pickup until the label lands.

When an issue is picked up, the agent clears pickup labels on merge and starts a task_lifecycle run.

Capacity is checked before pickup and fails closed: if the alive-worker count or the active-run lookup cannot be read, the agent skips pickup this cycle and retries on the next sync rather than risking an over-spawn. When no worker slot is free, pickup is skipped without an error.

External PR review

github_sync also lists open pull requests. It reviews PRs the agent did not author:

• PRs on Steelframe feature branches (sf/<issue>-<slug>) are skipped.
• PRs authored by the installed GitHub App bot are skipped.
• Drafts are ignored.
• Everyone else — humans, dependabot, renovate, other bots — gets a review from the configured coding runtime.

A review is posted once per head SHA, pinned to that commit via the reviews API commit_id, and marked with <!-- steelframe-pr-review sha:… checkout:head --> in the body. If HEAD moves while the runtime is still writing, the submit is skipped so the next sync reviews the live SHA instead of attaching an old write-up to the new commit. A new push is reviewed again on the next sync.

At most 3 PRs are reviewed per sync cycle so a PR flood cannot stall issue pickup.

Self-heal

self_heal is a separate singleton that turns agent failures, red default-branch Actions, and code-health findings into issues carrying your pickup_labels. It only runs when delivery_profile=source and self_heal_minutes > 0 (default 30). Dedup is by fingerprint marker in the issue body, and it files at most self_heal_max_issues (default 3) per cycle. See Workflows.

Configuration

Key	Default	Meaning
github_repo	—	org/repo the agent manages
pickup_labels	steelframe:work-on-this	Comma-separated labels; empty = all issues
github_sync_minutes	5	Sync interval; 0 disables
self_heal_minutes	30	Self-heal cadence on source profile; 0 disables
self_heal_max_issues	3	Max new self-heal issues per cycle

Production GitHub operations should use a dedicated GitHub App so commits and PRs are attributed to a bot identity. Without an App the agent falls back to ambient gh auth, which is fine for local development but not for production — worker sandboxes have no ambient auth, so their pushes fail. See GitHub App setup.

Caution

Do not grant the GitHub App the Workflows permission. An agent with it could inject a pull_request_target job that runs PR code with repo secrets. Land workflow files from a human token with the workflow OAuth scope instead.

Gotchas

• Sync polls; expect up to one interval of latency between a label and pickup. Force it with POST /api/tasks/sync.
• Reviews are budgeted: more than three external PRs wait for later cycles.
• Pickup respects max_workers; labeled issues can sit in Queued until a slot frees.
• github_sync never reviews its own sf/ heads, so Steelframe’s harness and delivery PRs are yours to merge.