TT-17162: support scoped tokens for branch suggestion

Author: olamilekan000

.github/workflows/branch-suggestion.yml

@@ -7,7 +7,7 @@ on:
     secrets:
       JIRA_TOKEN:
         required: true
-        description: 'Base64 encoded JIRA API token'
+        description: 'Base64 encoded Jira email and scoped API token'
 
 permissions:
   pull-requests: write

.github/workflows/example-usage.yml.template

@@ -15,4 +15,5 @@ jobs:
   branch-suggestions:
     uses: TykTechnologies/REFINE/.github/workflows/branch-suggestion.yml@b469f63c328ddc43e222dac10487f0a19cd0add1  # main
     secrets:
-      JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
+      # JIRA_TOKEN should be base64-encoded from "your-email@example.com:your-scoped-jira-api-token".
+      JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}

branch-suggestion/README.md

@@ -19,7 +19,7 @@ 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_TOKEN`: Base64 encoded Jira account email and scoped API token, generated from `email:api_token`
 3. That's it! The workflow will automatically analyze PRs and post branch suggestions.
 
 ### Example Workflow Configuration
@@ -95,7 +95,7 @@ npm install -g @probelabs/visor
 
 3. Set up environment variables:
 ```bash
-export JIRA_TOKEN="your-jira-api-token"
+export JIRA_TOKEN="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)"
 ```
 
 ### Test Individual Scripts
@@ -138,8 +138,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 +184,13 @@ node scripts/github/add-pr-comment.js \
 
 ```bash
 # Test with a real ticket
-env JIRA_TOKEN="your-token" \
+env JIRA_TOKEN="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)" \
     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_TOKEN="$(printf '%s' 'your-email@example.com:your-scoped-jira-api-token' | base64)" \
     PR_TITLE="TT-5433" \
     REPOSITORY="TykTechnologies/tyk-identity-broker" \
     visor --config branch_suggestion.yml
@@ -261,7 +262,7 @@ BRANCH SUGGESTION ANALYSIS
 ### Environment Variables
 
 #### Required
-- `JIRA_TOKEN`: Base64 encoded JIRA API token
+- `JIRA_TOKEN`: Base64 encoded Jira account email and scoped API token, generated from `email:api_token`
 
 #### Optional (for PR comment posting)
 - `GITHUB_TOKEN`: GitHub token (automatically provided in GitHub Actions)
@@ -313,9 +314,10 @@ 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. Ensure the token owner can browse the Jira project
 
 ### GitHub API rate limiting
 

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

branch-suggestion/scripts/jira/__tests__/jira-api.test.js

@@ -3,7 +3,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 // Set env var before importing
 process.env.JIRA_TOKEN = 'test-token';
 
-import { extractJQL, jiraAPI, searchIssues, getIssue, formatIssue, main } from '../jira-api.js';
+import { extractJQL, jiraAPI, searchIssues, getIssue, formatIssue, getJiraApiBaseUrl, getJiraCloudId, resetJiraCloudIdCache, main } from '../jira-api.js';
 import readline from 'readline';
 
 // Mock fetch
@@ -45,6 +45,7 @@ describe('jiraAPI', () => {
     vi.resetModules();
     process.env = { ...originalEnv };
     global.fetch.mockClear();
+    resetJiraCloudIdCache();
   });
 
   afterEach(() => {
@@ -57,6 +58,7 @@ describe('jiraAPI', () => {
   });
 
   it('should handle 401 Unauthorized error', async () => {
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
     global.fetch.mockResolvedValue({
       ok: false,
       status: 401,
@@ -67,6 +69,7 @@ describe('jiraAPI', () => {
   });
 
   it('should handle 404 Not Found error', async () => {
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
     global.fetch.mockResolvedValue({
       ok: false,
       status: 404,
@@ -77,6 +80,7 @@ describe('jiraAPI', () => {
   });
 
   it('should return JSON on success', async () => {
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
     const mockData = { key: 'TT-123' };
     global.fetch.mockResolvedValue({
       ok: true,
@@ -86,11 +90,57 @@ describe('jiraAPI', () => {
     const result = await jiraAPI('/test');
     expect(result).toEqual(mockData);
   });
+
+  it('should fetch JIRA_CLOUD_ID from tenant_info when it is not set', async () => {
+    delete process.env.JIRA_CLOUD_ID;
+    global.fetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({ cloudId: 'cloud-123' })
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({})
+      });
+
+    await jiraAPI('/test');
+
+    expect(global.fetch.mock.calls[0][0]).toBe('https://tyktech.atlassian.net/_edge/tenant_info');
+    expect(global.fetch.mock.calls[1][0]).toBe('https://api.atlassian.com/ex/jira/cloud-123/rest/api/3/test');
+  });
+
+  it('should use Atlassian scoped API token URL when JIRA_CLOUD_ID is set', async () => {
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
+    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 build Jira API base URL from JIRA_CLOUD_ID when present', async () => {
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
+    await expect(getJiraApiBaseUrl()).resolves.toBe('https://api.atlassian.com/ex/jira/cloud-123');
+  });
+
+  it('should throw if tenant_info does not return a cloud ID', async () => {
+    delete process.env.JIRA_CLOUD_ID;
+    global.fetch.mockResolvedValue({
+      ok: true,
+      json: vi.fn().mockResolvedValue({})
+    });
+
+    await expect(getJiraCloudId()).rejects.toThrow('JIRA cloud ID was not found');
+  });
 });
 
 describe('searchIssues', () => {
   beforeEach(() => {
     global.fetch.mockClear();
+    process.env.JIRA_CLOUD_ID = 'cloud-123';
   });
 
   it('should call jiraAPI with correct parameters', async () => {
@@ -110,6 +160,26 @@ describe('searchIssues', () => {
   });
 });
 
+describe('getIssue', () => {
+  beforeEach(() => {
+    global.fetch.mockClear();
+    process.env.JIRA_CLOUD_ID = '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 +313,4 @@ describe('main execution', () => {
     expect(global.fetch).toHaveBeenCalledTimes(1);
     expect(consoleLogMock).toHaveBeenCalledWith(expect.stringContaining('Displayed 50 of 100 total issues'));
   });
-});
+});

branch-suggestion/scripts/jira/get-fixedversion.js

@@ -214,4 +214,3 @@ export {
 if (import.meta.url === `file://${process.argv[1]}`) {
     main();
 }
-

branch-suggestion/scripts/jira/jira-api.js

@@ -8,14 +8,54 @@ if (!process.env.JIRA_TOKEN) {
     dotenv.config();
 }
 // JIRA configuration
-const JIRA_BASE_URL = 'https://tyktech.atlassian.net';
+const JIRA_SITE_URL = 'https://tyktech.atlassian.net';
 // We read JIRA_TOKEN dynamically inside jiraAPI to allow testing
+let cachedCloudId = null;
 
 // Debug logging (without exposing sensitive data)
 console.error('DEBUG: Environment check:');
 console.error(`  JIRA_TOKEN: ${process.env.JIRA_TOKEN ? 'SET' : 'EMPTY'}`);
+console.error(`  JIRA_CLOUD_ID: ${process.env.JIRA_CLOUD_ID ? 'SET' : 'EMPTY'}`);
 console.error(`  All JIRA env vars: ${Object.keys(process.env).filter(k => k.includes('JIRA')).join(', ')}`);
 
+async function getJiraCloudId() {
+  if (process.env.JIRA_CLOUD_ID) {
+    return process.env.JIRA_CLOUD_ID;
+  }
+
+  if (cachedCloudId) {
+    return cachedCloudId;
+  }
+
+  const response = await fetch(`${JIRA_SITE_URL}/_edge/tenant_info`, {
+    headers: {
+      'Accept': 'application/json'
+    }
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to fetch JIRA cloud ID (${response.status}): ${error}`);
+  }
+
+  const tenantInfo = await response.json();
+  if (!tenantInfo.cloudId) {
+    throw new Error('JIRA cloud ID was not found in tenant_info response');
+  }
+
+  cachedCloudId = tenantInfo.cloudId;
+  return cachedCloudId;
+}
+
+function resetJiraCloudIdCache() {
+  cachedCloudId = null;
+}
+
+async function getJiraApiBaseUrl() {
+  const cloudId = await getJiraCloudId();
+  return `https://api.atlassian.com/ex/jira/${cloudId}`;
+}
+
 // Extract JQL from URL or use directly
 function extractJQL(input) {
   // Check if input is a URL
@@ -41,7 +81,8 @@ async function jiraAPI(endpoint, options = {}) {
     throw new Error('JIRA_TOKEN must be set in environment variables');
   }
 
-  const response = await fetch(`${JIRA_BASE_URL}/rest/api/3${endpoint}`, {
+  const baseUrl = await getJiraApiBaseUrl();
+  const response = await fetch(`${baseUrl}/rest/api/3${endpoint}`, {
     ...options,
     headers: {
       'Authorization': `Basic ${token}`,
@@ -76,7 +117,7 @@ async function searchIssues(jql, startAt = 0, maxResults = 50) {
 
 // Get issue details
 async function getIssue(issueKey) {
-  return jiraAPI(`/issue/${issueKey}`);
+  return jiraAPI(`/issue/${issueKey}?fields=summary,priority,issuetype,fixVersions`);
 }
 
 // Format issue for display
@@ -118,7 +159,7 @@ function formatIssue(issue, index) {
     lines.push(`   Components: ${issue.fields.components.map(c => c.name).join(', ')}`);
   }
 
-  lines.push(`   Link: ${JIRA_BASE_URL}/browse/${issue.key}`);
+  lines.push(`   Link: ${JIRA_SITE_URL}/browse/${issue.key}`);
 
   return lines.join('\n');
 }
@@ -241,7 +282,7 @@ function exportToCSV(issues) {
       new Date(issue.fields.created).toLocaleDateString(),
       issue.fields.assignee?.displayName || '',
       issue.fields.reporter?.displayName || '',
-      `${JIRA_BASE_URL}/browse/${issue.key}`
+      `${JIRA_SITE_URL}/browse/${issue.key}`
     ];
     rows.push(row.join(','));
   }
@@ -257,10 +298,13 @@ export {
   getIssue,
   formatIssue,
   exportToCSV,
+  getJiraCloudId,
+  getJiraApiBaseUrl,
+  resetJiraCloudIdCache,
   main
 };
 
 // Run main if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
   main().catch(console.error);
-}
+}