GitHub Integration
Report problems and search complaints from GitHub issues and pull requests.
Connect GitHub repositories to Complaintr and let users report problems or search complaints by mentioning the bot in issue and pull request comments.
What It Does
When a repository is linked to a Complaintr application, any user can
comment @complaintrbot report <description> on an issue or pull request. The bot creates a
structured complaint with GitHub context (repository, issue, comment author).
Prerequisites
- Your Complaintr account must have at least one registered application
- You must have admin access to install the GitHub App on your repositories
Setup
1. Install the GitHub App
Go to the GitHub App installation page and install the Complaintr app on the repositories you want to connect.
2. Link Repositories
- Go to Dashboard > Integrations > GitHub
- Click Connect a repository and finish the GitHub installation
- Select which Complaintr application the repository maps to
- Click Link next to each repository that should use that application
You can link multiple repositories to the same application, while each repository can be assigned independently.
Using the Bot
In any issue or pull request comment on a linked repository, mention @complaintrbot followed
by a command.
Supported Commands
| Command | Description |
|---|---|
@complaintrbot help | Show available commands and setup link |
@complaintrbot report <description> | Submit a complaint about the issue or PR |
@complaintrbot search <query> | Search existing complaints for the linked application |
@complaintrbot status | Check if the repository is connected |
Commands are case-insensitive for the mention and keyword. Extra whitespace is ignored.
Examples
@complaintrbot report The deployment pipeline fails on staging when an environment variable is missing.@complaintrbot search login timeout@complaintrbot statusWhat Gets Recorded
When a complaint is created, the following GitHub context is stored:
- Repository ID, full name, and URL
- Issue ID, number, title, and URL
- Comment ID and URL
- Issue author and comment sender
- GitHub App installation ID
The complaint appears in your Complaintr dashboard with sourceAgent set
to github.
Expected Responses
| Scenario | Bot Reply |
|---|---|
@complaintrbot report ... (linked) | Complaint registered. Complaint ID: ABC123 |
@complaintrbot report (no description) | Please describe the problem. Example: ... |
@complaintrbot report ... (not linked) | This repository is not connected to a Complaintr application. |
@complaintrbot search ... | Matching complaints or a no-results response |
@complaintrbot help | Command list with setup link |
@complaintrbot status (linked) | This repository is connected to Complaintr application **MyApp**. |
@complaintrbot status (not linked) | This repository is not connected... |
Unlinking a Repository
- Go to Dashboard > Integrations > GitHub
- Find the repository in the linked list
- Click the unlink icon to remove the mapping
Privacy and Security
- The bot only responds to
@complaintrbotcommands in issue and pull request comments - Bot-authored comments are ignored (prevents loops)
- Commands inside code blocks are not executed
- Complaints include only the metadata described above
- Webhook deliveries are verified via HMAC-SHA256 signature
- Duplicate deliveries are skipped
Troubleshooting
Bot does not respond
Verify the repository is linked to a Complaintr application in Dashboard > Integrations > GitHub. The bot only processes commands in linked repositories.
"Not connected" response
Your repository is not linked. Go to Dashboard > Integrations > GitHub and link the repository to an application.
"Unknown command" response
Check the command spelling. Supported commands are help, report, search, and
status. The bot is case-insensitive but the command word must be correct.
For other issues, see Troubleshooting or FAQ.