Skip to content

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:org scopes 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

  1. Navigate to Admin → Settings → Integrations → GitHub
  2. 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.
  3. 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:

  1. In GitHub, navigate to Settings → Webhooks → Add webhook
  2. Set Payload URL to: https://canviq.app/api/webhooks/github
  3. Set Content type to application/json
  4. Set Secret to your webhook secret (found in Canviq admin)
  5. Select events: Issues, Issue comments
  6. Click Add webhook

Canviq will now receive real-time updates when GitHub issues change.

Pushing Submissions to GitHub

From Submission Detail Page

  1. Open a submission (/admin/submissions/[id])
  2. Click Push to GitHub (top-right)
  3. Review issue details:
  4. Title: Pre-filled with submission title
  5. Description: Pre-filled with submission description + Canviq link
  6. Labels: Auto-assigned based on category/tags
  7. Assignee: Optional
  8. 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:

  1. Navigate to Admin → Triage Queue
  2. Select submissions using checkboxes
  3. Click Bulk Actions → Push to GitHub
  4. Configure issue template (title prefix, labels)
  5. 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:

  1. Open the submission detail page
  2. Click Unlink GitHub Issue
  3. 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:

  1. User submits feedback on Canviq
  2. Admin triages, changes status to "Planned"
  3. Admin pushes to GitHub → issue created
  4. Engineer labels issue in-progress in GitHub
  5. Canviq status auto-updates to "In Progress"
  6. Engineer closes issue in GitHub when work is done
  7. Canviq status auto-updates to "Shipped"
  8. 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