Skip to main content

GitHub issues integration

End users in QRY can report issues from the Help menu. Without the GitHub integration, those reports stay in QRY's own database. With it, every report syncs to a GitHub repo of your choice — typically pueteam/QRY for QRY's own issue tracker, or your own internal repo for tenant-specific bug tracking.

The sync is bidirectional: QRY → GitHub is immediate (creating an issue in GitHub when a user reports); GitHub → QRY is on-demand (no webhooks — admins trigger a sync to pull updates back). This is intentional: webhooks add complexity and a public ingress; on-demand sync is enough for most tenants.

What gets synced​

DirectionTriggerWhat's synced
QRY → GitHubUser clicks Report issueNew GitHub issue with title, description, user, conversation context (if any), tenant id
GitHub → QRYAdmin triggers Refresh issuesUpdated status, labels, comments, close state

The user's email is included in the GitHub issue body so engineering can reach back. Privacy implication: the GitHub repo's visibility (public / private / org-internal) determines who can read user emails. Use a private repo for anything customer-facing.

Configuring​

Admin > System Settings > GitHub. Required:

  • GitHub repository — owner/repo format (e.g. pueteam/QRY).
  • Personal access token — with repo scope. Store as a secret; the token is encrypted at rest.
  • Default labels — applied to every issue QRY creates (e.g. from-tenant, triage).
  • User-facing prefix — added to the issue title (e.g. [acme] so engineering can spot which tenant reported it).

Click Test to confirm the token works. The test creates a draft issue in the repo (and immediately closes it).

Triggering a refresh​

In Admin > Issues, click Sync from GitHub. QRY pulls every issue from the configured repo and updates its local mirror. Closed issues, comments, and label changes flow back. The sync takes seconds for small repos, minutes for large ones (paginated API calls).

A scheduled sync runs nightly by default — Admin > System Settings > GitHub > Schedule.

How users report​

In any conversation or page, the user clicks Help > Report Issue. They get a form asking for:

  • Title — required.
  • Description — what happened, what they expected.
  • Attach conversation (optional) — sends the conversation id along so engineering can debug with full context.

Submitting creates a GitHub issue and shows the user a confirmation with the issue URL.

Per-tenant prefix​

If you run multiple tenants and they all sync to the same GitHub repo (say, your support tracker), set a different prefix per tenant. Issues from acme.qry.dev open with [acme] in the title; issues from customer-b.qry.dev open with [customer-b]. Engineering can filter / triage by tenant.

Security considerations​

The GitHub token in admin settings has repo scope. That's enough to write any issue to the repo, including malicious content if compromised. Mitigations:

  • Use a dedicated GitHub bot account with access only to the issue repo.
  • Don't reuse the token elsewhere.
  • Rotate the token periodically.
  • Audit the integration's activity in Admin > Audit log.

The issue body can contain user-supplied text. Filter / sanitise on the engineering side before reposting elsewhere — XSS risk is minimal in plain GitHub but anywhere you pull the body into HTML, escape it.

Common issues​

Reports not appearing in GitHub. Token expired or rate-limited. Check the integration's last-sync log in Admin > System Settings > GitHub > Status.

Status changes in GitHub aren't reflected in QRY. The on-demand sync hasn't run since the change. Trigger a manual sync, or set the schedule shorter.

Duplicate issues filed by the same user. QRY doesn't dedupe. Engineering can close-as-duplicate in GitHub; QRY will reflect that on the next sync.

Issue body too long → GitHub rejects. GitHub caps issue bodies at 65 KB. If QRY is attaching a large conversation, it truncates and adds a "…truncated, see QRY conversation <url>" link instead.

Want a public-facing tracker but private user data. Don't sync to a public repo. Or sanitise reports on the engineering side before mirroring publicly.

See also​

QRYA product of IXEN.