GitHub Integration Guide
The Topiq GitHub integration turns customer bugs and feature requests captured in Topiq into GitHub issues, and shows you in Topiq when they are fixed. You connect it once, with a fine-grained personal access token. This guide covers how to add, use and remove the integration.
The token works like a spare key that opens only the issues on the repositories you pick. Topiq can't see or change your code.
Before you start
- You need a Topiq account. Topiq is available at app.topiq.work.
- You need a GitHub account that can open issues in your repositories. Issues Topiq files are shown as written by this account, so a shared team account is a good choice.
- Connecting GitHub is done once for the whole workspace, by a Topiq owner or admin. If that isn't you, you can create the token and send it to your Topiq admin.
1. Adding the GitHub integration
Step 1: Open the token page in GitHub
- In GitHub, click your profile photo (top right) and choose Settings.
- At the bottom of the left sidebar, click Developer settings.
- Go to Personal access tokens → Fine-grained tokens and click Generate new token.
Step 2: Name it and choose the owner
- Name it Topiq.
- Under Resource owner, choose your company's organization, not your personal account.
- Set the expiration as long as your organization allows, and note the date. When it expires, Topiq stops filing issues until you add a new token.
Step 3: Choose the repositories
- Under Repository access, choose Only select repositories and pick the repositories where bugs and feature requests should go.
Step 4: Choose what Topiq can do
| Permission | Set to | Why Topiq needs it |
|---|---|---|
| Repository → Issues | Read and write | Opens issues and checks when they are closed |
| Repository → Metadata | Read-only (added automatically) | Required by GitHub for every token |
| Organization → Projects (optional) | Read-only | Only if you track work on a GitHub Project board; Topiq then shows which column each item is in |
Leave every other permission as No access.
Step 5: Generate and copy the token
- Click Generate token and copy the code that starts with github_pat_. GitHub shows it only once.
- If your organization requires approval for new tokens, the token stays pending until an organization owner approves it. Ask them to approve it before you continue.
- Treat the token like a password. Don't paste it into email or chat. If you are handing it to a colleague, use a password manager's secure share.
Step 6: Add the token and your repositories to Topiq
- In Topiq, open Integrations, find the GitHub card, paste the token and click Save changes.
- Go to Workspace settings → Business lines. For each product, enter its repository (for example your-org/your-repo) and, if you use one, the link to its GitHub Project board.
2. Using the GitHub integration
Filing an issue
- Open a signal (a bug or feature request) in Topiq and file it as a GitHub issue in one click. It goes to the repository of the signal's business line.
- If the issue already exists in GitHub, link it to the signal instead of filing a new one.
Keeping status in step
- Topiq checks GitHub about every 15 minutes.
- When an issue is closed as completed, its signal moves to In review, so someone can confirm the fix before marking it done. An issue closed as not planned marks the signal rejected, and a reopened issue reopens it.
- If you connected a Project board, open issues follow the board's columns, such as To do and In progress.
What Topiq accesses
- Only the issues, and optionally the Project board, of the repositories you picked in Step 3. Topiq doesn't read or change your code, branches or pull requests.
3. Removing the GitHub integration
Delete the token
- Open Settings → Developer settings → Personal access tokens → Fine-grained tokens in GitHub and delete the Topiq token. Topiq's access stops immediately.
- If you'd also like the token cleared from your Topiq workspace, email support@topiq.work.
What happens after removal
- Topiq stops filing issues and stops updating signals from GitHub.
- Issues already filed stay in GitHub, and signals keep their links to them.
- To reconnect, follow the steps in Adding the GitHub integration again.
4. Troubleshooting
- Filing an issue fails. The token may have expired, be waiting for organization approval, or not include that repository. Check the token in GitHub, or create a new one.
- The Project board columns don't show. The token needs Projects: Read-only under Organization permissions. Topiq shows this on the business line's settings when it can't read the board.
- A signal's business line has no repository. Add the repository under Workspace settings → Business lines.
Support
For help with the GitHub integration, email support@topiq.work. Our team is available Monday through Friday, 9:00 AM – 5:00 PM PT, excluding major U.S. holidays, and responds within 3 business days.