GitHub
Read actual GitHub issues, pull requests and comments with the selected account,
or apply exact already-decided changes and confirm them independently. For a
normal read, give repo and optionally kind, number, page and limit.
The read authority is selected by the existing native operation; callers do not
need to construct synchronization direction or scope just to inspect an issue.
The default github runner reads one bounded page or exact numbered record.
kind is issues (the shared GitHub issue feed, including PRs), pull_requests
or comments. Comments are issue/PR conversation comments; review diff comments
are a different capability. comments requires the issue or PR number. Exact
numbered reads return the actual current record; state/label filters are for
list queries. Raw provider records and the original native operation evidence
are preserved. A bounded page never establishes complete conversation/history
coverage, including when filtering PRs out of an issue-feed page.
The explicit sync runner performs the requested advanced pull or push. plan
is the explicit no-effect runner; pull and push remain explicit execution
lanes for compatible callers. Pulls are bounded reads. A push carries one to
twenty typed mutations per call that one GitHub operation applies, and returns each
item's outcome. It closes only on an independent GitHub readback of every
applied item. An item whose outcome is unknown holds the push for
reconciliation and is never silently retried. activity reads what changed
in a repository since a time, compact enough to summarise. No GitHub token
enters this package.
When to use it
Use the default for actual bounded records. Resolve an omitted repository in
the host with ordinary git remote/context tools, verify the exact owner/name,
and pass it explicitly. Do not guess a repository, treat a folder name as one,
or introduce a separate repository/cursor state store.
Use sync when an operator needs a reproducible pull or push contract for
issues, pull requests, or threads, especially when cursor state must survive
across runs. Use plan only when the requested outcome is a plan. Use pull
for an explicitly selected read lane. Use activity to learn what changed in
a repository since a time, such as since the last check of a daily summary:
it reads issues and pull requests together and returns the fields a reader
needs rather than GitHub's whole records. Use push for already-decided issue,
pull-request, or comment changes of one kind. A call accepts up to twenty changes, matching the connector's batch contract; split larger work into separate calls and retain each result. Batches are bounded and
best-effort, not atomic: a refused item does not stop the rest, the result
identifies each item, and the operator reconciles before retrying. Use github-issue-triage to decide what an issue means
and github-issue-to-pr to govern an implementation lane.
Do not use a plan as evidence that remote state was read or changed. Only the
native runx.provider.operation.v1 result from pull or push is provider
evidence. Do not silently turn a denied push into a pull.
How it works
- Validate the exact
owner/name repository, direction, resource kind, bounded
filters, maximum result count, and requested scope.
- A
pull plan requires read scope and records the exact resources a provider
may fetch.
- A
push plan requires write scope and one to twenty typed mutations per call that
one GitHub operation applies: issues.create, issues.update,
pullrequests.update, comments.create, or comments.update. It rejects unknown fields,
oversized content, and mixed kinds, then returns ready_for_execution;
planning itself does not grant provider authority.
- Optional
plan_and_append_cursor calls the store's events.append and
projection.read to append the bounded plan and read the projection back. That proves local
cursor persistence, not GitHub synchronization; this package does not own a
second cursor database or storage adapter.
- The explicit
sync runner selects the same bounded read or write path from the
validated direction. pull calls the planned read (issues.list,
issues.read, pullrequests.list, pullrequests.read, or
comments.list) with repo.read. push calls the planned write once under
repo.write for issue and pull-request changes or issue.comment for comment changes: the runtime sends each item, records each outcome, and reads
every applied item back before the push closes.
Both run under the GitHub instance selected here: the signed-in gh session
or a stored token.
activity calls issues.list with repo.read for one page of 100 of
everything updated at or after since, open or closed. GitHub's listing
holds pull requests too, so one read finds both. The result keeps each
item's number, kind, title, state (merged for a merged pull request),
whether it was opened at or after since, its author and whether that is a
bot, its times, labels, assignees, comment count and link, and the first
600 characters of its body with the count left out. The provider is queried in updated/descending order, then the
page is projected in that order; a full page names a possible next_page.
Inputs and result
repo is exactly owner/name.
- The default needs only
repo: e.g. {repo: "runxhq/runx", kind: "pull_requests", number: 554} reads that exact PR. To continue comments use kind: comments, its number, and the next page, retaining the same query and original provider receipt.
direction is pull or push for the explicit sync and planning phases.
resources contains the issue, PR, thread, or batch selector and a
limit no greater than 100. A push has one to twenty mutations entries with path, op, and an
exact typed payload. Issue and PR changes use op: update; a new issue
uses path: issues and op: create; new thread comments use op: comment. Bodies are capped at 65,536 characters. Pulls
return GitHub's records whole.
scope is the requested read or write scope.
activity takes repo, since (RFC 3339) and an optional page, and
returns activity: the repository, since, the page, its items, and
next_page when more may follow. Its provider evidence is the read's
runx.provider.operation.v1, kept in the run's record.
The runx/github.sync_plan.v1 plan records exact direction, provider operation,
scope, filters, blockers, authority posture, cursor state when used, and the
explicit absence of remote effects. Execution additionally emits the native
provider-operation packet; it does not rewrite the planning packet to imply a
remote effect.
Stop conditions
- Refuse malformed repositories, unknown resource kinds, unbounded selectors,
limits above the contract, more than twenty mutations in one call, unknown mutation fields, or
content beyond the declared bounds.
- Refuse push when write scope is missing; do not degrade silently.
- Do not treat local cursor persistence as remote provider readback.
- Refuse a push that mixes new issues, issue, pull-request, and comment
changes; send each kind as its own push.
- Refuse when no GitHub instance is selected, or the selected one lacks the
scope. Never treat an available instance as evidence of the intended
repository.
- Do not claim comments, labels, issues, or PRs were read or changed until the
native provider operation proves the expected access, operation, and readback.
Example
A caller wants to pull the next 50 open issues after cursor 2. Planning can
persist that cursor locally; pull then performs issues.list through the
selected instance and returns the provider result. To close issue 241, a push
carries path: issues/241, op: update, and
payload: {state: closed, state_reason: completed}. Runx applies only that
issue update through issues.update under repo.write, and reads issue 241
back. A morning summary calls activity with since set to its last check
and reports the items that are new, or changed by someone else.
For composition, consume the returned native provider-operation packet directly.
Pass already read issue fields to github-issue-triage respond, preserving
repository, exact number, title, state, full relevant body and original source
link/receipt. This path does not fetch or post again. pull and push retain
their complete typed selectors for power users; the common reader does not
replace them. Local cursor persistence remains the explicit store-owned phase.
1---2name: github3description: Read or synchronize bounded GitHub issues, threads, and pull requests through the GitHub connector, with scoped authority and readback.4metadata:5 source: https://skillmd.com/skills/runxhq/github6---78# GitHub910Read actual GitHub issues, pull requests and comments with the selected account,11or apply exact already-decided changes and confirm them independently. For a12normal read, give `repo` and optionally `kind`, `number`, `page` and `limit`.13The read authority is selected by the existing native operation; callers do not14need to construct synchronization direction or scope just to inspect an issue.1516The default `github` runner reads one bounded page or exact numbered record.17`kind` is `issues` (the shared GitHub issue feed, including PRs), `pull_requests`18or `comments`. Comments are issue/PR conversation comments; review diff comments19are a different capability. `comments` requires the issue or PR number. Exact20numbered reads return the actual current record; state/label filters are for21list queries. Raw provider records and the original native operation evidence22are preserved. A bounded page never establishes complete conversation/history23coverage, including when filtering PRs out of an issue-feed page.2425The explicit `sync` runner performs the requested advanced pull or push. `plan`26is the explicit no-effect runner; `pull` and `push` remain explicit execution27lanes for compatible callers. Pulls are bounded reads. A push carries one to28twenty typed mutations per call that one GitHub operation applies, and returns each29item's outcome. It closes only on an independent GitHub readback of every30applied item. An item whose outcome is unknown holds the push for31reconciliation and is never silently retried. `activity` reads what changed32in a repository since a time, compact enough to summarise. No GitHub token33enters this package.3435## When to use it3637Use the default for actual bounded records. Resolve an omitted repository in38the host with ordinary git remote/context tools, verify the exact owner/name,39and pass it explicitly. Do not guess a repository, treat a folder name as one,40or introduce a separate repository/cursor state store.4142Use `sync` when an operator needs a reproducible pull or push contract for43issues, pull requests, or threads, especially when cursor state must survive44across runs. Use `plan` only when the requested outcome is a plan. Use `pull`45for an explicitly selected read lane. Use `activity` to learn what changed in46a repository since a time, such as since the last check of a daily summary:47it reads issues and pull requests together and returns the fields a reader48needs rather than GitHub's whole records. Use `push` for already-decided issue,49pull-request, or comment changes of one kind. A call accepts up to twenty changes, matching the connector's batch contract; split larger work into separate calls and retain each result. Batches are bounded and50best-effort, not atomic: a refused item does not stop the rest, the result51identifies each item, and the operator reconciles before retrying. Use `github-issue-triage` to decide what an issue means52and `github-issue-to-pr` to govern an implementation lane.5354Do not use a plan as evidence that remote state was read or changed. Only the55native `runx.provider.operation.v1` result from `pull` or `push` is provider56evidence. Do not silently turn a denied push into a pull.5758## How it works59601. Validate the exact `owner/name` repository, direction, resource kind, bounded61 filters, maximum result count, and requested scope.622. A `pull` plan requires read scope and records the exact resources a provider63 may fetch.643. A `push` plan requires write scope and one to twenty typed mutations per call that65 one GitHub operation applies: `issues.create`, `issues.update`,66 `pullrequests.update`, `comments.create`, or `comments.update`. It rejects unknown fields,67 oversized content, and mixed kinds, then returns `ready_for_execution`;68 planning itself does not grant provider authority.694. Optional `plan_and_append_cursor` calls the store's `events.append` and70 `projection.read` to append the bounded plan and read the projection back. That proves local71 cursor persistence, not GitHub synchronization; this package does not own a72 second cursor database or storage adapter.735. The explicit `sync` runner selects the same bounded read or write path from the74 validated direction. `pull` calls the planned read (`issues.list`,75 `issues.read`, `pullrequests.list`, `pullrequests.read`, or76 `comments.list`) with `repo.read`. `push` calls the planned write once under77 `repo.write` for issue and pull-request changes or `issue.comment` for comment changes: the runtime sends each item, records each outcome, and reads78 every applied item back before the push closes.79 Both run under the GitHub instance selected here: the signed-in `gh` session80 or a stored token.816. `activity` calls `issues.list` with `repo.read` for one page of 100 of82 everything updated at or after `since`, open or closed. GitHub's listing83 holds pull requests too, so one read finds both. The result keeps each84 item's number, kind, title, state (`merged` for a merged pull request),85 whether it was opened at or after `since`, its author and whether that is a86 bot, its times, labels, assignees, comment count and link, and the first87 600 characters of its body with the count left out. The provider is queried in updated/descending order, then the88 page is projected in that order; a full page names a possible `next_page`.8990## Inputs and result9192- `repo` is exactly `owner/name`.93- The default needs only `repo`: e.g. `{repo: "runxhq/runx", kind: "pull_requests", number: 554}` reads that exact PR. To continue comments use `kind: comments`, its `number`, and the next `page`, retaining the same query and original provider receipt.94- `direction` is `pull` or `push` for the explicit `sync` and planning phases.95- `resources` contains the issue, PR, thread, or `batch` selector and a96 limit no greater than 100. A push has one to twenty `mutations` entries with `path`, `op`, and an97 exact typed `payload`. Issue and PR changes use `op: update`; a new issue98 uses `path: issues` and `op: create`; new thread comments use `op: comment`. Bodies are capped at 65,536 characters. Pulls99 return GitHub's records whole.100- `scope` is the requested read or write scope.101- `activity` takes `repo`, `since` (RFC 3339) and an optional `page`, and102 returns `activity`: the repository, `since`, the page, its items, and103 `next_page` when more may follow. Its provider evidence is the read's104 `runx.provider.operation.v1`, kept in the run's record.105106The `runx/github.sync_plan.v1` plan records exact direction, provider operation,107scope, filters, blockers, authority posture, cursor state when used, and the108explicit absence of remote effects. Execution additionally emits the native109provider-operation packet; it does not rewrite the planning packet to imply a110remote effect.111112## Stop conditions113114- Refuse malformed repositories, unknown resource kinds, unbounded selectors,115 limits above the contract, more than twenty mutations in one call, unknown mutation fields, or116 content beyond the declared bounds.117- Refuse push when write scope is missing; do not degrade silently.118- Do not treat local cursor persistence as remote provider readback.119- Refuse a push that mixes new issues, issue, pull-request, and comment120 changes; send each kind as its own push.121- Refuse when no GitHub instance is selected, or the selected one lacks the122 scope. Never treat an available instance as evidence of the intended123 repository.124- Do not claim comments, labels, issues, or PRs were read or changed until the125 native provider operation proves the expected access, operation, and readback.126127## Example128129A caller wants to pull the next 50 open issues after cursor `2`. Planning can130persist that cursor locally; `pull` then performs `issues.list` through the131selected instance and returns the provider result. To close issue 241, a push132carries `path: issues/241`, `op: update`, and133`payload: {state: closed, state_reason: completed}`. Runx applies only that134issue update through `issues.update` under `repo.write`, and reads issue 241135back. A morning summary calls `activity` with `since` set to its last check136and reports the items that are new, or changed by someone else.137138For composition, consume the returned native provider-operation packet directly.139Pass already read issue fields to `github-issue-triage` `respond`, preserving140repository, exact number, title, state, full relevant body and original source141link/receipt. This path does not fetch or post again. `pull` and `push` retain142their complete typed selectors for power users; the common reader does not143replace them. Local cursor persistence remains the explicit store-owned phase.