Tutorial
Connect GitHub pull requests to your board
Set up a repository webhook so pull requests appear on the card — including the two traps that otherwise make it fail silently.
Last updated:
Commits show what was worked on. Pull requests show what is waiting to land — and when it actually did. This guide connects both to the board. Git integration belongs to the Developer plan, and pull request tracking runs through GitHub only today.
What you need
- The Developer plan — see pricing.
- A GitHub repository you administer (creating webhooks requires it).
- Ideally first: link commits to cards.
1. Check your plan
Without the Developer plan the endpoint accepts no events. The webhook would be configured, but every delivery would land nowhere.
2. Get the webhook URL and secret from Zuuna
Zuuna provides a webhook URL per repository along with a matching secret. Copy both — the secret is the only proof Zuuna has that a delivery genuinely came from GitHub.
3. Add the webhook in GitHub
In the repository: Settings → Webhooks → Add webhook.
- Payload URL — the URL from Zuuna.
- Content type —
application/json. The default is something else; change it, or the payload arrives in a shape that is not parsed. - Secret — the secret from Zuuna.
- Events — "Let me select individual events", then Pull requests and Pushes.
4. Check the ping
GitHub sends a ping immediately. The result appears under "Recent Deliveries". The green tick is the real confirmation that the secret is correct — an error there almost always means the secret was mis-copied or the content type is still not JSON.
5. Put the card key in the PR title
And here is the trap that costs most people half an hour:
A card key that sits only in the branch name or only in the PR number matches nothing. The response is "0 linked" and no card moves.
The reason: on a pull request event Zuuna reads the title and the description, not the reference. So put the key in the PR title — ZNA-164: add sprint picker to the backlog — or in the description. A good branch name does no harm; it is simply not enough here.
6. Merge and check the card
Opening the pull request makes it appear on the card; merging changes its state and runs the matching automations. A pull request closed without merging, by contrast, deliberately fires nothing: abandoned work should not advance a card.
Troubleshooting
- Delivery red in GitHub. The secret or URL is wrong. Edit the webhook, paste the secret again, hit "Redeliver".
- Delivery green, nothing on the card. The key sat only in the branch name or the PR number. Move it into the title.
- Merging does not move the card. Check whether any rule listens for "pull request merged" — linking alone moves nothing, the automation does.
- Push events missing. Only "Pull requests" is selected on the webhook. Enable both events.
Next steps
- Move cards automatically with git — decide what should happen on merge.
- Show build status on the card.
- Zuuna vs Jira — how this differs from the Atlassian version.
FAQ
Why is my card not moving?
Almost always because the card key sits only in the branch name or the PR number. A pull request event does not read those fields — put the key in the PR title or the description.
Do I need a GitHub App or OAuth?
No. The webhook URL and the secret you paste into GitHub are enough. Your repository grants no further rights in the process.
Does this work with GitLab or Bitbucket?
For pull requests, not today — this route is GitHub-specific. Commits and branches, by contrast, work with any git host through the post-commit hook.
Is the endpoint safe even though it is publicly reachable?
Yes. GitHub signs every delivery with the shared secret, and Zuuna verifies that signature against the unmodified raw request body. Without a valid signature nothing is processed.
What happens when a pull request is closed without merging?
Nothing — deliberately. Abandoned work should not push a card into "In progress" and wear a progress badge it never earned.