GitHub Integration

Before you start

• Git integrations are available on Team plan workspaces.
• You need workspace permission to manage integrations.
• Create the repository connection in Ouraboard first, then add webhook in GitHub.
• Use the same repository in both systems. Owner/name must match exactly.

Step 1: Connect repository in Ouraboard

1. Open Workspace Settings → Git.
2. Set provider = GitHub.
3. Fill:
   • Repository owner (for github.com/acme/my-repo it is acme)
   • Repository name (for github.com/acme/my-repo it is my-repo)
   • Webhook secret (generate a random string and keep it safe)
   • Default branch (usually main)
4. Click Connect.
5. In Connected repositories, copy the full Webhook URL.

Step 2: Create GitHub webhook

1. Open your repository on GitHub.
2. Go to Settings → Webhooks.
3. Click Add webhook.
4. Paste webhook URL copied from Ouraboard.
5. Select content type application/json.
6. Paste the same secret from Ouraboard into the webhook secret field.
7. Select events:
   • Pushes
   • Pull requests
8. Keep webhook Active enabled and save.

Step 3: Verify end-to-end

1. Create or pick an issue in Ouraboard (example slug: PRJ-123).
2. Push a commit with slug in message (example: fix: PRJ-123 webhook test).
3. Optionally open a PR with same slug in title or description.
4. Open issue → Development tab and confirm commit/PR activity appears.

Issue linking rule

Include issue slug in branch, commit, or pull request text (example: PRJ-123) so activity is linked to the correct issue.

Recommended commit formats

• fix: PRJ-123 handle GitHub webhook retries
• feat(PRJ-456): add development live updates
• chore: update deps [PRJ-789]

If no issue slug is present, event is accepted but not attached to an issue.

Default branch behavior

• Linking works for all branches when issue slug is present.
• Default branch is used for optional auto-move branch guard only.
• Enable branch guard if you want auto-move only when PR targets your default branch.

Security checks

• Signature validation must pass (X-Hub-Signature-256).
• Unknown repositories are rejected.
• Duplicate deliveries are ignored using idempotency handling.

Troubleshooting

• Webhook repository does not match configured integration: check owner/name in Ouraboard vs GitHub repository URL.
• Signature mismatch or 401/403: re-check webhook secret on both sides.
• No issue linked: ensure commit/PR text contains valid issue slug (for example PRJ-123).
• Webhook test fails: ensure webhook URL is full URL and publicly reachable from GitHub.

Screenshot