GitHub Issues Integration

NirmIQ can automatically create GitHub Issues from user bug reports and feature requests. This provides better tracking than email without requiring SMTP or Resend configuration.

Benefits Over Email

Feature	GitHub Issues	Email
Trackable	Issue numbers, labels, milestones	Subject lines only
Searchable	Full-text search, filters	Limited
Workflow	Link to PRs, auto-close on merge	Manual
No spam filters	Always delivered	May be filtered
Public accountability	Users can see status	No visibility
Configuration	Just a token	SMTP/Resend setup

Setup Instructions

Step 1: Create a Dedicated Issues Repository (Recommended)

For security, create a separate public repository for user-reported issues:

1. Go to GitHub and create a new repository: nirmiq-issues
2. Make it public (so users can view their submitted issues)
3. Add labels: bug, enhancement, feedback, user-reported, triage-needed

Why a Separate Repository?

Using a dedicated issues repo keeps user reports separate from your development workflow. This prevents:

• Cluttering your main repo with user reports
• Accidentally exposing internal development issues
• Users seeing unreleased features in issue discussions

Step 2: Create a GitHub Personal Access Token (PAT)

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click Generate new token
3. Configure:
   • Token name: NirmIQ Feedback Bot
   • Expiration: 1 year (set a reminder to rotate)
   • Repository access: Select Only select repositories → choose nirmiq-issues
   • Permissions:
     • Issues: Read and write
     • (No other permissions needed)
4. Generate and copy the token

Step 3: Configure Environment Variables

Add these to your Railway/Vercel environment:

# Required
GITHUB_ISSUES_ENABLED=true
GITHUB_ISSUES_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_REPO_OWNER=your-org-name
GITHUB_REPO_NAME=nirmiq-issues

# Optional: Also send email notifications
RESEND_API_KEY=re_xxxx  # If you want email backup

Step 4: Verify Integration

1. Go to Admin → Feedback → Integration Status
2. Confirm GitHub Issues shows as enabled
3. Submit a test bug report
4. Check your issues repo for the new issue

How It Works

When a user submits feedback:

User → Feedback Button → API → GitHub Issues → Issue Created
                            ↓
                     Also saved to DB
                            ↓
              (Optional) Email notification

Issue Format

Created issues include:

## Bug Report

**Submitted by:** j***@c*****.com
**Feedback ID:** #42
**Date:** 2026-01-02 15:30 UTC

---

### Description

[User's description here]

---

### Context

| Property | Value |
|----------|-------|
| URL | `/dashboard/project/123` |
| Browser | `Chrome 120 on Windows` |
| Screenshot | Available (internal) |

---

Automatically created by NirmIQ Feedback System

Privacy Protection

• Email anonymization: User emails are masked (e.g., j***@c*****.com)
• No screenshots uploaded: Screenshots stay on your server, not GitHub
• Feedback ID reference: Internal tracking ID for cross-referencing

Labels

Issues are automatically labeled:

Label	When Applied
bug	Bug reports
enhancement	Feature requests
feedback	General feedback
user-reported	All user submissions
triage-needed	All new issues

Admin Dashboard

Check Integration Status

GET /api/feedback/integration-status

Returns:

{
  "github_issues": {
    "enabled": true,
    "token_configured": true,
    "repo_owner": "your-org",
    "repo_name": "nirmiq-issues"
  },
  "resend_email": {
    "enabled": false
  },
  "smtp_email": {
    "enabled": false
  },
  "recommended": "github_issues"
}

Troubleshooting

Issues Not Being Created

1. Check token permissions: Must have issues:write on the target repo
2. Verify repo exists: Token must have access to the specified repository
3. Check environment variables: All 4 variables must be set correctly

Token Expired

1. Generate a new PAT following Step 2
2. Update GITHUB_ISSUES_TOKEN in your environment
3. Restart the API server

Wrong Repository

If issues appear in the wrong repo, verify:

• GITHUB_REPO_OWNER matches your organization/username exactly
• GITHUB_REPO_NAME matches the repository name exactly

Security Best Practices

1. Use fine-grained tokens: Only grant issues:write permission
2. Limit repository access: Token should only access the issues repo
3. Rotate tokens annually: Set calendar reminders
4. Separate repos: Never use your main development repo for user issues
5. Audit regularly: Review created issues monthly for abuse

Related Documentation

• Feedback System Overview
• Admin Dashboard
• Audit Logs