GitHub
Pealboard connects to GitHub through one GitHub App, Pealboard
(github.com/apps/pealboard), installed by a workspace on an organization or
a personal account. Everything this API’s /v1/github/* routes and the
Issues, Projects, Labels and Milestones routes do against GitHub goes through
that installation.
Permissions
Section titled “Permissions”| Permission | Why |
|---|---|
| Issues, read and write | To show issues and comments, and to create and edit them from the workspace application and from portals. |
| Metadata, read | GitHub requires it for any repository access. |
| Pull requests, read | So an issue’s linked pull requests can be shown. Pealboard never writes to a pull request. |
| Projects, read and write | To read a project’s fields and items, and to set a field value when a card moves. |
| Members, read | To match a workspace member to a GitHub account. |
Pealboard never asks for code, contents, actions or secrets. It does not clone a repository and does not read source.
Events
Section titled “Events”The App is subscribed to: installation, installation_repositories,
installation_target, repository, issues, issue_comment, label,
milestone, projects_v2, projects_v2_item, projects_v2_status_update,
and sub_issues. Each delivery is verified against its signature and applied
to Pealboard’s cache; a delivery older than the cached row’s own updated_at
is dropped rather than applied, and an hourly reconciliation repairs anything
a dropped or missed delivery left stale. This is Pealboard receiving from
GitHub — it is not a surface for an integrator to call. See
Webhooks for the other direction.
Authoring: as the app, or as the member
Section titled “Authoring: as the app, or as the member”GitHub has no parameter that sets the author of an issue or a comment, so
content Pealboard writes with the installation’s own credential is authored by
pealboard[bot]. A member who links their GitHub account, from
Account → Linked GitHub, can instead have what they create through
Pealboard authored as themselves; content written this way carries no
attribution line, because the GitHub author already is the person. A member
who has not linked, and every portal customer, is written as the bot.
Attribution and markers
Section titled “Attribution and markers”An issue created through a portal carries this at the top of its body:
> **Requested by** Jane Doe (Acme) through the [Acme portal](https://acme.pealboard.com/requests/ACME-42).
<!-- pealboard:v1 request=ACME-42 portal=acme customer=8f1c... -->The visible line is for a person reading the issue in GitHub. It carries the
requester’s display name and company, and never their email address — GitHub
content is often shared more widely than the portal it came from, and an
address written into an issue body cannot be taken back. A public comment
written in a portal, or by a member using “Reply to portal”, ends with the
same kind of visible line and a comment-scoped marker,
<!-- pealboard:v1 public portal=acme -->.
The HTML comment is invisible in GitHub’s own rendering and is not the source of truth — the canonical link between an issue and the request it came from is a row in Pealboard’s database, keyed on the issue’s GitHub node id. The marker exists so that link can be rebuilt if a row is ever lost: it survives an edit by someone who does not know what it is, and it survives a restore from a backup taken before the request existed in Pealboard’s own database.
If a customer asks for deletion, Pealboard removes their portal account and rewrites the attribution lines it authored to read “a former customer,” leaving every other byte of the body untouched. The issue itself stays in GitHub — it belongs to the workspace — and only content Pealboard itself wrote is ever rewritten.
Rate limits
Section titled “Rate limits”GitHub’s own limit on the installation’s writes, not Pealboard’s request limit, is usually the binding one. See Rate limits.