🐙

GitHub Integration

Link branches, commits, and pull requests to Decuga tasks. Tasks automatically move to In Progress when code is pushed, and a review sub-task is created every time a PR is opened.

Overview

The GitHub integration works via webhooks — GitHub sends a notification to Decuga every time you push or open a PR. Decuga reads the branch name, commit messages, and PR title, extracts any task codes (e.g. PROJ-42), and links the artefact to the matching task.

No GitHub App, OAuth, or Personal Access Token required. Decuga only needs a webhook secret you choose yourself — all event data arrives in the webhook payload.

Branch push

Branch linked to task + task moves to In Progress

Commit push

Each commit linked to every referenced task

PR opened

PR linked + review sub-task created, assigned to first reviewer

PR closed

PR state updated to closed / merged on the link card

Task code

Any code matching [A-Z]+-\d+ in branch, commit, or PR title

Deduplication

Same event delivered twice → link updated, not duplicated

Setup

Install the GitHub connector in Decuga

In your Decuga project, go to Project Settings → Integrations and click Connect GitHub. Enter one field:

Webhook Secret — any random string (you will paste this on GitHub in the next step)

After saving, Decuga shows you your Webhook URL:

text

https://app.decuga.com/api/webhooks/vcs/github/<your-project-id>

Create the webhook on GitHub

Go to your GitHub repository → Settings → Webhooks → Add webhook and fill in:

Payload URL — the URL from step 1
Content type — application/json
Secret — the same string you entered as Webhook Secret in Decuga
Events — select Let me select individual events, then tick Pushes and Pull requests

Make sure the Content type is application/json, notapplication/x-www-form-urlencoded. Decuga only accepts JSON.

Verify the connection

After saving, GitHub immediately sends a ping event. In GitHub → Webhooks → your new webhook, you should see a green checkmark under Recent Deliveries. The ping returns HTTP 200.

Push any branch that includes a task code in its name (e.g.git checkout -b feature/PROJ-1-test) and verify the task shows a Development section with the branch linked.

How linking works

Task code detection

Decuga scans branch names, every commit message subject, and PR titles using the regular expression \b([A-Z][A-Z0-9]+-\d+)\b. Any match is treated as a task code.

Examples

feature/PROJ-42-add-login     → PROJ-42
fix/ABC-7-null-pointer        → ABC-7
Fix auth bug [PROJ-42]        → PROJ-42 (commit message)
Add OAuth2 — closes PROJ-42   → PROJ-42 (PR title)
chore: update deps            → (no match)

Duplicate prevention

A link is unique per (task, provider, repo, type, reference). If GitHub retries a delivery, or you push to the same branch twice, Decuga updates the existing link rather than creating a duplicate.

Automations

Branch / commit push → In Progress

When a branch containing a task code is pushed (or a commit message references one), Decuga moves the task from To Do or On Hold to In Progress. Tasks already in a later state (In Review, Done, etc.) are never downgraded.

PR opened → Review sub-task

When a PR is opened and a task code is found, Decuga automatically creates a sub-task titled “Review PR: <PR title>” under the parent task, with status In Review. If the PR has a requested reviewer whose GitHub username matches a Decuga project member’s name or email prefix, the sub-task is assigned to them.

PR closed / merged → Link state updated

When a PR is closed or merged, the link card in the task’s Development section updates its state badge from open to closed or merged.

Troubleshooting

The webhook shows a red X on GitHub — what went wrong?

Check that the Webhook Secret on GitHub exactly matches the one you entered in Decuga. Also confirm the Payload URL and that the Content type is application/json.

My task code is not being detected.

Task codes must be uppercase letters followed by a hyphen and digits — e.g. PROJ-42. Lowercase codes like proj-42 are not matched. Make sure the code appears in the branch name, commit message, or PR title.

The review sub-task was not created after opening a PR.

Ensure the PR title or source branch contains a valid task code. If it does, check the backend logs for a "Failed to create review sub-task" error, which may indicate the project counter could not be incremented.

The task did not move to In Progress.

Tasks in In Progress, In Review, Ready for Deploy, or Done states are not changed. Only To Do, Internal Hold, and External Hold tasks are moved.