GitHub

Push themes from ftools directly to GitHub Issues with one click.

Setup

Step 1 — Add a GitHub integration

1. Open the survey and go to the Integrations tab.
2. Click Add integration and select GitHub.

What you see next depends on whether you have already connected a GitHub account to ftools:

• First time: click Connect GitHub account. GitHub will open in a new tab — select the account or organization to install the app on, choose which repositories the app can access, and click Install. After installation you will be returned to ftools automatically.
• Already connected: pick the existing account from the dropdown. To use a different account, click Add another account and follow the install flow.

The same GitHub account can be reused across multiple surveys — installing the app once is enough.

Step 2 — Configure the integration

After picking a GitHub account, fill in the integration form:

1. Repository — pick a repo from the dropdown (the list is populated automatically from the repos the app has access to).
2. Labels (optional) — labels that will be applied to every created issue (e.g. feedback, bug). Labels must already exist in the repository.
3. Assignees (optional) — GitHub usernames to assign to every created issue. Assignees must have access to the repository.
4. Name (optional) — internal label, e.g. GitHub — Backend repo.
5. Click Save.

The integration is created and ready to use immediately.

Step 3 — Done

On any theme page you will see a Push to GitHub button — clicking it creates a new Issue in the selected repository.

The Issue will look like this:

Title:

🌙 Dark mode support

Body:

Users across plans ask for a dark theme...

**Type:** feature_request
**Findings:** 23

### Evidence
- "Please add dark mode"
- "Bright UI hurts my eyes at night"
- ...

---
[View theme in feedback.tools](https://feedback.tools/surveys/.../responses?tab=themes)

Multiple integrations to the same repository

You can create several GitHub integrations on the same survey pointing at the same repository — for example, one with labels: ["bug"] and another with labels: ["feature"]. Each one becomes a separate Push to GitHub option on the theme page, so you can route different themes to different label sets.

Identical clones (same account, same repo, same labels, same assignees) are blocked.

Managing the integration

• Pause temporarily — toggle the integration off in its settings; configuration is kept.
• Change repository / labels / assignees — edit the integration.
• Remove — delete the integration. The GitHub App stays installed on your GitHub account and can be reused for other integrations.
• Remove the GitHub account from ftools — in the GitHub accounts list, delete the connected account. This is only allowed when no integrations use it.
• Fully revoke access — uninstall the app from your GitHub account settings. ftools detects this automatically on the next push.

Repository becomes unavailable

If the repository is deleted, renamed, or the app loses access, the integration shows a Repository unavailable status and pushes start failing. To recover:

• Pick a different repository — edit the integration and change the repo.
• Restore access on GitHub — open your GitHub app settings and grant access to the repository again. On the next push the integration will recover automatically.

App needs reauthorization

If the GitHub App was uninstalled or its tokens were revoked, the connected account shows Reconnect required and integrations using it stop working. Click Reconnect on the account and reinstall the app on the same GitHub account — all integrations using that account will resume working.

Reference

Integration settings

How it works

The GitHub integration is manual push: nothing is sent until you click Push to GitHub on a theme page. There is no automatic delivery on new responses.

Authentication uses a GitHub App — you don't need to create a personal access token. Installing the app once on a GitHub account lets you reuse it across multiple integrations and surveys.

Tokens are valid for 8 hours and refresh automatically in the background. If the connected account hasn't been used for 6 months, you'll be asked to reconnect it.

Statuses

You will see one of these statuses on an integration:

What gets created in GitHub

Clicking Push to GitHub on a theme creates a new Issue:

Title: {emoji} {theme name} — for example 🌙 Dark mode support.

Body (markdown):

• The theme description.
• Type (bug / feature_request / emotion) and total findings count.
• Up to 25 example findings as a bulleted list.
• If the theme has more than 25 findings, a "Showing 25 of N — View all →" link to the survey themes page.
• A backlink to the theme in ftools.

Labels and assignees are taken from the integration settings, if set.

The delivery is synchronous — you see the result (success or error) right after clicking the button. There are no automatic retries.

Permissions

The GitHub App requests a minimal set of permissions:

No organization or account permissions are required. During installation you choose which specific repositories the app can access.

Multiple integrations to the same repository

You can create several integrations on the same survey pointing at the same repository with different labels or assignees — for example one with labels: ["bug"] and another with labels: ["feature"]. Each appears as a separate Push to GitHub option on the theme page.

Fully identical integrations (same account, same repo, same labels, same assignees) are blocked.

Removing things

• Pause an integration temporarily — toggle it off in settings. Configuration is kept.
• Remove an integration — delete it from the integrations list. The connected GitHub account is not affected.
• Remove a GitHub account from ftools — only allowed when no integrations use it; otherwise you'll see which integrations depend on it.
• Fully revoke access — uninstall the GitHub App from your GitHub account settings. ftools detects this on the next push and marks the account as needing reconnection.

Delivery history

Every push is recorded as a delivery and shown in the Integrations section on the survey page, with status (success / failed) and any error returned by GitHub.