Skip to content

GitHub Integration

!!! info "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

  • GitHub organization or personal account with repo access
  • GitHub Personal Access Token (PAT) with repo scope
  • Admin access to Canviq

Step 1: Connect GitHub Account

  1. Navigate to Admin → Integrations → GitHub
  2. Click Connect GitHub Account
  3. Choose connection method:
  4. OAuth — Authorize Canviq to access your GitHub repos (recommended)
  5. Personal Access Token — Manually paste a GitHub PAT
  6. Select target repository (e.g., yourorg/product-repo)
  7. Click Save

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.

Webhook Logs

View webhook activity in Admin → Integrations → GitHub → Webhook Logs:

  • Timestamp — When the webhook was received
  • Event — Event type (e.g., issues.closed)
  • Issue ID — GitHub issue number
  • Submission ID — Linked Canviq submission
  • Action — What Canviq did in response (e.g., "Changed status to Shipped")
  • Status — Success or error

Webhook logs are retained for 90 days.

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:

  • Verify GitHub token has repo scope
  • Check that target repository exists and you have write access
  • 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