Connectors

GitHub connector

Issues, pull requests and the README nobody updates.

In short

  • Reads issues, pull requests and branch prose from GitHub.com repositories through a GitHub App installation; source code is opt-in per repository.
  • Modes: sync for private repositories, fixed for any repository.

Setup

  1. Create a GitHub App with read-only permissions Metadata, Contents, Issues and Pull requests. No organization Members or Administration permission is needed; sync reads effective collaborators per repository.
  2. Install it on the account that owns the repositories and select those repositories. Note the App ID, the installation ID and the numeric ID of the installation owner (user or organization). The App-authenticated /app/installations/<installation_id> response supplies id, app_id and account.id; repository API responses supply each repository's id.
  3. Put the App's RS256 private key (PEM) in an environment variable.

Every run proves the installation: the App JWT must resolve to the configured installation and owner, or the sync fails. Installation tokens are minted in memory and never persisted.

Configuration

See shared configuration for installation, permission intervals, encryption keys and identity links.

[[sources]]
id = "github"
type = "github"
permissions = "sync"            # or "fixed" with readers = ["grp:staff"]

[sources.settings]
app_id = 12345
installation_id = 67890
account_id = 24680              # expected installation owner ID, not a login
private_key = { env = "FYRR_GITHUB_APP_KEY" }

[[sources.scope.repositories]]
id = 13579                      # stable numeric repository ID
branch = "main"                 # required; there is no default-branch drift
issues = true
pull_requests = true
prose = true
code = false                    # per-repository opt-in
KeyMeaning
settings.app_id, installation_id, account_idExpected App, installation and owner IDs; a mismatch fails.
settings.private_keyEnvironment reference to the App's PEM key.
settings.api_endpointREST origin; default https://api.github.com.
scope.repositories[]1–64 entries with unique IDs. Each enables at least one of issues, pull_requests, prose, code.

Repositories are keyed by numeric ID, so renames and transfers refresh URLs without changing identities. A configured ID that the installation cannot see fails the sync; a repository that later leaves the installation leaves the scope and its documents are removed at the next complete listing.

Documents

Issue and pull-request feeds are read by updated timestamp with an overlap. Deleted comments do not update their parent, so the connector also rotates through published conversations with a target of 12 hours; on large repositories or under rate limits a deleted comment can stay searchable longer. Files are enumerated each pass and reread when the branch head, blob, repository name, visibility or archived flag changes; file URLs pin the commit.

Permissions

Permission snapshots are reused within a run; see source revocation timing.

Under sync, only private repositories are supported. The effective collaborators with pull access are flattened to users:

GitHub accessReaders
Direct and outside collaborators, team members (nested teams included), organization owners, base-permission readersusr:github.com:<numeric user ID> on the repository container github:repo:<repository ID>
Personal repository ownerthe owner's usr: token
Public or internal repositoryrefused under sync; use fixed
Unknown visibility, unresolvable user, incomplete collaborator listno grant; the permission pass fails (failure handling)

No grp: grants are emitted; teams are expanded to their effective members. The member snapshot lists every observed reader as github.com:<numeric ID> with no e-mail, so linking a GitHub user to a canonical directory user needs an explicit account link in the directory snapshot. Profile, commit and noreply e-mails never link automatically.

Under fixed, the configured readers apply and no collaborator, team or member call is made.

Limits

Edit this page on GitHub ↗