ci: enrich cherry-pick PRs with Linear refs + future-proof sync workflow

[ashleeradka]

Prompt / plan

Linear Releases sync (PR #30622, merged) is dormant for this repo because of three structural gaps in how Linear's Release CLI consumes commit history when the source repo ships via cherry-pick PRs. This PR closes all three, plus adds future-proofing.

The three gaps

1. Cherry-pick squash commits drop Linear refs. cherry-pick-to-release.yml accumulates multiple cherry-picks into one PR per release branch. When that PR squash-merges, the squash body concatenates only the titles of the cherry-picked commits — not their bodies. Any Closes LUM-XXX in the original main PRs is lost.

2. Release branches aren't ancestors of each other. git merge-base --is-ancestor v0.8.0 v0.8.1 returns false. The Linear CLI uses merge-base --is-ancestor to filter candidate base SHAs; when none qualifies it falls back to inspecting only HEAD. Combined with (1), scheduled releases would stamp 0 issues even after backfill.

3. Magic-word requirement. Linear's extractor only catches LUM-NNNN when preceded by Closes / Fixes / Resolves / Part of / Refs. Bare mentions are intentionally ignored.

What this changes

.github/scripts/enrich-cherry-pick-pr.py walks origin/release/vX.Y.Z..HEAD, fetches each cherry-picked main PR via gh pr view, and rebuilds a structured Linear-refs block in the cherry-pick PR's body. When the cherry-pick PR squash-merges, the Closes LUM-XXX lines land in the squash commit body — exactly what Linear's HEAD-only fallback scans for.

Discovery order:

1. Linear attachmentsForURL GraphQL (docs) — optional, runs only when LINEAR_API_KEY is configured. Catches PRs linked via Linear's Development panel even with no identifier in the body.
2. Regex scan — restricted to Vellum's three team prefixes (LUM, ATL, JARVIS). One-line constant; adding a fourth team is trivial.

Block uses HTML-comment delimiters so subsequent cherry-picks update in place.

.github/workflows/cherry-pick-to-release.yml exports the cherry-pick PR number and adds a continue-on-error: true step invoking the script. Enrichment cannot fail the cherry-pick.

.github/workflows/linear-release-sync.yml:

• workflow_dispatch with a tag input for backfill / re-sync. Pre-release filter is gated on event_name == 'release'.
• Second action invocation with command: complete (same pinned SHA) that moves scheduled releases into the terminal stage automatically.

What this no longer changes (revised after team feedback)

An earlier revision added a comment block to .github/PULL_REQUEST_TEMPLATE.md encouraging Linear closing keywords. Removed in 5698b8a.

Team workflow already gets full Linear-issue linkage via bare mentions (Linear's GitHub integration links issues via the Development panel from any LUM-NNNN reference, and the workspace's auto-close-on-merge setting closes them when the PR merges). The closing-keyword hint was redundant for that purpose and wouldn't be adopted organically.

The Linear Release CLI's separate magic-word requirement is the real problem this PR solves — but via the enrichment script (which queries attachmentsForURL to discover Dev-panel-linked issues and writes the closing-keyword form into the cherry-pick PR body before squash-merge) — not by pushing a PR-template convention onto engineers.

Alternatives considered and rejected

• C: merge release branches back to main — solves ancestry but touches the release process itself.
• D: replace linear/linear-release-action with a custom GraphQL caller — re-implements logic the upstream CLI already handles.
• E: upstream a --from-sha flag — slow, uncertain, doesn't fix the squash-strips-refs problem.

Option B (this PR) preserves the existing release workflow entirely, requires no infrastructure changes, and is reversible by deleting the enrichment step.

Why it's safe

• Enrichment is best-effort (continue-on-error: true). Failures cannot fail the cherry-pick or any downstream job.
• The script only edits the cherry-pick PR body via gh pr edit; never pushes commits, never modifies workflow state, never touches other PRs.
• complete step uses the same pinned action SHA + CLI version as sync.
• workflow_dispatch is purely additive.

References

• Linear Release CLI: https://github.com/linear/linear-release
• Linear Release Action README: https://github.com/linear/linear-release-action#commands
• Linear attachmentsForURL: https://linear.app/developers/attachments
• GitHub workflow_dispatch: https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch

Test plan

• Regex smoke test confirms LUM-, ATL-, JARVIS- are extracted and HTTP-200, AWS-1, lowercase, and future-team prefixes are rejected.
• yaml.safe_load confirms both workflows parse.
• Once merged, the next cherry-pick will run enrichment and the resulting cherry-pick PR will show a structured Linear refs block. The next production tag publish will then sync correctly to Linear.
• Backfill of v0.6.0 → v0.8.1 is available via workflow_dispatch.

CLI verb checklist

N/A — no IPC routes touched.

Link to Devin session: https://app.devin.ai/sessions/8a3ce390e6e24deba0fac01d1b4a001e
Requested by: @ashleeradka

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b41375bdde

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Remove concrete Linear IDs from template comments

Because the new enrichment script scans the raw PR title/body with regex_linear_ids(...) and does not strip HTML comments, any PR opened from this template that leaves the hidden comments intact will contribute the example IDs here. When such a PR is cherry-picked, the release PR will get generated Closes LUM-1234 / Closes ATL-539 lines, so Linear release sync can attach bogus issues to every affected release; use non-matching placeholders or strip comments before scanning.

Useful? React with 👍 / 👎.

[devin-ai-integration]

Caught at the same moment by the Linear linkback bot itself — it attached this PR to the real LUM-NNNN and ATL-NNN issues. Pushed 7f76dcc which:

• Switches the template's example identifiers from LUM-1234 / ATL-539 (digits → matched by Linear's regex) to LUM-NNNN / ATL-NNN (letters → not matched).
• Same swap in the enrichment script's docstring for consistency.
• Updates this PR's description so it stops cross-linking to unrelated existing issues.

Verified my Vellum-team-prefix regex is \\b(LUM|ATL|JARVIS)-(\\d{1,9})\\b — NNNN/NNN have no digits and don't match, confirming the bot's analysis was correct.

Resolved.

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🔴 Enrichment script unreachable: working tree is on cherry-pick branch, not main

After the "Cherry-pick and create PR" step, the working tree is on the cherry-pick branch (via git checkout "$CHERRY_PICK_BRANCH" at .github/workflows/cherry-pick-to-release.yml:74 or :76-77). The cherry-pick branch is based on the release branch, which was created before this PR merged to main. Therefore .github/scripts/enrich-cherry-pick-pr.py does not exist in the working tree when the enrichment step tries to run it. The command python3 .github/scripts/enrich-cherry-pick-pr.py will fail with FileNotFoundError on every invocation until a release branch is cut from a main commit that includes this script. continue-on-error: true prevents this from blocking the cherry-pick, but the entire enrichment feature is non-functional for all existing release branches.

Suggested fix approach

Before running the script, restore it from the original checkout ref (main). For example:

run: |
  git show origin/main:.github/scripts/enrich-cherry-pick-pr.py > /tmp/enrich-cherry-pick-pr.py
  python3 /tmp/enrich-cherry-pick-pr.py

Suggested change

	run: python3 .github/scripts/enrich-cherry-pick-pr.py
	run: |
	git show origin/main:.github/scripts/enrich-cherry-pick-pr.py > /tmp/enrich-cherry-pick-pr.py
	python3 /tmp/enrich-cherry-pick-pr.py

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Real bug, confirmed by walking the workflow's git state:

1. The initial actions/checkout@v6.0.2 (line 28) puts the working tree on main with full history (fetch-depth: 0).
2. The "Cherry-pick and create PR" step (line 76 or line 73-74) git checkouts the cherry-pick branch, which is based on release/vX.Y.Z.
3. That release branch was cut before this PR exists, so it does not have .github/scripts/enrich-cherry-pick-pr.py.
4. By the time the enrichment step runs, the script file is genuinely missing from the working tree.

Result without a fix: python3 .github/scripts/enrich-cherry-pick-pr.py → No such file or directory on every cherry-pick. continue-on-error: true hides the failure but the whole enrichment is non-functional.

Applied the suggested fix in 1a8764d with a slight tweak — explicit git fetch origin main --quiet before git show, so the script is always loaded from the freshest origin/main (covers the case where a long-lived runner has stale refs). Script writes to /tmp and runs from there; its internal git operations (git log, git rev-parse, etc.) read from .git, which is the same regardless of working-tree ref, so behavior is unchanged.

Resolved.

[vex-assistant-bot]

Vex review — APPROVED ✅

CI-only: no application code paths. Reviewed all 3 commits at HEAD 1a8764d.

What this fixes: Three structural gaps that made the Linear Release CLI stamp 0 issues on vellum-assistant releases shipped via cherry-pick PR squashes — (1) squash body drops original PR bodies, (2) release branches aren't ancestors of each other (Linear's CLI falls back to HEAD-only scan), (3) Linear requires closing-keyword magic words, not bare mentions.

The two bugs Devin caught and self-fixed:

1. Template example IDs were real-looking (LUM-1234/ATL-539 → LUM-NNNN/ATL-NNN). Commit 7f76dcc confirmed correct — regex is \b(LUM|ATL|JARVIS)-(\d{1,9})\b; NNNN has no digits, doesn't match. Linear's linkback bot actually triggered on the original values before the fix landed, confirming the risk was real.

2. Enrichment script unreachable on existing release branches. After the cherry-pick step, working tree is on the cherry-pick branch (based on release/vX.Y.Z, cut before this PR merged), so .github/scripts/enrich-cherry-pick-pr.py doesn't exist in the tree. Commit 1a8764d fixes this correctly: git fetch origin main --quiet && git show origin/main:.github/scripts/... > /tmp/... — always loads the script from origin/main regardless of working tree state. Git operations inside the script (git log, git rev-parse) read from .git which is unaffected. ✅

Rest of the review:

• continue-on-error: true on enrichment step — enrichment failure cannot block cherry-picks ✅
• Action SHA pinned at both sync and complete steps (755d50b5), same cli_version: v0.10.0 ✅
• workflow_dispatch is additive — existing release: published behavior unchanged ✅
• Pre-release filter correctly gates on event_name == 'release' so manual dispatch bypasses it ✅
• Python script is idempotent (HTML comment delimiters replace in-place), handles Linear API errors gracefully, regex restricted to known team prefixes (LUM/ATL/JARVIS) to prevent false positives ✅
• LINEAR_API_KEY enrichment path is optional — degrades to regex-only if secret not set ✅

Anti-patterns KB: No SwiftUI, React, or application patterns apply — CI scripting only.

Vellum Constitution — Article VI (Accountability): This PR directly strengthens auditability by ensuring every shipped issue shows up correctly on its Linear release. When an issue is stamped "released in v0.8.2" it now actually means it shipped in that build. That's exactly the kind of audit trail Article VI asks for.

No blocking findings. Both Devin-flagged bugs are confirmed fixed at HEAD.

[devin-ai-integration]

Thanks @vex-assistant-bot. One revision since your approval: dropped the PR template closing-keyword hint in 5698b8a after the team clarified that bare LUM-NNNN mentions already provide full Linear linkage via the Dev panel + auto-close-on-merge. The closing-keyword convention was redundant for engineers' purposes and wouldn't have been adopted.

The Release CLI's separate magic-word requirement is still solved — by the enrichment script's attachmentsForURL query, which rewrites the cherry-pick PR body just-in-time without asking engineers to change anything. Both the script-unreachable bug (1a8764d) and the placeholder fix (7f76dcc) you confirmed remain in place.