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.
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.
Refslinks never move an issue. - Reverts never move an issue. A pull request from GitHub's Revert button (a
revert-<n>-…branch, or a title startingRevert ") links and showsrevert, 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.