TT-17162: support scoped tokens for branch suggestion

[olamilekan000]

change the update scripts to support a scoped Jira API token for branch suggestion.

[probelabs]

This pull request updates the branch suggestion workflow to use scoped Jira API tokens, enhancing security by replacing the previous authentication method. This is a breaking change that requires consumers of the workflow to update their repository secrets.

Files Changed Analysis

The changes are primarily within the branch-suggestion action and its configuration:

• GitHub Workflows (.github/workflows/): branch-suggestion.yml and the example-usage.yml.template are updated to replace the JIRA_TOKEN secret with two new secrets: JIRA_READ_AUTH (a base64-encoded string of email:token) and JIRA_BASE_URL.
• Jira Scripts (branch-suggestion/scripts/jira/): The core logic in jira-api.js is modified to use the new environment variables for API requests. The getIssue function is also optimized to fetch only necessary fields, improving efficiency.
• Tests (branch-suggestion/scripts/jira/__tests__/): The test suite is significantly expanded to cover the new authentication logic, URL construction from JIRA_BASE_URL, and error handling for missing secrets.
• Workflow Configuration (branch-suggestion/branch_suggestion.yml): The check is improved to capture and surface detailed error messages from the Jira script, aiding in debugging configuration issues.
• Documentation (branch-suggestion/README.md): The README is updated with clear instructions for generating and configuring the new scoped token and base URL.

Architecture & Impact Assessment

• What this PR accomplishes: It modernizes the Jira integration by migrating to scoped API tokens, which is a significant security improvement over the previous method.

• Key technical changes introduced:

  1. Breaking Authentication Change: The JIRA_TOKEN secret is replaced by JIRA_READ_AUTH and JIRA_BASE_URL. All consumers must update their repository secrets.
  2. Dynamic API Endpoint: The Jira API base URL is no longer hardcoded and is now configured via the JIRA_BASE_URL secret.
  3. Improved Error Reporting: The workflow now captures stderr from the node script, providing more descriptive error messages in GitHub Actions logs upon failure.

• Affected system components: The primary impact is on all repositories that use the branch-suggestion.yml reusable workflow. This is a breaking change requiring manual secret updates in every consuming repository to maintain functionality.

Authentication Flow

sequenceDiagram
    participant User Repo
    participant Workflow
    participant Jira Script
    participant Atlassian API

    User Repo->>Workflow: Trigger on PR event
    Workflow->>Jira Script: Execute with JIRA_READ_AUTH & JIRA_BASE_URL
    Jira Script->>Atlassian API: GET /ex/jira/{cloudId}/rest/api/3/issue/{key}
    Note over Jira Script,Atlassian API: Auth: Basic base64(email:token)<br/>Endpoint from JIRA_BASE_URL
    Atlassian API-->>Jira Script: Return issue data
    Jira Script-->>Workflow: Return fix versions
    Workflow->>User Repo: Post PR comment with suggestions

Loading

Scope Discovery & Context Expansion

The changes are well-contained within the branch-suggestion directory. However, the operational impact is broad, affecting all external consumers of this reusable workflow. The success of this migration relies on the updated documentation, which has been addressed in this PR.

A minor limitation remains: the Jira site URL (for generating browsable links in script output) is still hardcoded in jira-api.js. This means that while the API interaction is now configurable, the generated links will only be correct for one specific Jira instance, limiting the action's reusability for other organizations.

Metadata

• Review Effort: 3 / 5
• Primary Label: enhancement

---

Powered by Visor from Probelabs

Last updated: 2026-05-11T11:24:51.675Z | Triggered by: pr_updated | Commit: 7962cbd

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

Security Issues (1)

Severity	Location	Issue
🟡 Warning	branch-suggestion/scripts/jira/jira-api.js:18-24	The `JIRA_BASE_URL`, which is sourced from a user-configured secret, is used to construct the request URL without proper validation. This could lead to the `JIRA_READ_AUTH` secret being leaked to an arbitrary domain if the URL is misconfigured to point to a malicious server. As this is a reusable workflow, it should include safeguards to prevent such credential leakage. 💡 Suggestion Validate the hostname of the `JIRA_BASE_URL` to ensure it points to the expected Atlassian domain ('api.atlassian.com') before making any requests. This will prevent credentials from being sent to unintended endpoints. 🔧 Suggested Fix function getJiraApiBaseUrl() { const baseUrl = process.env.JIRA_BASE_URL; if (!baseUrl) { throw new Error('JIRA_BASE_URL must be set in environment variables'); } let url; try { url = new URL(baseUrl); } catch (e) { throw new Error(Invalid JIRA_BASE_URL: ${baseUrl}); } if (url.hostname !== 'api.atlassian.com') { throw new Error(JIRA_BASE_URL hostname must be 'api.atlassian.com', but was '${url.hostname}'); } return baseUrl.replace(//$/, ''); }

Architecture Issues (1)

Severity	Location	Issue
🟡 Warning	branch-suggestion/scripts/jira/jira-api.js:15	The Jira site URL is hardcoded, which limits the reusability of the action. While the API endpoint is now configurable via `JIRA_BASE_URL`, the user-facing links to Jira tickets generated by the script will only work for the `tyktech.atlassian.net` instance. This creates an inconsistent configuration experience and prevents the action from being fully portable to other organizations. 💡 Suggestion To make the action fully reusable, the Jira site URL should also be configurable. Introduce a new secret/environment variable (e.g., `JIRA_SITE_URL`) and use it to construct the browse links for Jira issues on lines 121 and 250.

✅ Performance Check Passed

No performance issues found – changes LGTM.

Quality Issues (1)

Severity	Location	Issue
🟡 Warning	branch-suggestion/scripts/jira/jira-api.js:13	The Jira site URL for generating browsable links to issues is hardcoded. This limits the utility of the action for organizations using a different Jira instance URL. 💡 Suggestion Consider making the `JIRA_SITE_URL` configurable via an environment variable, falling back to the current hardcoded value if the variable is not set. This would improve the reusability of this action for other teams without requiring code changes. For example: `const JIRA_SITE_URL = process.env.JIRA_SITE_URL || 'https://tyktech.atlassian.net';`

---

Powered by Visor from Probelabs

Last updated: 2026-05-11T11:24:40.888Z | Triggered by: pr_updated | Commit: 7962cbd

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

🎯 Recommended Merge Targets

Based on JIRA ticket TT-17162: Use scoped Jira API tokens for branch suggestion workflow

---

📋 Workflow

1. Merge this PR to master first