GitHub Interactions Envoy
The GitHub Interactions Envoy watches issues, pull requests, and reviews on repositories you connect, and can act on them — but only once you've told it to, and only in ways your own .foreshock.yml spells out.
Connect a repository
From GitHub in your workspace, Connect GitHub takes you to GitHub's own installation picker, where you choose an organization and the repositories to grant. Back in Foreshock, Track on a repo creates a sensor for it and does the first read of that repo's .foreshock.yml. A repository counts against your plan's repo allotment the moment you track it.
!!!SCREEN SHOT: The GitHub client area, showing the installation's repository list with a couple of repos tracked and their current mode (watching / active) visible.
Interaction rules, as code
Everything the Envoy does on a repository is governed by one file, read from the repository's default branch:
# .foreshock.yml
version: 1
mode: active # or telemetry_only — scores, never touches GitHub
sensitivity: medium # low=85 | medium=75 | high=65 confidence threshold
safety_defaults: true # built-ins: racism, sexism, harassment — always minimize
custom_shunts:
- name: hostile_takeover
action: receipt # minimize | receipt | log_only
template: Hostile
phrases:
- "we should fork this and take over"
- "the maintainer is incompetent"
## Hostile
Thanks for the report. This thread has been flagged for review.
A ## heading in the file is a comment template, referenced by name from a shunt's template: field — that's the text posted back when the shunt trips with a receipt action. Limits: 24 shunts, 32 phrases each, 300 characters per phrase, 34-character names — the same caps as the Shunt Studio.
Pushing a change to .foreshock.yml on the default branch re-reads it automatically, so every change to enforcement is a normal, reviewable commit — no separate dashboard toggle to forget about.
What triggers a score
The Envoy scores exactly six kinds of GitHub activity: a newly opened issue, a newly created issue comment, a newly opened pull request, a submitted pull request review (the review's summary prose), and a newly created pull request review comment (an inline note on a diff line). Bot-authored events are filtered out before scoring. Nothing about a repository's stars, metadata, or other traffic is read.
Log only, or take action
Two modes govern what happens once something scores above your sensitivity threshold:
Every arrival is scored and the verdict is recorded — which shunt would have tripped, at what confidence, on which thread — but nothing on GitHub is ever touched. This is the recommended starting mode for any newly tracked repository.
The same verdicts now act. A minimize on a comment collapses it on GitHub and leaves a receipt comment; on an issue/PR body (which can't be collapsed) it degrades to a receipt comment instead. A receipt action just posts the comment. A log_only action makes no GitHub call at all — pure telemetry, even in active mode.
The log itself, visible per-repository in your workspace, reads like this while watching:
foreshock-io/sensor-playground WATCHING
would MINIMIZE contributor_abuse 88% #12 issue_comment 2h ago
would RECEIPT entitled_demands 79% #11 issue 5h ago
no shunt tripped — — #10 pull_request 6h ago
Once that log looks right — the shunts that should fire are firing, and nothing else is — set mode: active and push. The same log becomes the live audit trail (MINIMIZED / RECEIPTED / FAILED) instead of a forecast. Pause on the repo's row in your workspace is the immediate kill switch if enforcement ever needs to stop right away.
!!!SCREEN SHOT: A repository's telemetry log in the client area, showing a mix of "would MINIMIZE"/"would RECEIPT" watching-mode entries.
Log only to start, on purpose
The point of telemetry_only isn't caution for its own sake — it's how you and your community find your biggest actual conflict points together, with real data, before anything is automated. Because the specimen text itself is never stored (only the spectrum and each shunt:<name> confidence, keyed by a hash of the thread), reviewing the watch log never means reading anyone's private words back to them — just the pattern of what's been tripping, and how often.
Where to go next
Custom shunts here are configuration, not the Shunt Studio account bank — they're scoped to one repository and live in that repository's own version control. For the concepts behind shunts, actions, and sensitivity thresholds, see Shunts & Latent Concept Erasure. For how a tracked repo's history shows up as a trend, see Graphs & Data.