Skip to content
Docs menu

Releases in Venom Tasks

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.

View .md

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 or your 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
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

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

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):

- 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.

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.