github
v0.5.0GitHub CLI and event-driven PR monitoring — typed queries and mutations, authenticated temporary webhooks, CI/comment/review notifications, and cleanup on merge.
Install
iii trigger compose::add worker=github@0.5.0Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
- default_timeout_ms: 30000
gh_executable:
max_output_bytes: 1048576
max_timeout_ms: 120000
webhooks:
enabled: false
max_body_bytes: 1048576
max_pending: 10000
max_watch_days: 30
notifications:
ignore_self: true
max_comment_chars: 2000
max_items: 30
max_wait_ms: 120000
profile: agent_actionable
quiet_ms: 15000
orphan_grace_minutes: 60
queue: github-webhooks
storage_path: ./data/github-webhooks/store.sqlite3
tunnel_id: webhooksMonitoramento durável de PR (opt-in)
Além das APIs CLI existentes, github::pr::watch, github::pr::unwatch,
github::pr::watch-status, github::pr::recover e a função observável
github::pr::on-event implementam monitoramento por webhooks. O recurso fica desabilitado por padrão;
consulte o guia de webhooks para
conhecer as permissões, a recuperação e as limitações. Nenhum recurso externo é
criado ao registrar a interface com a configuração padrão.
Antes de habilitá-lo, abra GitHub → Webhooks no Console ou chame
github::setup::webhooks-status. A lista verifica se o worker opcional
quick-tunnel está instalado, se o cloudflared está disponível e se o
listener restrito do http foi realmente aberto. O Console só instala
quick-tunnel depois da confirmação do operador; ele nunca instala
cloudflared e, quando necessário, mostra o
guia oficial de instalação.
Use github::setup::enable-http-listener e
github::setup::enable-webhooks para as alterações guiadas. Ativar os webhooks
exige todos os itens confirmados e requer reiniciar o worker github para
abrir o armazenamento. github::pr::watch recusa apenas pré-requisitos
sabidamente ausentes ou bloqueados; uma verificação temporariamente
unknown não gera um falso bloqueio.
github
GitHub as iii functions, powered by the GitHub CLI. Typed github::*
functions cover pull requests, issues, repos, Actions runs and workflows,
releases, and search; github::exec runs any other gh command and
github::api reaches any GitHub REST endpoint. Agents get
schema-discoverable GitHub operations with read-vs-mutate permission gating
instead of raw shell.
Install
iii call compose::add worker=githubiii call compose::add resolves the worker and its dependencies, writes
exact declarations to worker-compose.yaml, and reconciles the Compose project.
The worker shells out to the GitHub CLI — install
a current gh (the typed field sets are validated against gh 2.94) and give
it credentials: either gh auth login on the host, or set GH_TOKEN for
the worker (see Configuration).
Quickstart
use iii_sdk::{register_worker, CallRequest, InitOptions};
use serde_json::json;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
// Open PRs in a repo, typed and parsed:
let prs = iii
.call(CallRequest {
function_id: "github::pr::list".into(),
payload: json!({ "repo": "cli/cli", "state": "open", "limit": 5 }),
action: None,
timeout_ms: Some(60_000),
})
.await?;
println!("{prs:#?}"); // { value: [{ number, title, state, url, … }] }
// Anything else gh can do, verbatim:
let version = iii
.call(CallRequest {
function_id: "github::exec".into(),
payload: json!({ "args": ["--version"] }),
action: None,
timeout_ms: Some(60_000),
})
.await?;
println!("{version:#?}"); // { stdout, stderr, exit_code, … }
Ok(())
}Observable functions
| Function | Args | Delivery | Event |
|---|---|---|---|
github::on-called |
none; filter on input.function_id, input.repo, input.ok |
iii delivers each call to every observer whose filters match, fire-and-forget | { function_id, args_summary, repo, ok, duration_ms, result_summary, kind, result_preview, timestamp } |
github::pr::on-event |
{ notifications?, watch_id?, repo?, number?, categories? } |
Custom: each notification goes to the one observer it is for, and its target's result acks it | the full event (PrEvent), or a compact event or digest per the observer's notification policy |
Both functions are private: only this worker calls them, and any worker may observe them. Each handler returns the event it is called with.
github::on-called. The worker calls it after every github::* function
runs, only while something observes it. The event carries the call that ran
and a short, bounded result summary; the console's GitHub page observes it for
its activity feed and live git graph.
iii.observe(
{ function_id: 'github::on-called', filters: { 'input.ok': { $eq: false } }, deliver: 'output' },
'alerts::github-failure',
)github::pr::on-event. Durable PR lifecycle, comment, review and CI
notifications for the watches started with github::pr::watch. Observe it
before calling github::pr::watch, then read github::pr::watch-status once.
An observer's args select what it receives:
watch_id,repo(case-insensitive),number: the watches it listens to; omitted fields match every watch.categories: any ofci,comments,reviews,pr; omitted means all.notifications: its notification policy (profile: all | agent_actionable | review_assistant,success_checks,ignored_actors,quiet_ms,max_wait_ms,max_items, …); omitted inheritswebhooks.notifications.
The worker persists each observer as a subscriber when it is added, and the
watches it listens to stay alive while it exists (see
Watch lifetime). Delivery is durable and at-least-once:
each notification is a job in the worker's SQLite outbox, called as one call
of github::pr::on-event with that observer's payload (profile: all gets
the full event, the other profiles a compact event or a digest). The target
receives the payload itself, and the observer's deliver choice does not
apply. A target that returns acks the notification; an error or a timeout
(8 s) keeps the job and retries it. A notification the observer's filters
reject is acked without a call. Targets dedupe on event_id.
use iii_sdk::{ObserverOptions, Source};
use serde_json::json;
iii.observe_with(
Source::function("github::pr::on-event").args(json!({
"watch_id": "pr-1234",
"notifications": { "profile": "agent_actionable" },
})),
"agent::on-pr-event",
ObserverOptions::default().metadata(json!({ "session_id": "s-1" })),
);An observer is rejected with INVALID_ARGS when its repo or notification
policy is invalid, and with STORAGE_FAILURE when the webhook store cannot
persist it.
The worker observes, for its own plumbing:
| Function | Args or filters | Target |
|---|---|---|
configuration::on-updated |
filters input.id = this worker's entry, input.event_type = configuration:updated |
github::on-config-change |
http::on-request |
args { method: POST, path: /webhooks/github/:endpoint_id, public_webhook: true } |
github::webhooks::receive |
queue::on-message |
args { topic: webhooks.queue, group: github-webhooks, max_retries: 5, backoff_ms: 1000 }, observer id <worker name>:webhooks:<webhooks.queue> |
github::webhooks::process |
quick-tunnel::on-changed |
filter input.tunnel_id = webhooks.tunnel_id |
github::webhooks::tunnel-changed |
cron::on-tick |
args { expression: "*/10 * * * * *" } |
github::webhooks::maintain |
The four webhook observers exist only when webhooks.enabled is true. Each
stays pending while its function's worker is not running.
The job queue is observed as the consumer group github-webhooks. The queue
worker keeps one durable queue for the group, so the jobs nobody has acked
wait there whichever process of the worker consumes them next. The observer
has a stable id: the worker name (github, or the III_WORKER_NAME its
supervisor sets), then :webhooks: and the queue, preceded by <namespace>/
when the worker has a namespace (github:webhooks:github-webhooks by default;
an id over 128 bytes keeps a SHA-256 digest of it). When the worker stops,
killed or not, the engine keeps its observers suspended for its grace period
(observers.observer_grace_ms, 30 s by default) and withdraws them from the
queue and http workers, which frees the webhook route. A restarted worker,
under the same name and namespace, observes the queue under the same id: the
engine replaces the suspended observer with the new one at once, so the
consumer keeps one identity and the engine holds one observer for it. The
group's queue hands the new process every job the previous one left unacked,
once.
A refusal because another observer still holds the route
(HTTP_ROUTE_CONFLICT) or the queue observer's id (OBSERVER_ID_CONFLICT:
the engine has not seen the previous process's connection close yet, or
another worker holds the id until its grace period ends) is recorded in the
webhook health's last_error; the worker observes again after 1 s, then twice
as long each time up to 30 s, and clears the error once the observer is
active.
Configuration
gh_executable: "" # path to gh; empty = `gh` on PATH
token: "${GH_TOKEN}" # env-expanded; empty = ambient `gh auth login`
default_timeout_ms: 30000 # per-call timeout when timeout_ms is omitted
max_timeout_ms: 120000 # upper clamp for any per-call timeout_ms
max_output_bytes: 1048576 # per-stream capture cap (flags *_truncated)Other keys (and their defaults) live in src/config.rs.