GitHub

Three things happen on GitHub that are really things happening to a person: somebody starts sponsoring you, opens an issue, or stars your repository. Kicklace takes all three through one address.

• A sponsor becomes a purchase on their record and moves them to Paying, the same as a payment from your own servers, so a sequence at Paying on your Lifecycle map thanks a sponsor too.
• An issue becomes a message from the person who opened it, so you can write back from their record.
• A star is recorded only if you switch it on, because a star isn't consent to anything.

There's no code to write. Kicklace changes nothing in GitHub, reads no code, and never reads the words inside an issue.

Signing in with GitHub is not a GitHub App with access to your repositories. A GitHub App with that access is a separate, optional install, for one thing: preparing a pull request when you set Kicklace up (How data gets in).

It's under Connections → GitHub, and only an owner or an admin can change it.

Connecting with your GitHub account

If your Kicklace shows Continue with GitHub on its sign-in card, that's the short way: sign in with GitHub, or connect your GitHub account from Connections, and Kicklace adds each webhook for you.

What Kicklace asks GitHub for, and nothing else:

repo isn't on that list, on purpose: it's the whole of a repository, and all Kicklace wants is a webhook. So a private repository is never listed. To watch one, add its webhook by hand (below).

Choosing the repositories

Under Repositories to watch are the ones you administer. Tick the ones you want and press Save: for each, Kicklace makes one webhook for Issues and Stars. Untick one and Kicklace takes its webhook away. A webhook you added yourself is never touched.

Reading your history

A webhook only hears what happens next. Read the history reads what's already there: everybody sponsoring you now, every stargazer (only if stars are switched on), and every issue already opened. Pull requests are skipped, and an issue's body is never read. Everything is dated by GitHub's own clock, nothing is sent for any of it, and it's safe to press twice.

Nobody is put on a list. Sponsoring you, opening an issue and starring a repository are none of them permission to email anybody.

The one webhook Kicklace can't make

Sponsorships arrive at a webhook on your account, not a repository, and GitHub's API has no way to make that one. So it's a by-hand step, below.

Setting it up by hand

This works everywhere, and it's the only way to add the sponsors webhook or a private repository's.

1. Make the address. Connections → GitHub → Connect GitHub gives you an address like https://<your Kicklace>/api/webhooks/github/<token>.

2. Add it in GitHub.

Paste the address as the Payload URL, set Content type to application/json, and choose Let me select individual events → Sponsorships, Issues, Stars. One address takes all three.

3. Use the same secret in both places. GitHub doesn't make a secret for you: the Secret box on that form is one you fill in. Type a long random secret there and paste the same one into Kicklace. It's locked away and never shown back. Until it's in, nothing is taken.

GitHub signs with X-Hub-Signature-256, an HMAC-SHA256 of the raw body. Kicklace refuses anything else, including the older SHA-1 X-Hub-Signature. There's one secret for the whole workspace; replacing it puts the new one on every webhook Kicklace made.

What lands

Everything else is answered 200 and ignored. A sponsorship is recorded in US dollars, because GitHub Sponsors is priced in dollars. Anything GitHub marks as a bot is skipped. Nothing lands twice.

Who it lands on

By their public email, when GitHub gives one, which is rarely. By their handle otherwise: a sponsor with no visible email is still written down, named after their handle.

The two become one when an email turns up. A sponsor who later signs up on your website is one person, not two. Two people who both have emails are never merged by themselves.

What's never read

An issue's body never reaches Kicklace, from a private repository or a public one. It can be long and carry a stack trace with a key in it. The title and the link are what land.

What a release changed

Where Vercel is connected too, Kicklace reads GitHub's compare of each production deploy against the one before, with the same grant: the commits, the pull requests they name, and the files they touched. It asks for no permission of its own for that.

Stars

Off by default. Record a star as a visit records that somebody was here and nothing more: no list, no move on your map, and no email because of it. Unstarring isn't recorded.

When something doesn't arrive

Every post GitHub makes shows on Connections → Your website → Your website's heartbeat, in plain words. The usual three:

• No webhook secret is set for that endpoint yet: step 3 isn't done.
• The signature did not hold: the secret in GitHub and the one in Kicklace aren't the same.
• Not something Kicklace records: a ping, an issue being closed, a star with the switch off.

GitHub keeps its own log under Recent Deliveries on the webhook's page. Redelivering from there is safe.

Disconnecting stops the address answering and takes away every webhook Kicklace made. Everything already recorded stays.