GitHub Integration¶
TL;DR
Push feedback to GitHub issues with one click. Two-way sync keeps status in sync between Canviq and GitHub. Webhook receiver listens for GitHub issue status changes and updates Canviq automatically.
What is the GitHub Integration?¶
The GitHub integration connects Canviq feedback to your development workflow. Product teams can convert user feedback into GitHub issues without leaving the Canviq admin dashboard. When issue status changes in GitHub (e.g., closed, labeled), Canviq automatically updates the submission status.
Key Features¶
- One-Click Push: Convert submissions into GitHub issues
- Two-Way Sync: Status changes in GitHub update Canviq (and vice versa)
- Webhook Receiver: Listens for GitHub events in real-time
- Customizable Mapping: Configure which Canviq statuses map to GitHub labels
- Audit Trail: All syncs logged for compliance
Setup¶
Prerequisites¶
- A GitHub account with write (push) access to the repository you want to use
- A public repository. Private repositories are not supported yet: the connection asks GitHub for the
public_repo read:orgscopes only, and GitHub reports every private repository as not found. - Admin access to Canviq
- Startup plan or higher to push submissions to GitHub, and Growth or higher for two-way sync (GitHub issue changes updating Canviq). Connecting the account and generating the webhook secret are checked against the same plan requirement. Disconnecting always works, on any plan.
Step 1: Connect GitHub Account¶
- Navigate to Admin → Settings → Integrations → GitHub
- Click Connect GitHub and authorize Canviq on GitHub. The sign-in is bound to the admin who started it, in the same browser session. Opening the authorize link from a different browser or account does not connect anything.
- Enter the target repository as
owner/name(for example,yourorg/product-repo) and click Save
When you save, Canviq checks with GitHub that your connection can push to the repository, and stores the name exactly as GitHub spells it.
Each repository can be connected to one Canviq organization at a time. If a save fails, the message says why:
| Message | What it means |
|---|---|
| Another Canviq organization has already connected this repository | Another organization holds the repository. Contact support if it is yours. |
| Your GitHub account doesn't have write access to this repository | Check the name, or reconnect with an account that can push to it. |
| Your GitHub connection has expired | Disconnect, connect GitHub again, then save the repository. |
| Saving a repository needs the Startup plan or higher | Upgrade your plan to change the repository. |
Step 2: Configure Status Mapping¶
Map Canviq statuses to GitHub issue states:
| Canviq Status | GitHub State | GitHub Label (optional) |
|---|---|---|
| Planned | Open | planned |
| In Progress | Open | in-progress |
| Shipped | Closed | shipped |
| Declined | Closed | wontfix |
Custom mappings can be defined in Admin → Integrations → GitHub → Status Mapping.
Step 3: Set Up Webhook¶
To enable two-way sync, configure a GitHub webhook:
- In GitHub, navigate to Settings → Webhooks → Add webhook
- Set Payload URL to:
https://canviq.app/api/webhooks/github - Set Content type to
application/json - Set Secret to your webhook secret (found in Canviq admin)
- Select events:
Issues,Issue comments - Click Add webhook
Canviq will now receive real-time updates when GitHub issues change.
Pushing Submissions to GitHub¶
From Submission Detail Page¶
- Open a submission (
/admin/submissions/[id]) - Click Push to GitHub (top-right)
- Review issue details:
- Title: Pre-filled with submission title
- Description: Pre-filled with submission description + Canviq link
- Labels: Auto-assigned based on category/tags
- Assignee: Optional
- Click Create Issue
The GitHub issue is created and linked to the Canviq submission. A comment is posted on the submission with a link to the GitHub issue.
From Triage Queue¶
Bulk push multiple submissions to GitHub:
- Navigate to Admin → Triage Queue
- Select submissions using checkboxes
- Click Bulk Actions → Push to GitHub
- Configure issue template (title prefix, labels)
- Confirm
All selected submissions are converted to GitHub issues.
Issue Template¶
GitHub issues created from Canviq include:
## User Feedback
**Title:** [Submission Title]
**Description:** [Submission Description]
**Metadata:**
- Votes: 120
- Comments: 15
- Status: Planned
- Category: Feature Request
- Tags: export, pdf
**Canviq Link:** https://canviq.app/submissions/123
---
This issue was created from user feedback submitted via Canviq.
Customize the template in Admin → Integrations → GitHub → Issue Template.
Two-Way Sync¶
Once a submission is linked to a GitHub issue, status changes in either system sync automatically.
GitHub → Canviq¶
| GitHub Event | Canviq Action |
|---|---|
| Issue opened | No change (issue already exists) |
| Issue closed | Change status to "Shipped" |
Issue labeled wontfix | Change status to "Declined" |
Issue labeled in-progress | Change status to "In Progress" |
| Issue reopened | Change status to "Under Review" |
| Issue comment added | Optional: Post comment on Canviq submission |
Canviq → GitHub¶
| Canviq Event | GitHub Action |
|---|---|
| Status → "Shipped" | Close GitHub issue, add label shipped |
| Status → "Declined" | Close GitHub issue, add label wontfix |
| Status → "In Progress" | Add label in-progress |
| Comment added (official) | Post comment on GitHub issue |
Sync settings can be customized in Admin → Integrations → GitHub → Sync Rules.
Webhook Receiver¶
The webhook receiver listens for GitHub events and updates Canviq submissions in real-time.
Supported Events¶
| Event | Description | Action |
|---|---|---|
issues.opened | New issue created | No action (Canviq creates issues, not vice versa) |
issues.closed | Issue closed | Update Canviq status to "Shipped" |
issues.reopened | Issue reopened | Update Canviq status to "Under Review" |
issues.labeled | Label added | Update status based on label mapping |
issues.unlabeled | Label removed | Optionally revert status |
issue_comment.created | Comment added | Post comment on Canviq submission (optional) |
Webhook Security¶
Webhooks are secured using HMAC-SHA256 signatures. Canviq verifies the X-Hub-Signature-256 header on every webhook request to ensure it originated from GitHub.
Leaked API keys¶
If a Canviq API key is committed to a GitHub repository, GitHub secret scanning can notify Canviq. Canviq checks the full token against the stored key and revokes it only when it matches, so a string that merely looks like a key is ignored. See Authentication for key management.
Unlinking Submissions¶
To unlink a submission from a GitHub issue:
- Open the submission detail page
- Click Unlink GitHub Issue
- Confirm
The link is removed, but the GitHub issue remains open. Future status changes in GitHub will not affect the Canviq submission.
Troubleshooting¶
Issues Not Creating¶
Problem: Clicking "Push to GitHub" fails or shows an error.
Solutions:
- Check that the target repository exists, is public, and that the GitHub account you connected can push to it
- If the connection has expired, disconnect and connect GitHub again
- Review error message in webhook logs
Status Not Syncing¶
Problem: Closing a GitHub issue doesn't update Canviq status.
Solutions:
- Verify webhook is configured correctly in GitHub
- Check webhook secret matches the one in Canviq
- Review webhook logs for errors (e.g., signature mismatch)
- Ensure status mapping is configured in Canviq
Duplicate Issues¶
Problem: Multiple GitHub issues created for the same submission.
Solutions:
- Check if submission is already linked (link appears in sidebar)
- Avoid clicking "Push to GitHub" multiple times (button disables after first click)
- Search GitHub for existing issue before pushing
Best Practices¶
When to Push to GitHub¶
- High-vote submissions: >50 votes indicate strong user demand
- Planned items: After team decides to implement
- Bug reports: Push critical bugs immediately for triage
When Not to Push¶
- Spam or low-quality feedback: Triage first, push only valid feedback
- Duplicates: Merge duplicates in Canviq before pushing
- Declined submissions: No need to create GitHub issues for rejected feedback
Workflow Integration¶
Example workflow:
- User submits feedback on Canviq
- Admin triages, changes status to "Planned"
- Admin pushes to GitHub → issue created
- Engineer labels issue
in-progressin GitHub - Canviq status auto-updates to "In Progress"
- Engineer closes issue in GitHub when work is done
- Canviq status auto-updates to "Shipped"
- User is notified their feedback was implemented
Metrics¶
Track GitHub integration usage:
- Issues Created: Total submissions pushed to GitHub
- Sync Success Rate: % of webhook events successfully processed
- Avg Time to Ship: Median time from "Planned" to "Shipped" (via GitHub sync)
View metrics in Admin → Integrations → GitHub → Metrics.
What's Next¶
- Status Management: Understand the submission lifecycle
- Triage & Moderation: Review and categorize submissions
- Team Management: Assign team members to submissions