GitHub and other forges

Herding Cats integrates with GitHub, and other similar Git forges, to automatically create a task when issues and/or pull requests are opened on repositories you care about.

Tip

If you don’t know what any of these things are, don’t worry, this integration is opt-in and not something you need to use.

What the webhook does

Once you’ve configured a webhook for a repository or organisation, a task will be automatically created whenever an issue or pull request is open, depending on what events you subscribed to.

These tasks will go straight into your main list, with a title that looks like ‘Triage “Some issue” on your-user/your-repo’. The task notes will contain a link to the issue/pull request. You probably want to immediately rename the task to something meaningful, and update the status and other metadata to match what the work will involve for you.

If you’d like the ability to add tasks from other events, or have any other feedback or ideas about the git forge integration, please let me know.

Setting up a webhook

There’s 2 parts to using webhooks. Inside Herding Cats:

• Generate a webhook URL from your API Settings page, or copy the one you’ve generated previously,
• (optional but recommended) generate a webhook signing secret on your API Settings page, or copy your existing one. Using a secret means you can be sure webhooks events that create tasks for you are definitely sent by the integration you’ve set up.

Note

You can only have one active webhook URL and secret at a time in your account. You can use this for as many webhook integrations as you like, but if you need to revoke your webhook URL or secret, all your integrations will be affected. If you set a secret in your account, you must supply it to all of your webhook integrations.

In GitHub or your git forge of choice, set up one or more repositories or organisations to send webhooks to your webhook URL, signed with your secret if you created one. Precisely how to do this depends a bit on your forge, but the steps are broadly the same:

• find where there’s a webhook option in your forge (often repository -> settings -> webhooks), on a repository or organisation
• add your webhook URL as the “target URL” or “payload URL”
• add your secret if you’ve set one up, as the “secret” or “signing secret”
• if there’s a setting for content type, pick application/json
• pick whether you want tasks for issues, pull/merge requests, or both, by choosing those as the “events” or “triggers” for that webhook integration.
• hit “add webhook” and do something on a repository that you expect to trigger the webhook, check it made it through to your task list

Here’s GitHub’s docs for extra context. The integration should work for any forge with a GitHub-compatible API, including Codeberg, Forgejo, Gitea, as well as GitLab. If you have any problems or would like us to add support for a forge that isn’t already working, please get in touch.