# github

> GitHub CLI (gh) as an iii worker — typed github::pr/issue/repo/run/workflow/release/search functions, github::exec argv passthrough, and github::api for any GitHub REST endpoint.

| field | value |
|-------|-------|
| version | 0.3.8 |
| type | binary |
| license | Apache-2.0 |
| repo | https://github.com/iii-hq/workers |
| supported_targets | aarch64-apple-darwin, x86_64-pc-windows-msvc, aarch64-pc-windows-msvc, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, armv7-unknown-linux-gnueabihf |
| author | iii |

## installation

```sh
iii trigger compose::add worker=github@0.3.8
```

## configuration

```yaml
- default_timeout_ms: 30000
  gh_executable: 
  max_output_bytes: 1048576
  max_timeout_ms: 120000
```

## readme

# 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

```bash
iii trigger compose::add worker=github
```

`iii trigger 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](https://cli.github.com) — 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

```rust
use iii_sdk::{register_worker, InitOptions, TriggerRequest};
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
        .trigger(TriggerRequest {
            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
        .trigger(TriggerRequest {
            function_id: "github::exec".into(),
            payload: json!({ "args": ["--version"] }),
            action: None,
            timeout_ms: Some(60_000),
        })
        .await?;
    println!("{version:#?}"); // { stdout, stderr, exit_code, … }

    Ok(())
}
```

## Configuration

```yaml
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`](src/config.rs).

## api reference

```json
{
  "functions": [
    {
      "description": "Internal: reload github configuration when it changes.",
      "metadata": {
        "internal": true
      },
      "name": "github::on-config-change",
      "request_schema": {
        "properties": {},
        "type": "object"
      },
      "response_schema": {
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  ],
  "triggers": [
    {
      "description": "Fires after each github function runs; carries the call + a short result summary.",
      "invocation_schema": {},
      "metadata": {},
      "name": "github::called",
      "return_schema": {}
    }
  ]
}
```