Cairn Docs

Appearance

GitHub Events ​

Cairn can push branches, create PRs, and show live CI status without you switching to a browser. This requires connecting to GitHub through a GitHub App.

What's a GitHub App? ​

A GitHub App is GitHub's mechanism for granting repository access to external tools. Unlike personal access tokens (which only work for outbound API calls), GitHub Apps can also receive webhooks—letting Cairn know when CI finishes, reviews come in, or PRs get merged.

When you connect GitHub in Cairn, you create your own GitHub App (named something like "Cairn a7b3c9d1"). The private key downloads during setup and stays on your machine, encrypted at rest. You're not granting access to "Cairn" as a service, you're granting access to your specific installation and nothing else.

Your Keys, Your Data ​

Cairn generates two separate keypairs:

Relay keypair — Used to claim and secure your relay channel. The public key establishes your anonymous channel on the relay server. The private key stays on your machine and decrypts any events stored while you were offline.

GitHub App keypair — Downloaded when you create your GitHub App. This is what allows Cairn to authenticate as your app and interact with your repositories.

Both private keys exist only on your machine. There are no copies anywhere else.

Technical Details

Relay encryption uses X25519 key exchange with XSalsa20-Poly1305 authenticated encryption (NaCl sealed boxes)—the same approach used by Signal and age.

How the Relay Works ​

Receiving webhooks on a desktop app requires exposing a public endpoint—doable, but inconvenient. The relay server handles this for you.

Initial setup:

  1. On first launch, Cairn generates your relay keypair
  2. Cairn connects to relay.cairn.computer and claims an anonymous channel, locked with your public key
  3. When you create your GitHub App, its webhook URL points to your relay channel
  4. Now GitHub knows where to send events—your channel is the "mailbox"

When events arrive:

  • If you're connected: The relay forwards events immediately via WebSocket. Nothing is stored.
  • If you're offline: The relay encrypts the event with your public key and holds it in your mailbox. When you reconnect, Cairn fetches, decrypts, and acknowledges events (triggering deletion on the relay).

The relay is intentionally minimal. It can't read your events (they're encrypted with your key). It doesn't know who you are (channels are anonymous). It just routes webhooks to desktop apps.