GitHub connection

The repository owner installs Reach on selected repositories. An admitted issue or pull-request conversation can produce a proposed timeline comment, then one delivery as the application's bot. The conversation can ask for a code change without granting permission to execute or publish one.

The candidate reach.github.correspondence@1 profile belongs to the successor study. It starts with GitHub.com; another GitHub host/version needs its own pinned compatibility and credential configuration, not an arbitrary model-selected API URL.

Application and permissions

Prefer a GitHub App with installation identity and selected-repository access. OAuth Apps bind more broadly to user authority. Acting as a human is a separate optional authorization mode, not implied by bot installation. App comparison

Propose Issues write and Pull requests read, with no Contents, Workflows, Checks, Commit statuses, Administration or organization permission. Issue-comment REST endpoints cover issue and PR timeline comments, while issue_comment webhooks specifically need Issues read. These permission families are broader than this profile: the local operation allowlist admits only bounded reads and comment creation/updates to Reach-owned comments. Issue state changes remain excluded. Comment endpoints, webhook permissions

Installation tokens expire after one hour and can be narrowed to fewer repositories and permissions. Mint them on demand inside the credential owner. A publisher's app signing key can reach multiple installations and never belongs in customer software. The first self-hosted road uses a customer-owned app; a manifest registration can reduce manual setup. Installation tokens

Events and missed work

An initial request is either operator-originated or a first-line /reach ask text marker from a configured external actor in an admitted conversation. This is Reach's parser convention, not a native GitHub slash-command facility or local authority proof. Ignore the app's own comments, bot/automation authors by default, unconfigured actors and untriggered new activity before cognition. Resource changes may refresh a bounded projection without creating a request.

An edit to a triggering comment invalidates any unsent preparation based on the old version. It does not revise or resend an accepted reply. A new reply to an edited request needs a separately admitted request/version under explicit policy; polling overlap alone cannot create that authority.

The first road polls admitted repositories/conversations with pagination, overlap windows and conditional requests. Persist provider object id, version/update time and processed cursor; dedupe overlaps and distinguish edits from a new request. A changed comment cannot silently revise an already-approved response. Polling recovers accessible current state, not every deleted or intermediate event. Comment polling, conditional requests

A later webhook profile would first verify HMAC-SHA256 over the original body and bind the configured app/installation/repository and event/action. It must durably admit that intake before returning 2xx within the provider deadline. To recognize redelivery, deduplicate X-GitHub-Delivery with a payload fingerprint; GitHub retains the same GUID on redelivery. Bind each semantic action to its resource version as well, so delivery identity does not conceal an edit. The signature proves source bytes but gives the commenter no WardSecurity DeskSecurity Desk authority. Signature validation, webhook intake

GitHub does not automatically redeliver failed webhooks, and requested redelivery is limited to three days. App-wide delivery inspection/redelivery needs app-JWT custody rather than an ordinary installation token. A publisher-operated service must own that repair loop; resource polling remains the bounded reconciliation path. Failure handling, redelivery, app delivery API

Comment delivery and wider capabilities

Before review or standing policy, freeze the host, installation, repository id, issue/PR id, body, visibility observation and actor. Recheck current installation access and destination at send time. A proposed opaque Reach marker, carried in a hidden Markdown comment, can then help reconciliation associate a delivery occurrence with the bot-authored comment. Although hidden in rendering, it is externally visible source metadata: include it in the admitted bytes and keep customer/private identifiers out of it.

Correlation does not prevent duplicate writes. Neither the marker, GraphQL clientMutationId, nor check-run external_id establishes provider-enforced uniqueness. After an ambiguous POST, inspect the intended thread for the matching bot, marker and body, and retain the provider id/URL when known. If those reads are inconclusive, preserve UNKNOWN and do not resend. Even when the comment is known, updating it requires a separately authorized exact edit.

PR diff comments and formal reviews have separate APIs and Pull requests write. APPROVE and REQUEST_CHANGES are consequential review actions, not ordinary replies. Discussions use GraphQL and need a separate compatibility probe. Checks/statuses express commit-specific results and require their own permissions and judgment owner. Code edits, merges, releases and workflow runs belong to the relevant software-change owner, not this communications profile. Reviews, Discussions

REST installation allowance commonly starts at 5,000 requests/hour and varies with installation and plan. Respect primary response headers and secondary limits, serialize/pause content writes, and honor Retry-After and reset times on 403/429. No account/key rotation bypass. Rate limits

Ordinary releases preserve the app installation. Additional permissions require the installation owner's approval; an installation that has not approved keeps its old grant. Repository removal, installation suspension or uninstall fences pending sends without rerouting them. Permission changes

Forge · Accounts and updates · Acceptance and delivery