Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

ci(open-knowledge): stamp Linear issues with the release they ship in (#2748)

Andrew Mikofalvy4da8287551d5
diff --git a/.github/workflows/linear-release.yml b/.github/workflows/linear-release.yml
new file mode 100644
index 000000000..40ae34a32
--- /dev/null
+++ b/.github/workflows/linear-release.yml
@@ -0,0 +1,174 @@
+name: Linear Release
+
+# Stamp Linear issues with the Open Knowledge release they ship in.
+#
+# WHAT THIS DOES
+# On every OK release cut (beta cadence + stable promotion) this attaches
+# the Linear issues referenced in the release's commits to a release in the
+# Linear "OpenKnowledge" scheduled pipeline, and advances that release's
+# stage: `Beta` on a beta cut, `Stable` + complete on a stable promotion.
+# Each attached issue then shows which release it shipped in, in its Linear
+# sidebar. Uses Linear's first-party CLI via linear/linear-release-action.
+#
+# HOW IT'S TRIGGERED (no edits to the delicate publish path)
+# release.yml (beta) and promote-stable.yml (stable) BOTH already fire a
+# repository_dispatch event_type=desktop-release with
+# client_payload.{release_tag, ref} right after cutting the tag + draft
+# Release. We piggyback on that same event rather than adding a new dispatch,
+# so release.yml / promote-stable.yml stay byte-untouched. We cannot use
+# `release: published`: GitHub suppresses cascades from GITHUB_TOKEN-authored
+# release events, and repository_dispatch is the documented exemption (which
+# is exactly why the desktop-release cascade uses it).
+#
+# Channel is derived from the tag shape: a `-beta.N` suffix => Beta stage,
+# a bare vX.Y.Z => Stable stage.
+#
+# RELEASE IDENTITY (why betas accumulate into one release)
+# The Linear release is keyed by the STABLE base version (vX.Y.Z with any
+# `-beta.N` stripped), so every beta of a cycle syncs its issues into the
+# SAME release object, and the stable promotion flips that same release to
+# Stable + complete. Caveat: if a higher bump level lands mid-cycle the base
+# version shifts; that is rare, and Linear releases can be renamed/merged.
+#
+# COMMIT SCAN RANGE
+# The scan lower bound (base_ref) is the previous tag in history, so each cut
+# only scans its own new commits (`<prev-tag>..<this-tag>`) — bounded even on
+# the first run. sync is idempotent: re-attaching an already-attached issue
+# is a no-op, so a near-empty stable range simply re-affirms the accumulated
+# set before the stage flip.
+#
+# ONE-TIME SETUP
+# 1. A Linear SCHEDULED pipeline "OpenKnowledge" (team Product) with started
+# stages named exactly `Beta` and `Stable`. [done]
+# 2. The pipeline access key (Linear -> Settings -> Releases -> pipeline)
+# added as the repo secret LINEAR_ACCESS_KEY on inkeep/open-knowledge.
+# A pipeline access key is REQUIRED — a personal Linear API key will not
+# work. Until the secret exists this workflow no-ops (see the guard).
+# 3. Optional: a Linear status automation — when a release reaches Stable /
+# completes, move its issues to a Done status.
+# 4. Coverage: issues are attached by scanning commit text for Linear
+# identifiers (e.g. PRD-1234). A ticketed fix whose PR title lacks the
+# identifier will not be attached — put PRD-#### in the PR title.
+#
+# VALIDATION
+# After adding the secret, dry-run against a recent tag before trusting it:
+# run this workflow via workflow_dispatch with a real release_tag and read
+# the CLI output. (linear-release-action also supports dry_run for the CLI.)
+#
+# SAFETY
+# Fully decoupled from the release/publish path — a failure here can never
+# break a release. The job no-ops cleanly when LINEAR_ACCESS_KEY is absent.
+
+on:
+ repository_dispatch:
+ # Fired by release.yml (beta) and promote-stable.yml (stable) after each
+ # tag + draft Release. Carries client_payload.{release_tag, ref}.
+ types: [desktop-release]
+ # Manual re-stamp / backfill for a specific tag.
+ workflow_dispatch:
+ inputs:
+ release_tag:
+ description: "Release tag to stamp in Linear (e.g. v0.35.0 or v0.35.0-beta.3)"
+ required: true
+ type: string
+
+permissions:
+ contents: read
+
+concurrency:
+ # Serialize per release line so a beta and its stable promotion don't race
+ # on the same Linear release object.
+ group: linear-release-${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ cancel-in-progress: false
+
+jobs:
+ stamp:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ env:
+ # Secrets are unavailable in step/job `if` on some event types, so map
+ # presence to a plain string once and gate steps on that.
+ HAS_KEY: ${{ secrets.LINEAR_ACCESS_KEY != '' }}
+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ steps:
+ - name: Skip when access key is not configured
+ if: env.HAS_KEY != 'true'
+ run: |
+ echo "::notice::LINEAR_ACCESS_KEY is not set on this repo — skipping Linear release stamping. Add the OpenKnowledge pipeline access key as a repo secret to enable."
+
+ - name: Checkout at the release tag
+ if: env.HAS_KEY == 'true'
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ ref: ${{ github.event.client_payload.ref || inputs.release_tag }}
+ # Full history + tags so the commit scan and previous-tag lookup work.
+ fetch-depth: 0
+ fetch-tags: true
+
+ - name: Derive channel, version, and scan range
+ if: env.HAS_KEY == 'true'
+ id: derive
+ run: |
+ set -euo pipefail
+ TAG="${RELEASE_TAG}"
+ if [[ -z "$TAG" ]]; then
+ echo "::error::No release tag (neither client_payload.release_tag nor inputs.release_tag)."
+ exit 1
+ fi
+ # Stable base version: strip leading `v` and any `-beta.N` suffix.
+ V="${TAG#v}"; V="${V%%-beta.*}"
+ if [[ ! "$V" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "::error::Could not derive X.Y.Z from tag '${TAG}'."
+ exit 1
+ fi
+ if [[ "$TAG" == *-beta.* ]]; then
+ CHANNEL=beta; STAGE=Beta
+ else
+ CHANNEL=stable; STAGE=Stable
+ fi
+ # Exclusive lower bound for sync's commit scan = the previous tag in
+ # history. Empty on the very first tag ever; the action then falls
+ # back to its own default lower bound.
+ BASE_REF="$(git describe --tags --abbrev=0 "${TAG}^" 2>/dev/null || true)"
+ {
+ echo "channel=${CHANNEL}"
+ echo "stage=${STAGE}"
+ echo "version=${V}"
+ echo "name=v${V}"
+ echo "base_ref=${BASE_REF}"
+ } >> "$GITHUB_OUTPUT"
+ echo "tag=${TAG} channel=${CHANNEL} version=${V} stage=${STAGE} base_ref=${BASE_REF:-<none>}"
+
+ # Create/find the release keyed by the stable version, name it vX.Y.Z,
+ # and attach the Linear issues referenced in <base_ref>..HEAD. Runs on
+ # both channels; idempotent.
+ - name: Sync issues into the Linear release
+ if: env.HAS_KEY == 'true'
+ uses: linear/linear-release-action@c0cb8354a362c24c6d3e0948f37fd66d07588e3f # v0
+ with:
+ access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
+ command: sync
+ version: ${{ steps.derive.outputs.version }}
+ name: ${{ steps.derive.outputs.name }}
+ base_ref: ${{ steps.derive.outputs.base_ref }}
+
+ # Advance the release to Beta (beta cut) or Stable (stable promotion).
+ - name: Advance release stage
+ if: env.HAS_KEY == 'true'
+ uses: linear/linear-release-action@c0cb8354a362c24c6d3e0948f37fd66d07588e3f # v0
+ with:
+ access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
+ command: update
+ version: ${{ steps.derive.outputs.version }}
+ stage: ${{ steps.derive.outputs.stage }}
+
+ # Stable only: mark shipped-to-customers, moving the release to the
+ # pipeline's completed stage (`Released`) and firing any completion-based
+ # Linear status automations.
+ - name: Complete the release (stable only)
+ if: env.HAS_KEY == 'true' && steps.derive.outputs.channel == 'stable'
+ uses: linear/linear-release-action@c0cb8354a362c24c6d3e0948f37fd66d07588e3f # v0
+ with:
+ access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
+ command: complete
+ version: ${{ steps.derive.outputs.version }}