TT-17162: support scoped tokens for branch suggestion

olamilekan000 · olamilekan000 · commit 7962cbd23ae3 · 2026-05-11T12:22:55.000+01:00
diff --git a/.github/workflows/branch-suggestion.yml b/.github/workflows/branch-suggestion.yml
@@ -5,9 +5,12 @@ on:
     types: [opened, synchronize, reopened, ready_for_review]
   workflow_call:
     secrets:
-      JIRA_TOKEN:
+      JIRA_READ_AUTH:
         required: true
-        description: 'Base64 encoded JIRA API token'
+        description: 'Base64 encoded Jira email and scoped API token'
+      JIRA_BASE_URL:
+        required: true
+        description: 'Scoped Jira API base URL, e.g. https://api.atlassian.com/ex/jira/<cloudId>'
 
 permissions:
   pull-requests: write
@@ -40,7 +43,8 @@ jobs:
         working-directory: branch-suggestion
         env:
           VISOR_WORKSPACE_ENABLED: "false"
-          JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
+          JIRA_READ_AUTH: ${{ secrets.JIRA_READ_AUTH }}
+          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_TITLE: ${{ github.event.pull_request.title }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
diff --git a/.github/workflows/example-usage.yml.template b/.github/workflows/example-usage.yml.template
@@ -15,4 +15,7 @@ jobs:
   branch-suggestions:
     uses: TykTechnologies/REFINE/.github/workflows/branch-suggestion.yml@b469f63c328ddc43e222dac10487f0a19cd0add1  # main
     secrets:
-      JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
+      # JIRA_READ_AUTH should be base64-encoded from "your-email@example.com:your-scoped-jira-api-token".
+      JIRA_READ_AUTH: ${{ secrets.JIRA_READ_AUTH }}
+      # JIRA_BASE_URL should be "https://api.atlassian.com/ex/jira/<cloudId>".
+      JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
diff --git a/branch-suggestion/README.md b/branch-suggestion/README.md
@@ -19,7 +19,8 @@ Add this workflow to your repository to enable automatic branch suggestions:
 1. Copy `.github/workflows/example-usage.yml.template` to your repository as `.github/workflows/branch-suggestion.yml`
 
 2. Add required secrets to your repository (Settings → Secrets and variables → Actions):
-   - `JIRA_TOKEN`: Base64 encoded JIRA API token
+   - `JIRA_READ_AUTH`: Base64 encoded Jira account email and scoped API token, generated from `email:api_token`
+   - `JIRA_BASE_URL`: Scoped Jira API base URL, for example `https://api.atlassian.com/ex/jira/<cloudId>`
 3. That's it! The workflow will automatically analyze PRs and post branch suggestions.
 
 ### Example Workflow Configuration
@@ -37,7 +38,8 @@ jobs:
   branch-suggestions:
     uses: TykTechnologies/REFINE/.github/workflows/branch-suggestion.yml@main
     secrets:
-      JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
+      JIRA_READ_AUTH: ${{ secrets.JIRA_READ_AUTH }}
+      JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
 ```
 
 ## How It Works
@@ -95,7 +97,8 @@ npm install -g @probelabs/visor
 
 3. Set up environment variables:
 ```bash
-export JIRA_TOKEN="your-jira-api-token"
+export JIRA_READ_AUTH="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)"
+export JIRA_BASE_URL="https://api.atlassian.com/ex/jira/your-cloud-id"
 ```
 
 ### Test Individual Scripts
@@ -138,8 +141,9 @@ node scripts/jira/get-fixedversion.js "feature/TT-12345-fix-auth"
 
 **Exit codes:**
 - `0`: Success (fix versions found)
-- `1`: Error (ticket found but no fix versions set)
+- `1`: Error (JIRA API or configuration error)
 - `2`: No JIRA ticket found
+- `3`: Ticket found but no fix versions set
 
 #### Test Branch Matcher
 
@@ -183,13 +187,15 @@ node scripts/github/add-pr-comment.js \
 
 ```bash
 # Test with a real ticket
-env JIRA_TOKEN="your-token" \
+env JIRA_READ_AUTH="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)" \
+    JIRA_BASE_URL="https://api.atlassian.com/ex/jira/your-cloud-id" \
     PR_TITLE="TT-12345" \
     REPOSITORY="TykTechnologies/tyk" \
     visor --config branch_suggestion.yml
 
 # Test with TIB ticket (different version format)
-env JIRA_TOKEN="your-token" \
+env JIRA_READ_AUTH="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)" \
+    JIRA_BASE_URL="https://api.atlassian.com/ex/jira/your-cloud-id" \
     PR_TITLE="TT-5433" \
     REPOSITORY="TykTechnologies/tyk-identity-broker" \
     visor --config branch_suggestion.yml
@@ -261,7 +267,8 @@ BRANCH SUGGESTION ANALYSIS
 ### Environment Variables
 
 #### Required
-- `JIRA_TOKEN`: Base64 encoded JIRA API token
+- `JIRA_READ_AUTH`: Base64 encoded Jira account email and scoped API token, generated from `email:api_token`
+- `JIRA_BASE_URL`: Scoped Jira API base URL, for example `https://api.atlassian.com/ex/jira/<cloudId>`
 
 #### Optional (for PR comment posting)
 - `GITHUB_TOKEN`: GitHub token (automatically provided in GitHub Actions)
@@ -313,9 +320,11 @@ The tool automatically adapts to different branching strategies:
 **Symptom:** Error message about authentication
 
 **Solution:**
-1. Generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens
-2. Base64 encode the token with your email (e.g., `echo -n "email:token" | base64`)
-3. Ensure the token has not expired
+1. Generate a scoped API token at https://id.atlassian.com/manage-profile/security/api-tokens
+2. Ensure the token has Jira read scope, such as `read:jira-work`
+3. Base64 encode the token with your email (for example, `printf '%s' 'email:token' | base64`)
+4. Set `JIRA_BASE_URL` to the scoped Jira API base URL
+5. Ensure the token owner can browse the Jira project
 
 ### GitHub API rate limiting
 
diff --git a/branch-suggestion/branch_suggestion.yml b/branch-suggestion/branch_suggestion.yml
@@ -25,9 +25,18 @@ checks:
       BRANCH_NAME="${BRANCH_NAME:-feature/TT-12345-test}"
       REPO="${REPOSITORY:-TykTechnologies/tyk}"
 
+      # Visor can execute this check from a fresh temporary worktree.
+      # Install dependencies there when node_modules is not present.
+      if [ ! -d node_modules ]; then
+        npm ci --ignore-scripts
+      fi
+
       set +e
-      JIRA_RESULT=$(node scripts/jira/get-fixedversion.js "$PR_TITLE" "$BRANCH_NAME")
+      JIRA_ERROR_FILE=$(mktemp)
+      JIRA_RESULT=$(node scripts/jira/get-fixedversion.js "$PR_TITLE" "$BRANCH_NAME" 2>"$JIRA_ERROR_FILE")
       JIRA_EXIT_CODE=$?
+      JIRA_ERROR=$(cat "$JIRA_ERROR_FILE")
+      rm -f "$JIRA_ERROR_FILE"
       set -e
 
       # Handle exit codes
@@ -36,7 +45,14 @@ checks:
         exit 0
       fi
       if [ $JIRA_EXIT_CODE -eq 1 ]; then
-        echo '[{"file": "branch-suggestion", "line": 0, "message": "JIRA API or configuration error (e.g. invalid token).", "severity": "critical", "ruleId": "command/execution_error"}]'
+        MESSAGE=$(printf 'JIRA API or configuration error: %s' "${JIRA_ERROR:-Unknown error}")
+        jq -n --arg message "$MESSAGE" '[{
+          file: "branch-suggestion",
+          line: 0,
+          message: $message,
+          severity: "critical",
+          ruleId: "command/execution_error"
+        }]'
         exit 0
       fi
       if [ $JIRA_EXIT_CODE -eq 3 ]; then
diff --git a/branch-suggestion/scripts/common/match-branches.js b/branch-suggestion/scripts/common/match-branches.js
@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 import dotenv from 'dotenv';
 
-// Only load .env if JIRA_TOKEN is not already set (to avoid log output in CI)
-// Silence dotenv v17+ logging
-if (!process.env.JIRA_TOKEN) {
-    process.env.DOTENV_LOG_LEVEL = 'error';
-    dotenv.config();
+// Keep local .env fallback for manual usage, but do not let dotenv write to stdout.
+if (!process.env.JIRA_READ_AUTH && !process.env.JIRA_TOKEN) {
+    dotenv.config({ quiet: true });
 }
 
 /**
@@ -346,4 +344,3 @@ export {
 if (import.meta.url === `file://${process.argv[1]}`) {
     main();
 }
-
diff --git a/branch-suggestion/scripts/jira/__tests__/jira-api.test.js b/branch-suggestion/scripts/jira/__tests__/jira-api.test.js
@@ -1,9 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 // Set env var before importing
-process.env.JIRA_TOKEN = 'test-token';
+process.env.JIRA_READ_AUTH = 'test-token';
+process.env.JIRA_BASE_URL = 'https://api.atlassian.com/ex/jira/cloud-123';
 
-import { extractJQL, jiraAPI, searchIssues, getIssue, formatIssue, main } from '../jira-api.js';
+import { extractJQL, jiraAPI, searchIssues, getIssue, formatIssue, getJiraApiBaseUrl, main } from '../jira-api.js';
 import readline from 'readline';
 
 // Mock fetch
@@ -51,9 +52,9 @@ describe('jiraAPI', () => {
     process.env = originalEnv;
   });
 
-  it('should throw error if JIRA_TOKEN is not set', async () => {
-    delete process.env.JIRA_TOKEN;
-    await expect(jiraAPI('/test')).rejects.toThrow('JIRA_TOKEN must be set');
+  it('should throw error if JIRA_READ_AUTH is not set', async () => {
+    delete process.env.JIRA_READ_AUTH;
+    await expect(jiraAPI('/test')).rejects.toThrow('JIRA_READ_AUTH must be set');
   });
 
   it('should handle 401 Unauthorized error', async () => {
@@ -86,11 +87,44 @@ describe('jiraAPI', () => {
     const result = await jiraAPI('/test');
     expect(result).toEqual(mockData);
   });
+
+  it('should throw error if JIRA_BASE_URL is not set', async () => {
+    delete process.env.JIRA_BASE_URL;
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({})
+    });
+
+    await expect(jiraAPI('/test')).rejects.toThrow('JIRA_BASE_URL must be set');
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it('should use JIRA_BASE_URL for scoped API token requests', async () => {
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({})
+    });
+
+    await jiraAPI('/test');
+
+    expect(global.fetch.mock.calls[0][0]).toBe('https://api.atlassian.com/ex/jira/cloud-123/rest/api/3/test');
+  });
+
+  it('should remove trailing slash from JIRA_BASE_URL', () => {
+    process.env.JIRA_BASE_URL = 'https://api.atlassian.com/ex/jira/cloud-123/';
+    expect(getJiraApiBaseUrl()).toBe('https://api.atlassian.com/ex/jira/cloud-123');
+  });
+
+  it('should require JIRA_BASE_URL when building Jira API base URL', () => {
+    delete process.env.JIRA_BASE_URL;
+    expect(() => getJiraApiBaseUrl()).toThrow('JIRA_BASE_URL must be set');
+  });
 });
 
 describe('searchIssues', () => {
   beforeEach(() => {
     global.fetch.mockClear();
+    process.env.JIRA_BASE_URL = 'https://api.atlassian.com/ex/jira/cloud-123';
   });
 
   it('should call jiraAPI with correct parameters', async () => {
@@ -110,6 +144,26 @@ describe('searchIssues', () => {
   });
 });
 
+describe('getIssue', () => {
+  beforeEach(() => {
+    global.fetch.mockClear();
+    process.env.JIRA_BASE_URL = 'https://api.atlassian.com/ex/jira/cloud-123';
+  });
+
+  it('should request only fields needed for branch suggestions', async () => {
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({ key: 'TT-123' })
+    });
+
+    await getIssue('TT-123');
+
+    const url = global.fetch.mock.calls[0][0];
+    expect(url).toContain('/issue/TT-123?');
+    expect(url).toContain('fields=summary,priority,issuetype,fixVersions');
+  });
+});
+
 describe('formatIssue', () => {
   it('should format issue correctly', () => {
     const issue = {
@@ -243,4 +297,4 @@ describe('main execution', () => {
     expect(global.fetch).toHaveBeenCalledTimes(1);
     expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining('Displayed 50 of 100 total issues'));
   });
-});
+});
diff --git a/branch-suggestion/scripts/jira/get-fixedversion.js b/branch-suggestion/scripts/jira/get-fixedversion.js
@@ -2,9 +2,9 @@
 import dotenv from 'dotenv';
 import { jiraAPI, getIssue } from './jira-api.js';
 
-// Only load .env if JIRA_TOKEN is not already set (to avoid log output in CI)
+// Only load .env if auth is not already set (to avoid log output in CI)
 // Silence dotenv v17+ logging
-if (!process.env.JIRA_TOKEN) {
+if (!process.env.JIRA_READ_AUTH) {
     process.env.DOTENV_LOG_LEVEL = 'error';
     dotenv.config();
 }
@@ -214,4 +214,3 @@ export {
 if (import.meta.url === `file://${process.argv[1]}`) {
     main();
 }
-
diff --git a/branch-suggestion/scripts/jira/jira-api.js b/branch-suggestion/scripts/jira/jira-api.js
