---
title: Releases in Venom Tasks
description: Say what ships together with release pipelines and releases, fill them from GitHub pushes or any CI with a pipeline key, mark them shipped when GitHub reports a deployment, write release notes from a template, and copy each pipeline's changelog as Markdown.
section: cloud
order: 86
audience: [user, operator, agent]
sources: [services/nodejs-cloud/lib/tasks/releases.ts, services/nodejs-cloud/lib/tasks/releases-pure.ts, services/nodejs-cloud/lib/tasks/releases-handlers.ts, services/nodejs-cloud/lib/tasks/release-refs.ts, services/nodejs-cloud/app/tasks/api/releases, services/nodejs-cloud/components/tasks/releases, services/nodejs-cloud/migrations/0361_tasks_releases.sql, services/nodejs-cloud/lib/tasks/releases-git.ts, services/nodejs-cloud/lib/tasks/releases-git-pure.ts, services/nodejs-cloud/lib/tasks/releases-keys.ts, "services/nodejs-cloud/app/api/integrations/releases/sync", services/nodejs-cloud/migrations/0362_tasks_releases_git.sql]
features: [cloud.page-tasks, cloud.tasks]
---

Merging a pull request and shipping it to customers are different moments. Releases let a team record the second one:
which issues went out together, in which product or environment, and when.

## Pipelines and releases

A **pipeline** is one thing you ship: an app, a service, an environment (Web, iOS, Production). There are two kinds:

| Kind | How releases work |
|---|---|
| Scheduled | You plan releases ahead (name, target date, description), **Start** one when work on it begins and **Complete…** it when it ships. Planned → In progress → Completed (or Canceled) |
| Continuous | Every deploy is a release, made complete when it is created, with its commit SHA. Add them by hand, or let [GitHub](#from-github) or [your CI](#from-any-ci) make them |

A pipeline names **teams**: their issues see it first when added to a release. Teams don't limit who can join: an issue
from any team can be in any pipeline's release. An issue can be in one release per pipeline, and in releases of several
pipelines at once (the same fix in iOS 3.1 and Android 3.1).

A new release is named after the previous one by default: `2.4` becomes `2.5`, `Sprint 7` becomes `Sprint 8`, `v1.9`
becomes `v1.10`.

## Pages

| Page | URL |
|---|---|
| Releases | `/tasks/releases`: every pipeline with its kind, teams, current or latest release and open issues. Owners and admins make, edit and delete pipelines here |
| A pipeline | `/tasks/releases/{pipeline}`: its releases, started and planned first, then completed ones newest first, each with a done/total bar and a **⋯** menu (Start, Complete…, Edit…, Cancel release). The **Changelog** tab lists its completed releases with their notes |
| A release | `/tasks/releases/{pipeline}/{release}`: the release's status, target or ship date, commit and description over its issues in the normal list, with **Display** (list or board, grouping, ordering, properties). The **Notes** tab (`…/{release}/notes`) holds its release notes and the commits that went into it |
| A changelog | `/tasks/releases/{pipeline}/changelog`: completed releases, newest first |

**Releases** shows in the sidebar under Workspace once the org has a pipeline (owners and admins always see it, to make
the first). `g` then `r` goes there.

## Adding issues to a release

- On an issue, the **Release** row in the properties opens the release picker: pipelines whose teams include the
  issue's team come first, marked suggested, each with its planned and in-progress releases. The release the issue is
  in is checked; choosing it again, or **Remove from {pipeline}**, takes it out.
- In a list, select issues and use ⌘K **Add to release…** or **Remove from release**, or the issue menu's
  **More properties ▸ Release…**.
- Adding to a completed release is allowed (a fix found late); the picker marks such releases "completed" and says so
  when you pick one.

The issue's activity says "added the issue to release Web 2.5" and "removed the issue from release Web 2.5".

## In lists

- **Filter**: Release and Release pipeline (any of, none of, includes all of, or no release), also in the advanced filter.
- **Display property**: Release, a small chip with the release's name, or "2.5 +1" when it is in releases of several pipelines.
- **Group by**: Release. An issue in two releases shows in both groups; "No release" comes last.
- Saved views keep these, and a list's CSV export has a **Releases** column at the end ("Web 2.5; iOS 3.1").

## Completing a release

**Complete…** shows how many of the release's issues are finished and still open (the ones you can see). With **Move
open issues to the next release when one completes** on (the default for scheduled pipelines, set per pipeline and
in the dialog), open issues move to the next planned or in-progress release, and when there is none, a new one is made
by the naming rule ("Move 4 open issues to 2.6"). Completed and canceled issues stay in the release they shipped in.
Each moved issue's activity says "moved the issue on to release Web 2.6".

Then each team's **release automation** runs. In team settings → Workflow, **When a release completes** names a status
(a started or completed one, such as "Released") and, optionally, the pipelines it applies to. An issue in the release
moves there when:

- it has no linked pull requests, or a merged pull request that closes it and no open (or draft) one, closing or contributing;
- the move is forward in the team's workflow (a canceled issue never moves).

A pull request that was closed without merging counts as none. The move shows as "ran the release automation" in the
issue's activity, by Releases.

## Where releases come from

Owners and admins pick a pipeline's source in its **⋯** menu → **Source and notes…**:

| Source | What makes releases |
|---|---|
| By hand | People, as above |
| GitHub | Pushes to one repository and branch, through the webhook from [Tasks and GitHub](/docs/cloud/tasks-github.md) |
| CI | Any CI system calling Venom with the pipeline's key after it deploys |

The settings say what is still missing: GitHub not connected, no push or deployment received yet, or no key.

### From GitHub {#from-github}

Set the **Repository** (`acme/web`), the **Branch** (empty: the repository's default branch) and, optionally, **Path
filters** and **Ship when GitHub deploys to**. Each push to that branch then:

- **Continuous pipeline**: makes one release named by the push's newest commit (`a1b2c3d`), with every issue its commits
  name. Without a deployment environment it is complete at once and the team automation runs; with one, it stays in
  progress until GitHub reports a successful deployment of that commit.
- **Scheduled pipeline**: adds the issues to the release in progress (or, when none is, the next planned one; when there
  is none, a new one named by the numbering rule).

A commit's issues are the keys in its message (`Fixes ENG-12`, `refs ENG-14`, `ENG-15` anywhere), the issues linked to
the pull request a merge or squash commit names (`Merge pull request #21 from …`, `Fix login (#21)`), and the issues
the commit was already linked to. A commit that names no issue is kept as an **other change**, so it still shows in the
changelog. Issues of any team can join; an identifier of another organization finds nothing.

A **revert** (`Revert "…"`, `This reverts commit …`, or GitHub's revert pull request) adds no issues. When the commit or
pull request it undoes is in the same release, both are marked reverted and the issues only that commit brought leave
the release. A revert of something shipped earlier shows as an other change in its own release.

GitHub sends the same push again on a retry: nothing changes, since each commit is recorded once per pipeline. An issue
that already shipped in an earlier completed release of the pipeline stays there, and the later release's changelog
lists it again because one of its commits names it.

**Path filters** (one glob per line) keep a monorepo's pipelines apart: `apps/web/**` counts only commits that touch a
file under `apps/web`; `**` matches any number of folders, `*` anything within one, a line without `/` matches a file
name anywhere (`*.md`) and `!` excludes (`!**/*.md`). With filters, a commit whose push lists no files doesn't count.
GitHub's push lists at most 2048 commits; Venom reads the newest 100.

**Ship when GitHub deploys to** (`production`): a successful `deployment_status` for that environment completes the
release holding the deployed commit, through the same completion as **Complete…** (open issues roll on in scheduled
pipelines, then the team automation runs once). In a continuous pipeline, releases still in progress from before it
complete too. A failed deployment, or one to another environment, changes nothing.

What the webhook needs on GitHub's side: the **Pushes** event, and **Deployment statuses** for shipping on deploy. Add
them to the webhook you set up in Settings → GitHub (the repository's or organization's Settings → Webhooks → your
Venom webhook → **Let me select individual events**). Venom never changes anything on GitHub and writes nothing there
for releases.

### From any CI {#from-any-ci}

With the source **CI**, **Create key** makes a key (`vrk_…`), shown once: keep it in your CI system's secrets. A key can
only report releases for its one pipeline, at most 60 calls a minute; Venom stores only its hash and its first eight
characters, shows when it was last used, and **Rotate** and **Revoke** it. A revoked key gets 401 `invalid_key`; a key
whose pipeline was deleted gets 404.

`POST /api/integrations/releases/sync` with `Authorization: Bearer vrk_…` and a JSON body:

| Field | |
|---|---|
| `commit` | required: the deployed commit's SHA |
| `commits` | optional, at most 250: `[{sha, message, files?}]`, the commits since the last deploy. Their messages are read as on GitHub; `files` feeds the path filters |
| `issues` | optional: identifiers to add as well (`["ENG-12"]`) |
| `name` or `version` | optional: the release's name. Default: the commit's short SHA (continuous), or the release in progress (scheduled) |
| `stage` | optional: `completed` completes the release (continuous releases are complete by default), `started` starts a planned one or keeps a continuous one in progress |
| `url` | optional: an https link to the run, shown on the release |

It answers `{release: {id, name, status, pipeline}, created, attached, unknown}`, where `unknown` lists identifiers that
found no issue in your organization. The same commit sent again changes nothing; an `Idempotency-Key` header returns
the first answer for 24 hours. Every call is in the audit log, with the key's prefix and never the key.

A GitHub Actions step after your deploy (the checkout needs `fetch-depth: 0` for the commit list):

```yaml
- name: Report the release to Venom
  if: success()
  env:
    VENOM_RELEASE_KEY: ${{ secrets.VENOM_RELEASE_KEY }}
    BEFORE: ${{ github.event.before }}
  run: |
    commits=$(git log --format='%H%x1f%s' "$BEFORE..$GITHUB_SHA" 2>/dev/null \
      | jq -R -s -c 'split("\n") | map(select(length > 0) | split("\u001f") | {sha: .[0], message: .[1]})')
    jq -n --arg commit "$GITHUB_SHA" --argjson commits "${commits:-[]}" \
      --arg url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" \
      '{commit: $commit, commits: $commits, url: $url}' \
    | curl -fsS https://YOUR-VENOM-CLOUD/api/integrations/releases/sync \
      -H "Authorization: Bearer $VENOM_RELEASE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" \
      --data-binary @-
```

The key stays in the `VENOM_RELEASE_KEY` secret and is never printed. GitLab CI is the same step with `$CI_COMMIT_SHA`,
`$CI_COMMIT_BEFORE_SHA` and a masked variable.

## Release notes

Each release has notes, written on its **Notes** tab in the same editor as issue descriptions (`[[ENG-12]]` links an
issue, `@` mentions any item; saving links the release to what it mentions). **Start from template** fills them from
the pipeline's template and asks first when the notes already hold text. In a continuous pipeline, **Notes cover**
picks an earlier release, and the template lists every issue shipped since then. Below the notes, the tab lists the
commits that went into the release, reverted ones struck through.

The template is set in **Source and notes…** (empty: the default). It is Markdown with `{{release}}`, `{{date}}`,
`{{issues}}` (the issues as `[[ENG-12]] title`, grouped by label, team, or not at all, as the pipeline says) and
`{{changes}}` (the commits that named no issue). Titles are used as written; nothing is generated by a model. An issue
of a private team is listed by its identifier alone, since everyone who sees the pipeline reads the notes; its chip
shows the title only to people who can see the issue.

## The changelog

A pipeline's **Changelog** tab lists its completed releases, newest first: the name, the day it shipped and its notes
(or, without notes, its issues and other changes). Each has **Copy link** and **Copy as Markdown**, and **Copy changelog
as Markdown** copies them all, with issue links as plain identifiers, ready to paste elsewhere.

## Deleting a pipeline

Owners and admins delete a pipeline from its **⋯** menu. Its releases leave every issue at once. For 30 days it is
listed under **Deleted pipelines** on the Releases page and **Restore** brings it back with its releases and their
issues; after that it is removed for good.

## Who sees what

Pipelines and releases belong to the workspace. A release never shows an issue from a private team you are not in:
its issue list, its counts and the pipeline's open count leave such issues out, and so do its commits, a notes draft
and the changelog (a commit that names only such issues is left out too).

## For agents

Releases are referenceable items (`release:<id>`): mention one with `@` in a note or an issue, paste its link, and it
shows as a card with its pipeline, status and issue count. The MCP tools, in the `planning` tool set:

| Tool | What |
|---|---|
| `tasks_releasepipeline_list`, `_create`, `_update`, `_delete`, `_restore` | pipelines (changing them needs an owner or admin) |
| `tasks_release_list`, `tasks_release_get` | releases, and one release with the issues in it |
| `tasks_release_create`, `tasks_release_update`, `tasks_release_complete` | make, change and complete releases |
| `tasks_release_issue_add`, `tasks_release_issue_remove` | `{"release": "Web 2.5", "issues": ["ENG-12"]}` |
| `tasks_releaseautomation_get`, `tasks_releaseautomation_update` | a team's release automation |
| `tasks_release_draft`, `tasks_releasechangelog_get` | notes from the template (`tasks_release_update` with `notes` saves them), and a pipeline's changelog |
| `tasks_releasekey_list`, `_create`, `_revoke` | a pipeline's CI keys (owners and admins) |

`tasks_releasepipeline_update` takes the source settings (`source`, `repo`, `branch`, `pathGlobs`, `deployEnv`,
`template`, `notesGroup`). The CI endpoint has no tool: agents use `tasks_release_create` and `tasks_release_issue_add`.

`tasks_issue_get` returns an issue's `releaseIds`, and `tasks_issue_search` takes the `release` and `releasePipeline`
filter fields. The REST endpoints are under [Releases](/docs/cloud/tasks-api.md#releases).

Behaviour follows Linear's public documentation on releases (linear.app/docs/releases, read November 15, 2026); the
design and the code are Venom's own.

## Related

- [Venom Tasks](/docs/cloud/tasks.md)
- [Tasks and GitHub](/docs/cloud/tasks-github.md)
- [Tasks API](/docs/cloud/tasks-api.md)
