Habitica GitHub integration FAQ

It is a simple two-step process. First, install our GitHub App on the repositories you want to track. Second, log in to the Dashboard and enter your Habitica User ID and API Token. Here is where Habitica keeps them.

You're now ready to configure your triggers and start earning Gold/XP!

Once linked, head to the Dashboard to create Triggers. You decide the rules: "When I [Push Code] to [This Repo], score a [Medium] task". You can create as many triggers as you want for different events and repositories. For ready-made examples, see the coding habit recipes.

Absolutely. Since Octogriffin works as a GitHub App, you explicitly grant it access to specific repositories - whether they are public or private. We process the webhooks securely regardless of visibility.

We use GitHub Webhooks to listen for activity on your connected repositories. When you push code, open a pull request, or close an issue, GitHub notifies our servers.

We then analyze the event metadata (like commit size or issue complexity) to calculate a fair XP reward. Finally, we use the Habitica API to score a custom task on your account, instantly granting you Gold and Experience.

Your API credentials are encrypted at rest in our database using industry-standard encryption (AES-256). We never expose them in the frontend, and they are only decrypted momentarily by our server to send requests to Habitica on your behalf.

Read-only, and we never use it. GitHub only sends push events to apps that can read a repository's contents, so the Octogriffin GitHub App asks for read-only Contents access. It can never change your code. Octogriffin never downloads your files: it only uses the event details GitHub sends, like who pushed and how many commits, and stores a record of which events earned you rewards, never your code or commit messages. The installation guide lists every permission the app asks for.

We take data sovereignty seriously. Our primary database is hosted in Frankfurt, Germany (via Neon), ensuring your data remains within the EU and is protected by strict privacy standards.

You remain in control. You can uninstall the GitHub App from your repository settings at any time, which immediately stops all data flow. You can also regenerate your Habitica API Token by resetting the password of your Habitica account to invalidate the old credentials instantly.

A single push rewards each trigger at most 10 times, no matter how many commits it contains. You can also give a trigger a cooldown, so it rests for a while after it scores. A daily cap sets the most a trigger can score in a Habitica day. Spam detection leaves out empty commits and pull requests you close straight away, and bots like Dependabot never earn rewards. These all come with the Anti-Cheese update. Beyond that, we operate on the "honor system."

Yes! In the Control Freak update, you can set the Trigger Action to "Punish" (Down). This is perfect for discouraging bad habits, like pushing directly to the main branch or breaking the build.

No. Deleting a trigger in Octogriffin only stops future events from processing. We do not delete your history or the associated task in Habitica. You can keep the task as a record or delete it manually in the Habitica app.

First, check if your trigger is set to Active in the dashboard. Second, ensure the GitHub App is actually installed on that specific repository. Finally, GitHub webhooks can sometimes have a delay of a few seconds.

Did you recently reset your password or regenerate your API Token in Habitica? If so, your old credentials are invalid. Please go to the Settings page and update your API Token to resume syncing.

Octogriffin tries to find a task with the exact title you specified. If you have multiple tasks with the same name (e.g. two tasks named "Coding"), we might score the wrong one. We recommend giving your tasks unique names or using the Task Alias feature in the Advanced Settings of your trigger for 100% precision.

Check your Dashboard. You might have created two overlapping triggers (e.g., one Global trigger and one Repository-specific trigger) that both fire on "Push" events. Disable one of them to fix the issue.