---
title: Link GitHub pull requests to Venom Tasks issues
description: 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.
section: cloud
order: 83
audience: [user, operator]
sources: [services/nodejs-cloud/lib/tasks/github, services/nodejs-cloud/components/tasks/github, services/nodejs-cloud/app/tasks/api/github, services/nodejs-cloud/app/api/integrations/github, "services/nodejs-cloud/app/tasks/api/issues/[id]/pull-requests", services/nodejs-cloud/migrations/0137_tasks_github.sql, services/nodejs-cloud/migrations/0162_tasks_github_intents.sql, services/nodejs-cloud/migrations/0314_tasks_github_automations.sql, services/nodejs-cloud/lib/tasks/github/intents.ts]
features: [cloud.tasks, cloud.page-tasks, cloud.api-integrations, cloud.migrations]
---

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 {#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 {#linking}

| 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 {#issue}

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 {#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}

**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 {#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](/docs/cloud/tasks-mcp#push)) 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 {#board}

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 {#token}

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](/docs/cloud/chat-work.md#the-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](#board)) |
| 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](#linkback)) |
| Close a pull request | **Canceling an issue closes its pull requests** is on and a person cancels an issue ([below](#cancel)) |

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

### Comment on linked pull requests {#linkback}

**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 {#cancel}

**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 {#branch}

`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 {#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](#connect): the Pull requests
event carries drafts, ready for review, review requests, the base branch and `updated_at`.
