Skip to content
Docs menu

Link GitHub pull requests to Venom Tasks issues

Connect a GitHub webhook so pull requests and commits that name an issue key show on the issue, move issues through draft, open, review, ready to merge and merged by each team's rules and target-branch rules, comment back on the pull request, and start an issue when you copy its branch name.

View .md

Put an issue key in a branch name, a pull request's title or body, or a commit message, and the pull request or commit shows on the issue. GitHub sends the events to Venom Tasks through a webhook your organisation adds itself.

Connect

Open Settings → GitHub (/tasks/settings/github). An owner or admin presses Connect GitHub. Venom makes a random webhook secret and shows it once. If you register your own GitHub App, paste its webhook secret instead.

Then, in the GitHub repository or organisation, go to Settings → Webhooks → Add webhook:

Field Value
Payload URL the URL on the settings page, https://<cloud>/api/integrations/github/<id>/webhook
Content type application/json (form-encoded works too)
Secret the secret Venom showed
Events Pull requests, Pushes and Issues. Add Pull request reviews and Check suites (or Check runs) for review and checks state

GitHub sends a ping when you save the webhook; the settings page shows the last event it received.

Every delivery is checked against the secret (X-Hub-Signature-256, HMAC-SHA256, compared in constant time). A delivery with a wrong signature gets 401 and changes nothing. Make a new secret replaces it; paste the new one into GitHub. Disconnect forgets the secret and the token. Links already made stay on their issues.

The secret and the token are sealed in the cloud's vault (VENOM_VAULT_KEYS). A cloud without a vault key cannot connect GitHub.

What links an issue

Where the key is What it does
Branch name (feat/eng-123-login) links, and merging closes the issue
Pull request title links, and merging closes the issue
Fixes ENG-123, closes, resolves (also fixed, closing, completes) anywhere links, and merging closes the issue
Refs ENG-123, part of, related to anywhere links only, even when the branch names the issue
A bare key in a pull request body or a commit message links only

Lists work: Fixes ENG-1, ENG-2 and ENG-3. A pull request or commit links at most 20 issues. Keys that name no issue in your organisation are ignored. An old key (the issue moved team, or the team was renamed) still resolves.

"Closes the issue" means the team's merge rule applies, when the team has one. Without rules, nothing moves.

The issue view

The issue's Pull requests section lists each linked pull request: title, repository and number, state (draft, open, merged or closed), checks (running, passed, failed) and review (review requested, approved, changes requested) when GitHub sent them, and refs when merging it will not close the issue. The API also carries the pull request's size as GitHub last said it (additions, deletions, changedFiles). Linked commits are under it, folded. The activity feed says "GitHub linked the pull request acme/web#12".

Each row's ⋯ menu opens the pull request on GitHub, copies its link, or Unlinks it: use this when a key linked the wrong issue. The row leaves the issue and stays off when GitHub sends the same event again (or any later event); only an edit of the pull request's title or body that still names the issue links it again. Unlinking is in the activity feed. A row also shows the branch the pull request merges into, and revert for a revert (below).

On the issue list, the Pull requests display property (Display → Display properties) shows a chip with the most active pull request's state and number, and how many more there are.

Workflow rules

Each team sets, on the settings page, the state a linked issue moves to at each pull request stage. All are off by default:

Stage When a pull request is here
Draft opened as a draft, or converted back to one
PR opened open and not a draft: opened, reopened or marked ready for review
Review a review was requested, or someone reviewed (commented, asked for changes, approved without green checks)
Ready to merge not a draft, approved, and its checks passed (or none reported). Fires only when the team also set Review
Merged merged. A commit with a closing word pushed to the repository's default branch counts as merged there

Draft to Ready to merge take an unstarted or started state; Merged a started or completed one. Ready to merge is Venom's own reading of the payloads: an approved review plus checks. GitHub's mergeable_state is not used, because webhooks often send it as unknown, and branch protection Venom cannot see (required reviewers, code owners) is not checked.

How the stages move an issue:

  • All linked pull requests count. The stage that counts is the least advanced of the issue's pull requests whose link closes it (a closing word, or the key in the branch or title). A pull request closed without merging drops out; Merged needs every remaining one merged. So with two closing pull requests, merging the first leaves the issue where it is and merging the second completes it. Refs links never move an issue.
  • Reverts never move an issue. A pull request from GitHub's Revert button (a revert-<n>-… branch, or a title starting Revert ") links and shows revert, but does not count. A merged revert does not reopen the issue; move it yourself if the work is to be redone.
  • Forward only. A move goes forward through the workflow (by state type, then by the state's order in the team), never out of a completed or canceled state, and only Merged may complete an issue.
  • A stage that is off falls back to the nearest earlier stage that is on: a pull request opened with reviewers already requested still moves the issue by PR opened when Review is off. Merged never falls back.
  • Only when the stage changes. An issue moves when an event changes its stage, so GitHub sending the same event twice changes nothing, and a person who moves the issue back is not overruled until its pull requests reach a new stage. Every move is an ordinary state change: change it back as you would any other.
  • Order does not matter. Each pull request event carries GitHub's updated_at; a delivery older than one already applied is ignored, and a merged pull request stays merged. A merge that arrives before "ready for review" still ends merged.

The activity feed shows each move as two rows: one that names the pull request, the stage and the branch rule that decided it ("acme/web#12 reached Merged into staging (branch rule staging)"), then the state change, made as GitHub. Moves notify subscribers like any status change.

Branch rules

Branch rules (n) on a team's row overrides a stage by the branch the pull request merges into (pull_request.base.ref; for a closing commit, the branch it was pushed to). Each rule has a pattern, a stage, and a state or No action. A pattern is a branch name (main) or a regular expression between slashes (/^release\/.+$/; anchor it yourself, it is matched as written). Rules are checked in order and the first that matches the stage and the branch wins; No action stops there. With no match, the team's stage setting applies. A team holds at most 50 rules; a pattern is at most 200 characters and must compile. Reorder with ↑ and ↓.

Example: Merged → Done for the team, and a rule staging · Merged → In QA. A pull request merged into staging moves its issue to In QA; the one that later merges into main moves it to Done.

Rules belong to one team. A sub-team does not inherit its parent's GitHub rules, because its workflow states are its own: set them on the sub-team's row.

GitHub issues as intents

A GitHub issue is a Tasks issue. With the Issues event on, Venom Tasks follows GitHub issues the same way it follows pull requests:

  • Linking. A GitHub issue whose title or body names a Tasks key (ENG-123) links to that issue. Otherwise, when you pick a Team for new GitHub issues under Settings → GitHub → Intents, opening one creates a Tasks issue in that team. With neither, the event is ignored.
  • Following. Editing the title updates the Tasks issue. Closing it moves the Tasks issue to the team's first completed state (canceled when GitHub says "not planned"). Reopening moves a closed one back to the first unstarted state.
  • Approving. When the approve label (default status:approved) is applied, or an issue is opened with it, the Tasks issue is delegated to the agent you chose on the same page. The agent's stream (see Venom Tasks for agents) sends it within seconds, so no poller is needed. With no agent chosen, the label changes nothing.

Moves are made as GitHub. The webhook is the only inbound path; Venom reads nothing else from GitHub for this.

Moving a card sets the label

Each team also maps three workflow states: Approved, Iterate and Rejected (all off by default). When an issue linked to a GitHub issue moves into one of them, from the board, the list, the API or an agent, Venom puts that state's label on the GitHub issue (status:approved, status:iterate or status:rejected by default; the names are settings) and takes the other two off. This uses the token from the next section; without one, nothing is sent. The move is never undone when GitHub fails to answer. Anyone who may change the state may move the card.

The token, and what Venom writes to GitHub

Webhooks carry state as it changes. The settings page also takes a GitHub token: a fine-grained token on the repositories you link, with Pull requests: read and write (comments, closing), Issues: read and write (the status labels above) and Checks and Commit statuses: read. With read access only, the reads work and the writes fail (the last failure shows on the settings page). The token is sealed in the vault and used only for these calls, all to api.github.com:

Call When
Read a pull request, its reviews and checks a member presses Refresh on an issue (at most 10 pull requests; it never moves the issue)
Read a pull request's changed files someone opens a pull request card in Venom Chat (From a channel message to a merged pull request); not stored
Put a status label on a GitHub issue a card moves into a team's Approved, Iterate or Rejected state (above)
Comment on a pull request, or edit that comment Comment on linked pull requests is on and a pull request links an issue for the first time, or one is unlinked (below)
Close a pull request Canceling an issue closes its pull requests is on and a person cancels an issue (below)

Without a token, the cloud only receives webhooks and writes nothing to GitHub.

Comment on linked pull requests

On by default once a token is saved (Settings → GitHub → Automations). When a pull request links an issue for the first time, Venom posts one comment on it: each linked issue's ID, title and Venom link. When more issues link, or one is unlinked, Venom edits that same comment, so a pull request never gets a second one. Issues in a private team appear by ID and link only, never by title. If someone deletes the comment, Venom does not post it again. A failed call shows on the settings page and is not retried; it never delays the webhook.

Canceling an issue closes its pull requests

Off by default. When a person moves an issue to a canceled state (marking it a duplicate does too), Venom closes its open and draft pull requests whose link closes it, except one that also closes another issue still open. It is a GitHub "close": never a merge, never a branch delete. Each close is an activity row on the issue ("closed acme/web#12 on GitHub"). A cancel made by GitHub, a triage rule or an agent closes nothing.

Copy a branch name

Mod+Shift+. (or Copy git branch name in an issue's menu and ⌘K) copies the issue's branch name. The default is eng-123-fix-the-login-loop. An admin can change the format under Settings → GitHub → Automations → Branch name format, with the tokens {identifier}, {title} (lower case, dashes, at most 48 characters) and {username} (the part of your email before the @). For example {username}/{identifier}-{title} gives ada/eng-123-fix-the-login-loop. A format must hold {identifier}, so a branch made from it always links its issue.

With your preference Copying a branch name starts the issue on (the default; Settings → Preferences), copying also assigns the issue to you when nobody has it and moves it from triage, backlog or unstarted to its team's first started state, as one edit: Mod+Z undoes both, and the toast says what changed. With several issues selected, only the first one's branch is copied and only that one starts.

API

All under the Tasks session (the console's cookie). Changes need org:manage, except the refresh (write access).

Endpoint What
GET /tasks/api/github the connection (payload URL, secret and token hints, last event, the automations, the branch name format, the last failed call to GitHub) and the teams' rules with their branch rules
POST /tasks/api/github {webhookSecret?, rotateSecret?, token?}: connect or change; answers secret once when Venom made one; token: null removes the token
PATCH /tasks/api/github {linkback?, closeOnCancel?, branchFormat?}: the automations and the branch name format (null restores the default); 409 until GitHub is connected
DELETE /tasks/api/github disconnect
PUT /tasks/api/github/rules {teamId, draftStateId?, openStateId?, reviewStateId?, readyStateId?, mergeStateId?, branchRules?, approvedStateId?, iterateStateId?, rejectedStateId?}; null turns a rule off and a key left out keeps its value; branchRules ([{pattern, stage, stateId}], stateId: null for no action) replaces the team's ordered list
PUT /tasks/api/github/intents {approveLabel?, iterateLabel?, rejectLabel?, agentId?, teamId?}: the labels, the agent approved issues go to and the team new GitHub issues land in (409 until GitHub is connected)
GET /tasks/api/github/summary the list chips: {issues: {<issue id>: {count, state, repo, number}}}
GET /tasks/api/issues/{id}/pull-requests the issue's pullRequests and commits; a pull request has additions, deletions and changedFiles (null until GitHub said them)
POST /tasks/api/issues/{id}/pull-requests refresh them from GitHub with the saved token (409 no_token without one)
DELETE /tasks/api/issues/{id}/pull-requests/{prId} unlink a pull request or commit (write access); it stays unlinked when GitHub sends the same event again
POST /api/integrations/github/{id}/webhook GitHub's deliveries: pull_request, issues, push, pull_request_review, check_suite, check_run, ping; anything else is answered 200 and ignored

The MCP tools are tasks_github_rule_set (stages and branch rules), tasks_github_update (the automations) and tasks_pullrequest_unlink. The stages need no webhook events beyond those in Connect: the Pull requests event carries drafts, ready for review, review requests, the base branch and updated_at.