---
name: github
description: 'GitHub issues and events as data for issue-driven workflows -- the fields of an issue form, and whether an event''s sender is an approver. Tools: check-approver, read-issue-form. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering
  tools: check-approver.py, read-issue-form.py
---

# GitHub

GitHub issues and events as data for issue-driven workflows -- the fields of an issue form, and whether an event's sender is an approver.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/check-approver.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `check-approver.py`

Whether a GitHub event's sender is an approver -- one of the people allowed to say "go" to an automated action -- printed as one line naming who approved what, or a failure giving the reason. The approvers file lists one GitHub username per line (# comments; a leading @ or "- " is ignored, so a plain YAML list also works); matching ignores case. label=<name> also requires the event to be that label being applied, so only that label counts as approval. Its receipt is the approval record: which event, which list, which answer.

Use when an issue-driven workflow must act only on approval from specific people -- e.g. before generating anything for a labelled issue, check that whoever applied the label is one of the repository's approvers.

```sh
<skill-dir>/check-approver.py -p event="<event>" -p approvers="<approvers>" [-p label="<label>"]
```

Parameters:
- `event` (file, required) — GitHub event JSON, e.g. $GITHUB_EVENT_PATH for an issues.labeled event
- `approvers` (file, required) — The approvers: one GitHub username per line, # comments allowed
- `label` (string, optional) — If set, the event must be this label being applied (e.g. poem:ready)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `read-issue-form.py`

The fields of a GitHub issue form as JSON: {"issue": {number, title, author, url, labels}, "fields": {<label_slug>: value}}. GitHub renders a form submission as "### Label" headings with values beneath; each heading becomes a snake_case key, "_No response_" becomes null, and checkbox lists become arrays of the checked options. Accepts a whole GitHub event payload (issues/issue_comment, e.g. $GITHUB_EVENT_PATH) or a bare issue body.

Use when an issue-driven workflow needs the answers from a templated GitHub issue as structured data, e.g. turning a labelled request issue into a request.json for the next step.

```sh
<skill-dir>/read-issue-form.py -p issue="<issue>"
```

Parameters:
- `issue` (file, required) — GitHub event JSON (with .issue) or a bare issue body in Markdown

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
