GitHub Integration
Link branches, commits, and pull requests to Decuga tasks. Tasks automatically move to In Progress when code is pushed, and pull request events are available to automation rules, so you decide what happens next, such as creating a review sub-task.
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.
Branch push
Branch linked to task + task moves to In Progress
Commit push
Each commit linked to every referenced task
PR opened
PR linked, task moves to In Progress, and the "Pull / merge request is opened" automation trigger fires
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 (recommended): Connect with GitHub
Authorize Decuga
In your Decuga project, go to Integrations → Connections and click Connect with GitHub. GitHub asks you to authorize Decuga (including any organizations you want to use - organization owners may need to approve access).
reposcope, because GitHub does not offer a narrower permission for managing repository webhooks. The token is stored encrypted and is only used to list your repositories and create or remove this project’s webhooks. You need admin access on a repository to connect it.GitHub access tokens issued to Decuga do not expire, so the connection keeps working until it is revoked - there is nothing to renew. Webhooks that Decuga has already created keep delivering events even if the token is later revoked. To revoke access, go to GitHub → Settings → Applications → Authorized OAuth Apps → Decuga PM, or remove the integration in Decuga. After revoking, click Reconnect to manage repositories again.
Pick repositories
Back in Decuga, the GitHub card shows every repository you administer. Search, tick the ones you want, and click Connect selected - up to 100 at a time. Decuga creates a webhook on each repository (Push and Pull request events, JSON, with a signing secret) and marks it Connected.
Later, tick a connected repository and use Remove webhookto disconnect it. Only this project’s webhook is removed.
Verify
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.
Manual setup
Use this if you cannot or do not want to authorize Decuga on GitHub. Click Set up manually next to the connect button (it is the default when your Decuga administrator has not configured GitHub OAuth). No GitHub App, OAuth, or Personal Access Token is needed.
Install the GitHub connector in Decuga
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:
https://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
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.
Existing webhooks & repositories shared by several projects
You already added webhooks by hand
Authorizing with GitHub keeps your existing installation and webhook secret, so your current webhooks keep working. When you connect a repository that already has a webhook pointing at this project, Decuga recognises it by URL and re-keys it (shown as “existing webhook adopted”) instead of creating a duplicate.
One repository, several Decuga projects
Each Decuga project has its own webhook URL and secret, so the same repository can feed any number of projects. The repository list shows “also in N other projects”for information. Connecting or removing a webhook in one project never touches another project’s webhook. Each project only reacts to task codes that exist in that project. GitHub allows up to 20 webhooks per repository.
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.
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 events → Automation rules
Opening, reopening, merging or closing a PR that mentions a task code does not create anything by itself. Each one fires an automation trigger, and you choose what to do in Automations. For example, a rule on Pull / merge request is opened with the action Create a sub-task titled “Review PR: {{prTitle}}”, assigned to The request’s reviewer, gives each PR a review sub-task. The reviewer is found by matching the PR’s requested reviewer to a project member’s name or email prefix. Rules can also check the repository, branch or author before they run.
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.
A repository is missing from the list, or connecting it fails.
Only repositories where you have admin access (and that are not archived) are listed. For organization repositories, an owner may need to approve Decuga under GitHub → Settings → Applications → Authorized OAuth Apps, or the organization may restrict OAuth apps. If GitHub reports the token as revoked, click Reconnect and authorize again.
Do I need to re-authorize GitHub periodically?
No. GitHub tokens issued to Decuga do not expire. You only need to reconnect if you (or an organization owner) revoke Decuga's access on GitHub. Existing webhooks continue to deliver events in the meantime.
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.
No review sub-task was created after opening a PR.
Decuga no longer creates one on its own. Add an automation rule on "Pull / merge request is opened" with the action "Create a sub-task". The PR title or source branch must also contain a valid task code, and the rule must be enabled. The rule's run history shows whether it ran and any error.
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.