Docs · Guide
GitHub auto-ship
Put a ticket ID like WEB-142 in your branch name or PR title. Opening the PR moves the ticket to In Progress; merging moves it to In Production and emails the people who care. The board keeps itself honest while you keep coding.
Before you start
You need a Tickhatch board where you’re the owner or an editor (viewers can’t link repos), and a GitHub repository where you can add webhooks — that means admin access on the repo. A board can have several repos connected, but each repo links to a single board: its PRs move tickets on that board only.
Link your repo
- 1
Open the board’s GitHub section
Open the project’s board and scroll below the lanes to the row of collapsible sections. Expand GitHub. If you don’t see it, you’re a viewer on this board — ask the owner for editor access.
- 2
Connect the repo
Type the repository as owner/name — for example acme/app — and press Connect repo.
- 3
Copy the webhook details
Tickhatch replies with a one-time panel holding everything GitHub needs:
Payload URLhttps://tickhatch.com/api/integrations/github- Content type: application/json
- Secret: a fresh token, generated just for this repo
- Events: just Pull requests
Heads upThe secret is shown once — copy it before you leave the page. Lost it? Disconnect the repo and connect it again: linking generates a brand-new secret every time. - 4
Add the webhook in GitHub
In the repo on GitHub, open Settings → Webhooks → Add webhook. Paste the Payload URL and secret, set the content type to application/json, choose “Let me select individual events” and tick only Pull requests, then press Add webhook.
GitHub fires a ping at the new webhook right away — it shows up green under Recent Deliveries. The ping proves the URL is reachable, not that the secret matches, so open a small test PR to confirm the loop end-to-end.
How tickets get picked up
Tickhatch looks for a ticket ID — the board key plus a number, like WEB-142 — in three places, in this order: the branch name, then the PR title, then the PR description. The first place with an ID-shaped match wins, and within it only the first match counts.
web-142-fix-login-redirectFix the login redirect loop (WEB-142)Matching is case-insensitive — web-142 from a lazily named branch works fine — and anchored to a word boundary, so version-ish names like release-2 never trigger it. The key has to be the linked board’s: if the repo is connected to WEB, a MOB-7 in the branch does nothing — and because the branch is checked first, Tickhatch won’t fall back to a WEB-142 sitting in the title. Either way the PR itself is attached to the ticket, so you can jump to it from the ticket dialog.
What happens when
Pull request event → ticket move
opened / reopened
New → In Progress. Already past New? The ticket stays put — automation never moves a ticket backward.
merged
Anywhere → In Production. The ticket’s creator and assignee each get a “shipped” email (one email if that’s the same person) linking straight to the ticket.
closed without merging
No move. The PR is recorded as closed on the ticket; where the ticket goes next is up to you.
Testing is deliberately untouched: a PR can’t know when you’ve actually verified the work, so moving a ticket into Testing stays a human call.
Troubleshooting
GitHub’s Recent Deliveries shows 200 OK, but the ticket didn’t move.
A 200 doesn’t mean the ticket moved — Tickhatch answers 200 to every delivery, even ones it rejects, so GitHub doesn’t retry them. The usual culprit is the secret: a delivery signed with the wrong secret is dropped silently. Disconnect the repo in the board’s GitHub section, reconnect it to get a fresh secret, and paste that into the webhook’s Secret field in GitHub.
The ticket ID is in my branch, but nothing happened.
The ID’s key must match the board the repo is linked to — WEB-142 does nothing if the repo is connected to your MOB board. And only the first ID-shaped match counts: Tickhatch checks the branch name, then the PR title, then the description, and stops at the first place that has one — if that first match is some other board’s key, it doesn’t keep looking. Still stuck? Confirm the webhook is actually sending pull request events under the repo’s Recent Deliveries.
Opening a PR didn’t move my ticket to In Progress.
Opened (and reopened) only moves a ticket that’s still in New. If it’s already in In Progress, Testing, or In Production, it stays where it is — the automation never drags a ticket backward. Merging is the exception: it moves the ticket to In Production from any earlier column.
I lost the webhook secret.
Secrets are shown once and never again. Disconnect the repo in the board’s GitHub section and connect it again — linking generates a brand-new secret every time. Paste the new one into GitHub under Settings → Webhooks → your webhook → Edit, and you’re back in business.
Do squash and rebase merges count?
Yes. Tickhatch reads the merged flag GitHub sends with the closed event, and GitHub sets it for merge commits, squash merges, and rebase merges alike. A PR closed without merging changes nothing — the ticket stays where it is.
Which events should the webhook send?
Just “Pull requests”. Tickhatch ignores everything else (it answers 200 and does nothing), so sending more events only adds noise to your delivery log. If you picked “Send me everything” it still works — the pull request events get through either way.