semantic-release-linear-app 0.1.0 → 0.2.0

package/README.md

@@ -1,204 +1,261 @@
-# semantic-release-linear-app
+# semantic-release-linear
 
-> A [semantic-release](https://github.com/semantic-release/semantic-release) plugin to automatically update Linear issues with version labels when they're included in releases.
+> A [semantic-release](https://github.com/semantic-release/semantic-release) plugin that updates Linear issues with version labels based on branch names.
 
 ## Features
 
-- 🏷️ Automatically adds version labels to Linear issues mentioned in commits
-- 🎨 Color-coded labels based on release type (major/minor/patch)
-- 🧹 Optionally removes old version labels to keep issues clean
-- 💬 Can add release comments to issues (optional)
-- 🔍 Configurable team key filtering
+- 🌿 Extracts Linear issue IDs from branch names
+- 🏷️ Automatically adds version labels to Linear issues
+- 🎨 Color-coded labels based on release type
+- 🧹 Removes old version labels (configurable)
+- 💬 Adds release comments to issues (optional)
 - ⚡ Batch operations for efficiency
-- 📝 Full TypeScript support with type definitions
+- 📝 Full TypeScript support
 
 ## Install
 
 ```bash
-npm install --save-dev semantic-release-linear-app
+npm install --save-dev semantic-release-linear
 ```
 
-## Usage
+## Quick Start
 
-Add the plugin to your semantic-release configuration:
+1. **Configure semantic-release** (`.releaserc.json`):
 
 ```json
 {
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
-    ["semantic-release-linear-app", {
-      "apiKey": "lin_api_xxx"
+    ["semantic-release-linear", {
+      "teamKeys": ["ENG", "FEAT", "BUG"]
     }],
     "@semantic-release/github"
   ]
 }
 ```
 
-### TypeScript Configuration
-
-If you're using TypeScript for your configuration, the plugin exports types:
-
-```typescript
-import type { PluginConfig } from 'semantic-release-linear-app';
+2. **Set your Linear API key**:
 
-const config: PluginConfig = {
-  apiKey: process.env.LINEAR_API_KEY,
-  teamKeys: ['ENG', 'FEAT'],
-  labelPrefix: 'v',
-  removeOldLabels: true,
-  addComment: false
-};
+```bash
+export LINEAR_API_KEY=lin_api_xxx
 ```
 
-## Configuration
-
-### Authentication
-
-Set your Linear API key via environment variable:
+3. **Use proper branch names**:
 
 ```bash
-export LINEAR_API_KEY=lin_api_xxx
+git checkout -b feature/ENG-123-add-authentication
+git checkout -b bugfix/FEAT-456-fix-validation
+git checkout -b ENG-789-quick-fix
 ```
 
-Or pass it in the plugin configuration:
+That's it! When semantic-release creates a release from these branches, the corresponding Linear issues will be labeled with the version number.
 
-```json
-{
-  "apiKey": "lin_api_xxx"
-}
-```
+## Configuration
 
 ### Options
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `apiKey` | - | Linear API key (or use `LINEAR_API_KEY` env var) |
-| `teamKeys` | `[]` | Array of team keys to filter issues (e.g., `["ENG", "FEAT"]`) |
+| `teamKeys` | `[]` | Team keys to filter (e.g., `["ENG", "FEAT"]`) |
 | `labelPrefix` | `"v"` | Prefix for version labels |
-| `removeOldLabels` | `true` | Remove previous version labels from issues |
-| `addComment` | `false` | Add a comment to issues with release info |
-| `dryRun` | `false` | Preview changes without updating Linear |
+| `removeOldLabels` | `true` | Remove previous version labels |
+| `addComment` | `false` | Add a release comment to issues |
+| `skipBranches` | `["main", "master", "develop", "staging", "production"]` | Branches to skip unless they contain issues |
+| `requireIssueInBranch` | `true` | Only process branches with Linear issues |
+| `dryRun` | `false` | Preview without making changes |
 
-### Example Configuration
+### TypeScript Configuration
 
-```javascript
-// .releaserc.js
-module.exports = {
-  branches: ['main', 'next'],
+```typescript
+// .releaserc.ts
+import type { PluginConfig } from 'semantic-release-linear';
+
+const config: PluginConfig = {
+  teamKeys: ['ENG', 'FEAT'],
+  labelPrefix: 'release-',
+  addComment: true,
+  skipBranches: ['main', 'develop']
+};
+
+export default {
   plugins: [
     '@semantic-release/commit-analyzer',
     '@semantic-release/release-notes-generator',
-    ['semantic-release-linear-app', {
-      teamKeys: ['ENG', 'FEAT', 'BUG'],
-      labelPrefix: 'version:',
-      removeOldLabels: true,
-      addComment: true
-    }],
-    '@semantic-release/npm',
+    ['semantic-release-linear', config],
     '@semantic-release/github'
   ]
 };
 ```
 
-## How It Works
+## Branch Naming Convention
 
-1. **Issue Detection**: The plugin scans commit messages for Linear issue IDs (e.g., `ENG-123`)
-2. **Label Creation**: Creates a version label if it doesn't exist (color-coded by release type)
-3. **Issue Updates**: Applies the label to all detected issues
-4. **Cleanup**: Optionally removes old version labels to avoid clutter
-
-### Commit Message Examples
-
-The plugin will detect Linear issues in various formats:
+### Recommended Patterns
 
 ```bash
-# In commit message
-git commit -m "feat: add new feature ENG-123"
+# Feature branches
+feature/ENG-123-user-authentication
+feature/FEAT-456-payment-integration
 
-# In commit body
-git commit -m "feat: add new feature" -m "Closes ENG-123"
+# Bug fixes
+bugfix/BUG-789-login-error
+fix/ENG-101-memory-leak
 
-# Multiple issues
-git commit -m "fix: resolve bugs ENG-123, FEAT-456"
+# Hotfixes
+hotfix/ENG-102-critical-security-patch
 
-# In PR title (when squash merging)
-"feat: add feature (#123) ENG-456"
+# Simple format (still works)
+ENG-103-quick-update
+FEAT-104
 ```
 
-### Label Colors
+### Multiple Issues in One Branch
 
-Labels are automatically color-coded based on the release type:
+If you need to update multiple issues, include them all in the branch name:
 
-- 🔴 **Major** releases (breaking changes) - Red
-- 🟠 **Minor** releases (new features) - Orange  
-- 🟢 **Patch** releases (bug fixes) - Green
-- 🟣 **Prerelease** versions - Purple
+```bash
+feature/ENG-123-FEAT-456-combined-update
+```
 
-## Advanced Usage
+### Enforce Branch Naming
 
-### Channel-Specific Configuration
+Use Git hooks or CI checks to enforce the naming convention:
 
-For different behavior on different release channels:
+```bash
+#!/bin/bash
+# .git/hooks/pre-push or CI script
 
-```javascript
-// Coming in v2.0
-{
-  channelConfig: {
-    next: {
-      labelPrefix: 'next:',
-      addComment: false
-    },
-    latest: {
-      labelPrefix: 'stable:',
-      addComment: true
-    }
-  }
-}
+branch=$(git rev-parse --abbrev-ref HEAD)
+pattern="^(feature|bugfix|fix|hotfix)/[A-Z]+-[0-9]+|^[A-Z]+-[0-9]+"
+
+if ! [[ "$branch" =~ $pattern ]]; then
+  echo "❌ Branch name must include a Linear issue ID"
+  echo "   Example: feature/ENG-123-description"
+  exit 1
+fi
 ```
 
-### Dry Run
+## How It Works
+
+1. **Branch Detection**: When semantic-release runs, it reads the current branch name
+2. **Issue Extraction**: Extracts Linear issue IDs (e.g., `ENG-123`) from the branch
+3. **Label Creation**: Creates a version label if needed (e.g., `v1.2.3`)
+4. **Issue Update**: Applies the label to the Linear issue(s)
+5. **Cleanup**: Optionally removes old version labels
+
+### Label Colors
+
+Labels are color-coded by release type:
 
-Test what issues would be updated without making changes:
+- 🔴 **Major** (breaking changes) - Red
+- 🟠 **Minor** (new features) - Orange  
+- 🟢 **Patch** (bug fixes) - Green
+- 🟣 **Prerelease** - Purple
+
+## Dry Run Mode
+
+Test what will happen without making changes:
 
 ```javascript
 {
-  dryRun: true
+  "plugins": [
+    ["semantic-release-linear", {
+      "dryRun": true
+    }]
+  ]
 }
 ```
 
+Output:
+```
+[semantic-release] [semantic-release-linear] Found 1 Linear issue(s) in branch "feature/ENG-123-auth": ENG-123
+[semantic-release] [semantic-release-linear] [Dry run] Would update issues: ["ENG-123"]
+[semantic-release] [semantic-release-linear] [Dry run] Would apply label: v1.2.3
+```
+
 ## Linear API Setup
 
-1. Go to Linear Settings → API → Personal API keys
-2. Create a new key with "write" access
+1. Go to **Linear Settings** → **API** → **Personal API keys**
+2. Create a new key with **write** access
 3. Add to your CI environment as `LINEAR_API_KEY`
 
-## CI Configuration
+## CI Examples
 
 ### GitHub Actions
 
 ```yaml
-- name: Release
-  env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-    LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
-  run: npx semantic-release
+name: Release
+
+on:
+  push:
+    branches: [main, next]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+        run: npx semantic-release
 ```
 
+## FAQ
+
+### Why only branch names?
+
+Extracting from commits is unreliable - developers forget, commits get squashed, and there's no enforcement. Branch names are:
+- Required for every PR
+- Easily enforced via Git hooks
+- Visible in PR lists
+- A single source of truth
+
+### What about releases from main/master?
+
+You have three options:
+
+1. **Skip them** (default): Set `requireIssueInBranch: true`
+2. **Tag main with an issue**: `git checkout main-ENG-123`  
+3. **Allow all branches**: Set `requireIssueInBranch: false`
+
+### Can I update multiple issues?
+
+Yes, include multiple issue IDs in your branch name:
+```bash
+feature/ENG-123-FEAT-456-big-feature
+```
+
+### What if my branch doesn't have an issue?
+
+The plugin will skip it (unless `requireIssueInBranch: false`). This is intentional - not every release needs to update Linear.
+
 ## Troubleshooting
 
 ### Issues not being detected
 
-- Ensure issue IDs follow the format `TEAM-NUMBER` (e.g., `ENG-123`)
-- Check that team keys match if using the `teamKeys` filter
-- Verify the issues exist in Linear
+1. Check branch name: `git rev-parse --abbrev-ref HEAD`
+2. Verify format matches: `TEAM-NUMBER`
+3. Check team keys filter if configured
+4. Run with `dryRun: true` to debug
 
 ### API errors
 
-- Confirm your API key has write access
-- Check that the Linear workspace is accessible
-- Ensure network connectivity from CI environment
+- Verify API key has write access
+- Check Linear workspace permissions
+- Ensure network connectivity in CI
 
 ## License
 

package/dist/lib/parse-issues.d.ts

@@ -1,15 +1,18 @@
-import { Commit } from "semantic-release";
 /**
- * Extract Linear issue IDs from a commit
- * @param commit - The commit object from semantic-release
- * @param teamKeys - Optional list of team keys to filter by
- * @returns Set of unique issue identifiers
+ * Extract Linear issue IDs from branch name ONLY
+ * This enforces a single source of truth for issue tracking
  */
-export declare function parseCommit(commit: Commit, teamKeys?: string[] | null): Set<string>;
 /**
- * Extract all Linear issue IDs from a list of commits
- * @param commits - Array of commit objects
+ * Extract Linear issue IDs from a branch name
+ * @param branchName - The branch name to parse
  * @param teamKeys - Optional list of team keys to filter by
  * @returns Array of unique issue identifiers
  */
-export declare function parseIssues(commits: readonly Commit[], teamKeys?: string[] | null): string[];
+export declare function parseIssuesFromBranch(branchName: string, teamKeys?: string[] | null): string[];
+/**
+ * Check if branch should be processed for Linear updates
+ * @param branchName - The branch name to check
+ * @param skipBranches - Branches to skip (default: main, master, develop without issue IDs)
+ * @returns true if branch should be processed
+ */
+export declare function shouldProcessBranch(branchName: string, skipBranches?: string[]): boolean;

package/dist/lib/parse-issues.js

@@ -1,46 +1,48 @@
 "use strict";
+/**
+ * Extract Linear issue IDs from branch name ONLY
+ * This enforces a single source of truth for issue tracking
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseCommit = parseCommit;
-exports.parseIssues = parseIssues;
+exports.parseIssuesFromBranch = parseIssuesFromBranch;
+exports.shouldProcessBranch = shouldProcessBranch;
 /**
- * Extract Linear issue IDs from a commit
- * @param commit - The commit object from semantic-release
+ * Extract Linear issue IDs from a branch name
+ * @param branchName - The branch name to parse
  * @param teamKeys - Optional list of team keys to filter by
- * @returns Set of unique issue identifiers
+ * @returns Array of unique issue identifiers
  */
-function parseCommit(commit, teamKeys = null) {
+function parseIssuesFromBranch(branchName, teamKeys = null) {
     const issues = new Set();
     // Build regex pattern based on team keys
     const teamPattern = teamKeys ? `(?:${teamKeys.join("|")})` : "[A-Z]+";
-    // Pattern matches: ENG-123, FEAT-45, etc.
+    // Pattern matches: feature/ENG-123-description, ENG-123, bugfix/FEAT-45, etc.
     const issuePattern = new RegExp(`\\b(${teamPattern}-\\d+)\\b`, "gi");
-    // Search in commit message
-    if (commit.message) {
-        const messageMatches = Array.from(commit.message.matchAll(issuePattern));
-        for (const match of messageMatches) {
-            issues.add(match[1].toUpperCase());
-        }
-    }
-    // Search in commit body
-    if (commit.body) {
-        const bodyMatches = Array.from(commit.body.matchAll(issuePattern));
-        for (const match of bodyMatches) {
-            issues.add(match[1].toUpperCase());
-        }
+    const matches = Array.from(branchName.matchAll(issuePattern));
+    for (const match of matches) {
+        issues.add(match[1].toUpperCase());
     }
-    return issues;
+    return Array.from(issues);
 }
 /**
- * Extract all Linear issue IDs from a list of commits
- * @param commits - Array of commit objects
- * @param teamKeys - Optional list of team keys to filter by
- * @returns Array of unique issue identifiers
+ * Check if branch should be processed for Linear updates
+ * @param branchName - The branch name to check
+ * @param skipBranches - Branches to skip (default: main, master, develop without issue IDs)
+ * @returns true if branch should be processed
  */
-function parseIssues(commits, teamKeys = null) {
-    const allIssues = new Set();
-    commits.forEach((commit) => {
-        const commitIssues = parseCommit(commit, teamKeys);
-        commitIssues.forEach((issue) => allIssues.add(issue));
-    });
-    return Array.from(allIssues);
+function shouldProcessBranch(branchName, skipBranches = [
+    "main",
+    "master",
+    "develop",
+    "staging",
+    "production",
+]) {
+    // Skip certain branches UNLESS they contain an issue ID
+    if (skipBranches.includes(branchName)) {
+        // These branches are OK if they contain an issue ID
+        const hasIssue = /[A-Z]+-\d+/.test(branchName);
+        return hasIssue;
+    }
+    // Process any other branch that contains an issue ID
+    return /[A-Z]+-\d+/.test(branchName);
 }

package/dist/lib/parse-issues.test.js

@@ -2,22 +2,38 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const parse_issues_1 = require("./parse-issues");
 describe("parse-issues", () => {
-    test("extracts Linear issue IDs from commits", () => {
-        const commits = [
-            { message: "fix: solve ENG-123 and FEAT-456" },
-            {
-                message: "feat: new feature",
-                body: "Closes BUG-789",
-            },
-            { message: "chore: no issues here" },
-        ];
-        const result = (0, parse_issues_1.parseIssues)(commits);
-        expect(result).toEqual(expect.arrayContaining(["ENG-123", "FEAT-456", "BUG-789"]));
-        expect(result).toHaveLength(3);
+    test("extracts Linear issue IDs from branch name", () => {
+        const branchName = "feature/ENG-123-add-new-feature";
+        const result = (0, parse_issues_1.parseIssuesFromBranch)(branchName);
+        expect(result).toEqual(["ENG-123"]);
+    });
+    test("extracts multiple issue IDs from branch name", () => {
+        const branchName = "fix/ENG-123-FEAT-456-bug-fix";
+        const result = (0, parse_issues_1.parseIssuesFromBranch)(branchName);
+        expect(result).toEqual(expect.arrayContaining(["ENG-123", "FEAT-456"]));
+        expect(result).toHaveLength(2);
     });
     test("filters by team keys when provided", () => {
-        const commits = [{ message: "fix: ENG-123 OTHER-456" }];
-        const result = (0, parse_issues_1.parseIssues)(commits, ["ENG"]);
+        const branchName = "feature/ENG-123-OTHER-456";
+        const result = (0, parse_issues_1.parseIssuesFromBranch)(branchName, ["ENG"]);
         expect(result).toEqual(["ENG-123"]);
     });
+    test("returns empty array for branch without issues", () => {
+        const branchName = "feature/no-issues-here";
+        const result = (0, parse_issues_1.parseIssuesFromBranch)(branchName);
+        expect(result).toEqual([]);
+    });
+    test("shouldProcessBranch returns false for skip branches without issues", () => {
+        expect((0, parse_issues_1.shouldProcessBranch)("main", ["main", "master"])).toBe(false);
+        expect((0, parse_issues_1.shouldProcessBranch)("master", ["main", "master"])).toBe(false);
+    });
+    test("shouldProcessBranch returns true for skip branches with issues", () => {
+        expect((0, parse_issues_1.shouldProcessBranch)("main-ENG-123", ["main", "master"])).toBe(true);
+    });
+    test("shouldProcessBranch returns true for feature branches with issues", () => {
+        expect((0, parse_issues_1.shouldProcessBranch)("feature/ENG-123", ["main", "master"])).toBe(true);
+    });
+    test("shouldProcessBranch returns false for feature branches without issues", () => {
+        expect((0, parse_issues_1.shouldProcessBranch)("feature/no-issues", ["main", "master"])).toBe(false);
+    });
 });

package/dist/lib/success.d.ts

@@ -2,9 +2,14 @@ import { SuccessContext } from "semantic-release";
 import { PluginConfig, LinearContext } from "../types";
 interface ExtendedContext extends SuccessContext {
     linear?: LinearContext;
+    branch: {
+        name: string;
+        [key: string]: unknown;
+    };
 }
 /**
  * Update Linear issues after a successful release
+ * Only uses branch name for issue detection - single source of truth
  */
 export declare function success(pluginConfig: PluginConfig, context: ExtendedContext): Promise<void>;
 export {};

package/dist/lib/success.js

@@ -5,31 +5,45 @@ const linear_client_1 = require("./linear-client");
 const parse_issues_1 = require("./parse-issues");
 /**
  * Update Linear issues after a successful release
+ * Only uses branch name for issue detection - single source of truth
  */
 async function success(pluginConfig, context) {
-    const { logger, nextRelease, commits, linear } = context;
+    const { logger, nextRelease, linear, branch } = context;
     if (!linear) {
         logger.log("Linear context not found, skipping issue updates");
         return;
     }
-    const { removeOldLabels = true, addComment = false, dryRun = false, } = pluginConfig;
+    if (!branch.name) {
+        logger.log("No branch name available, skipping Linear updates");
+        return;
+    }
+    const { removeOldLabels = true, addComment = false, dryRun = false, skipBranches = ["main", "master", "develop", "staging", "production"], requireIssueInBranch = true, } = pluginConfig;
+    // Check if this branch should be processed
+    if (requireIssueInBranch && !(0, parse_issues_1.shouldProcessBranch)(branch.name, skipBranches)) {
+        logger.log(`Branch "${branch.name}" doesn't contain Linear issues or is in skip list, skipping updates`);
+        return;
+    }
     const client = new linear_client_1.LinearClient(linear.apiKey);
     const version = nextRelease.version;
     const channel = nextRelease.channel || "latest";
     // Format the label based on configuration
     const labelName = `${linear.labelPrefix}${version}`;
     const labelColor = getLabelColor(nextRelease.type);
-    logger.log(`Updating Linear issues for release ${version} (${channel})`);
-    // Extract issue IDs from commits
-    const issueIds = (0, parse_issues_1.parseIssues)(commits, linear.teamKeys);
+    logger.log(`Updating Linear issues for release ${version} (${channel}) from branch "${branch.name}"`);
+    // Extract issue IDs from branch name ONLY
+    const issueIds = (0, parse_issues_1.parseIssuesFromBranch)(branch.name, linear.teamKeys);
     if (issueIds.length === 0) {
-        logger.log("No Linear issues found in commits");
+        logger.log(`No Linear issues found in branch name "${branch.name}"`);
+        if (requireIssueInBranch) {
+            logger.warn("⚠️  Consider using branch names like: feature/ENG-123-description");
+        }
         return;
     }
-    logger.log(`Found ${issueIds.length} Linear issue(s): ${issueIds.join(", ")}`);
+    logger.log(`Found ${issueIds.length} Linear issue(s) in branch "${branch.name}": ${issueIds.join(", ")}`);
     if (dryRun) {
         logger.log("[Dry run] Would update issues:", issueIds);
         logger.log(`[Dry run] Would apply label: ${labelName}`);
+        logger.log(`[Dry run] Branch: ${branch.name}`);
         return;
     }
     // Ensure the version label exists
@@ -41,7 +55,7 @@ async function success(pluginConfig, context) {
             // Get the issue first
             const issue = await client.getIssue(issueId);
             if (!issue) {
-                logger.warn(`Issue ${issueId} not found, skipping`);
+                logger.warn(`Issue ${issueId} not found in Linear, skipping`);
                 return { issueId, status: "not_found" };
             }
             // Remove old version labels if configured
@@ -52,7 +66,7 @@ async function success(pluginConfig, context) {
             await client.addLabelToIssue(issue.id, label.id);
             // Add comment if configured
             if (addComment) {
-                const comment = formatComment(version, channel, nextRelease);
+                const comment = formatComment(version, channel, nextRelease, branch.name);
                 await client.addComment(issue.id, comment);
             }
             logger.log(`✓ Updated issue ${issueId}`);
@@ -89,10 +103,11 @@ function getLabelColor(releaseType) {
 /**
  * Format comment for Linear issue
  */
-function formatComment(version, channel, release) {
+function formatComment(version, channel, release, branchName) {
     const emoji = channel === "latest" ? "🚀" : "🔬";
     const channelText = channel === "latest" ? "stable" : channel;
     let comment = `${emoji} **Released in \`v${version}\`** (${channelText})\n\n`;
+    comment += `📌 Released from branch: \`${branchName}\`\n\n`;
     const githubRepo = process.env.GITHUB_REPOSITORY;
     if (release.gitTag && githubRepo) {
         comment += `[View release →](https://github.com/${githubRepo}/releases/tag/${release.gitTag})`;

package/dist/types.d.ts

@@ -11,6 +11,10 @@ export interface PluginConfig {
     addComment?: boolean;
     /** Preview changes without updating Linear (default: false) */
     dryRun?: boolean;
+    /** Branches to skip unless they contain issue IDs (default: ["main", "master", "develop", "staging", "production"]) */
+    skipBranches?: string[];
+    /** Require issues in branch name to process (default: true) */
+    requireIssueInBranch?: boolean;
 }
 export interface LinearContext {
     apiKey: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "semantic-release-linear-app",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Semantic-release plugin to update Linear issues with version labels",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/src/lib/parse-issues.test.ts

@@ -1,28 +1,49 @@
-import { parseIssues } from "./parse-issues";
-import { Commit } from "semantic-release";
+import { parseIssuesFromBranch, shouldProcessBranch } from "./parse-issues";
 
 describe("parse-issues", () => {
-  test("extracts Linear issue IDs from commits", () => {
-    const commits = [
-      { message: "fix: solve ENG-123 and FEAT-456" },
-      {
-        message: "feat: new feature",
-        body: "Closes BUG-789",
-      },
-      { message: "chore: no issues here" },
-    ] as Commit[];
-
-    const result = parseIssues(commits);
-    expect(result).toEqual(
-      expect.arrayContaining(["ENG-123", "FEAT-456", "BUG-789"]),
-    );
-    expect(result).toHaveLength(3);
+  test("extracts Linear issue IDs from branch name", () => {
+    const branchName = "feature/ENG-123-add-new-feature";
+    const result = parseIssuesFromBranch(branchName);
+    expect(result).toEqual(["ENG-123"]);
   });
 
-  test("filters by team keys when provided", () => {
-    const commits = [{ message: "fix: ENG-123 OTHER-456" }] as Commit[];
+  test("extracts multiple issue IDs from branch name", () => {
+    const branchName = "fix/ENG-123-FEAT-456-bug-fix";
+    const result = parseIssuesFromBranch(branchName);
+    expect(result).toEqual(expect.arrayContaining(["ENG-123", "FEAT-456"]));
+    expect(result).toHaveLength(2);
+  });
 
-    const result = parseIssues(commits, ["ENG"]);
+  test("filters by team keys when provided", () => {
+    const branchName = "feature/ENG-123-OTHER-456";
+    const result = parseIssuesFromBranch(branchName, ["ENG"]);
     expect(result).toEqual(["ENG-123"]);
   });
+
+  test("returns empty array for branch without issues", () => {
+    const branchName = "feature/no-issues-here";
+    const result = parseIssuesFromBranch(branchName);
+    expect(result).toEqual([]);
+  });
+
+  test("shouldProcessBranch returns false for skip branches without issues", () => {
+    expect(shouldProcessBranch("main", ["main", "master"])).toBe(false);
+    expect(shouldProcessBranch("master", ["main", "master"])).toBe(false);
+  });
+
+  test("shouldProcessBranch returns true for skip branches with issues", () => {
+    expect(shouldProcessBranch("main-ENG-123", ["main", "master"])).toBe(true);
+  });
+
+  test("shouldProcessBranch returns true for feature branches with issues", () => {
+    expect(shouldProcessBranch("feature/ENG-123", ["main", "master"])).toBe(
+      true,
+    );
+  });
+
+  test("shouldProcessBranch returns false for feature branches without issues", () => {
+    expect(shouldProcessBranch("feature/no-issues", ["main", "master"])).toBe(
+      false,
+    );
+  });
 });

package/src/lib/parse-issues.ts

@@ -1,58 +1,57 @@
-import { Commit } from "semantic-release";
+/**
+ * Extract Linear issue IDs from branch name ONLY
+ * This enforces a single source of truth for issue tracking
+ */
 
 /**
- * Extract Linear issue IDs from a commit
- * @param commit - The commit object from semantic-release
+ * Extract Linear issue IDs from a branch name
+ * @param branchName - The branch name to parse
  * @param teamKeys - Optional list of team keys to filter by
- * @returns Set of unique issue identifiers
+ * @returns Array of unique issue identifiers
  */
-export function parseCommit(
-  commit: Commit,
+export function parseIssuesFromBranch(
+  branchName: string,
   teamKeys: string[] | null = null,
-): Set<string> {
+): string[] {
   const issues = new Set<string>();
 
   // Build regex pattern based on team keys
   const teamPattern = teamKeys ? `(?:${teamKeys.join("|")})` : "[A-Z]+";
 
-  // Pattern matches: ENG-123, FEAT-45, etc.
+  // Pattern matches: feature/ENG-123-description, ENG-123, bugfix/FEAT-45, etc.
   const issuePattern = new RegExp(`\\b(${teamPattern}-\\d+)\\b`, "gi");
 
-  // Search in commit message
-  if (commit.message) {
-    const messageMatches = Array.from(commit.message.matchAll(issuePattern));
-    for (const match of messageMatches) {
-      issues.add(match[1].toUpperCase());
-    }
-  }
-
-  // Search in commit body
-  if (commit.body) {
-    const bodyMatches = Array.from(commit.body.matchAll(issuePattern));
-    for (const match of bodyMatches) {
-      issues.add(match[1].toUpperCase());
-    }
+  const matches = Array.from(branchName.matchAll(issuePattern));
+  for (const match of matches) {
+    issues.add(match[1].toUpperCase());
   }
 
-  return issues;
+  return Array.from(issues);
 }
 
 /**
- * Extract all Linear issue IDs from a list of commits
- * @param commits - Array of commit objects
- * @param teamKeys - Optional list of team keys to filter by
- * @returns Array of unique issue identifiers
+ * Check if branch should be processed for Linear updates
+ * @param branchName - The branch name to check
+ * @param skipBranches - Branches to skip (default: main, master, develop without issue IDs)
+ * @returns true if branch should be processed
  */
-export function parseIssues(
-  commits: readonly Commit[],
-  teamKeys: string[] | null = null,
-): string[] {
-  const allIssues = new Set<string>();
-
-  commits.forEach((commit) => {
-    const commitIssues = parseCommit(commit, teamKeys);
-    commitIssues.forEach((issue) => allIssues.add(issue));
-  });
+export function shouldProcessBranch(
+  branchName: string,
+  skipBranches: string[] = [
+    "main",
+    "master",
+    "develop",
+    "staging",
+    "production",
+  ],
+): boolean {
+  // Skip certain branches UNLESS they contain an issue ID
+  if (skipBranches.includes(branchName)) {
+    // These branches are OK if they contain an issue ID
+    const hasIssue = /[A-Z]+-\d+/.test(branchName);
+    return hasIssue;
+  }
 
-  return Array.from(allIssues);
+  // Process any other branch that contains an issue ID
+  return /[A-Z]+-\d+/.test(branchName);
 }

package/src/lib/success.ts

@@ -1,6 +1,6 @@
 import { SuccessContext } from "semantic-release";
 import { LinearClient } from "./linear-client";
-import { parseIssues } from "./parse-issues";
+import { parseIssuesFromBranch, shouldProcessBranch } from "./parse-issues";
 import {
   PluginConfig,
   LinearContext,
@@ -10,28 +10,48 @@ import {
 
 interface ExtendedContext extends SuccessContext {
   linear?: LinearContext;
+  branch: {
+    name: string;
+    [key: string]: unknown;
+  };
 }
 
 /**
  * Update Linear issues after a successful release
+ * Only uses branch name for issue detection - single source of truth
  */
 export async function success(
   pluginConfig: PluginConfig,
   context: ExtendedContext,
 ): Promise<void> {
-  const { logger, nextRelease, commits, linear } = context;
+  const { logger, nextRelease, linear, branch } = context;
 
   if (!linear) {
     logger.log("Linear context not found, skipping issue updates");
     return;
   }
 
+  if (!branch.name) {
+    logger.log("No branch name available, skipping Linear updates");
+    return;
+  }
+
   const {
     removeOldLabels = true,
     addComment = false,
     dryRun = false,
+    skipBranches = ["main", "master", "develop", "staging", "production"],
+    requireIssueInBranch = true,
   } = pluginConfig;
 
+  // Check if this branch should be processed
+  if (requireIssueInBranch && !shouldProcessBranch(branch.name, skipBranches)) {
+    logger.log(
+      `Branch "${branch.name}" doesn't contain Linear issues or is in skip list, skipping updates`,
+    );
+    return;
+  }
+
   const client = new LinearClient(linear.apiKey);
   const version = nextRelease.version;
   const channel = nextRelease.channel || "latest";
@@ -40,23 +60,31 @@ export async function success(
   const labelName = `${linear.labelPrefix}${version}`;
   const labelColor = getLabelColor(nextRelease.type as ReleaseType);
 
-  logger.log(`Updating Linear issues for release ${version} (${channel})`);
+  logger.log(
+    `Updating Linear issues for release ${version} (${channel}) from branch "${branch.name}"`,
+  );
 
-  // Extract issue IDs from commits
-  const issueIds = parseIssues(commits, linear.teamKeys);
+  // Extract issue IDs from branch name ONLY
+  const issueIds = parseIssuesFromBranch(branch.name, linear.teamKeys);
 
   if (issueIds.length === 0) {
-    logger.log("No Linear issues found in commits");
+    logger.log(`No Linear issues found in branch name "${branch.name}"`);
+    if (requireIssueInBranch) {
+      logger.warn(
+        "⚠️  Consider using branch names like: feature/ENG-123-description",
+      );
+    }
     return;
   }
 
   logger.log(
-    `Found ${issueIds.length} Linear issue(s): ${issueIds.join(", ")}`,
+    `Found ${issueIds.length} Linear issue(s) in branch "${branch.name}": ${issueIds.join(", ")}`,
   );
 
   if (dryRun) {
     logger.log("[Dry run] Would update issues:", issueIds);
     logger.log(`[Dry run] Would apply label: ${labelName}`);
+    logger.log(`[Dry run] Branch: ${branch.name}`);
     return;
   }
 
@@ -72,7 +100,7 @@ export async function success(
         const issue = await client.getIssue(issueId);
 
         if (!issue) {
-          logger.warn(`Issue ${issueId} not found, skipping`);
+          logger.warn(`Issue ${issueId} not found in Linear, skipping`);
           return { issueId, status: "not_found" };
         }
 
@@ -86,7 +114,12 @@ export async function success(
 
         // Add comment if configured
         if (addComment) {
-          const comment = formatComment(version, channel, nextRelease);
+          const comment = formatComment(
+            version,
+            channel,
+            nextRelease,
+            branch.name,
+          );
           await client.addComment(issue.id, comment);
         }
 
@@ -144,11 +177,13 @@ function formatComment(
   version: string,
   channel: string,
   release: SuccessContext["nextRelease"],
+  branchName: string,
 ): string {
   const emoji = channel === "latest" ? "🚀" : "🔬";
   const channelText = channel === "latest" ? "stable" : channel;
 
   let comment = `${emoji} **Released in \`v${version}\`** (${channelText})\n\n`;
+  comment += `📌 Released from branch: \`${branchName}\`\n\n`;
 
   const githubRepo = process.env.GITHUB_REPOSITORY;
   if (release.gitTag && githubRepo) {

package/src/types.ts

@@ -16,6 +16,12 @@ export interface PluginConfig {
 
   /** Preview changes without updating Linear (default: false) */
   dryRun?: boolean;
+
+  /** Branches to skip unless they contain issue IDs (default: ["main", "master", "develop", "staging", "production"]) */
+  skipBranches?: string[];
+
+  /** Require issues in branch name to process (default: true) */
+  requireIssueInBranch?: boolean;
 }
 
 export interface LinearContext {