Super Merger - VS Code Extension

Super Merger is a VS Code extension that helps developers streamline the process of merging code changes into the beta branch. It integrates with Jira and GitHub to automate the collection and merging of pull requests related to a specific release version.

Features

• Jira Integration: Connect to Jira and fetch tickets by Fix Version
• GitHub Integration: Automatically fetch GitHub pull requests linked in Jira tickets
• Tree View: Visual representation of tickets and their associated merge requests
• Merge Automation: Merge pull requests locally or via GitHub API
• Batch Operations: Merge multiple PRs at once
• Status Tracking: Monitor the status of merge requests
• Merge Reports: Generate detailed reports of merge operations

Installation

1. Download the .vsix file from releases
2. Open VS Code
3. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) to open the Command Palette
4. Type "Extensions: Install from VSIX" and select it
5. Navigate to the downloaded .vsix file and install it

Configuration

Before using Super Merger, you need to configure your Jira and GitHub credentials:

Jira Configuration

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Super Merger: Configure Jira"
3. Enter your Jira base URL:
   • For Atlassian Cloud: https://your-company.atlassian.net
   • For Jira Server/Data Center: https://your-jira-server.com
4. Enter your Jira account email:
   • Required for Jira Cloud: Your email address associated with your Jira account
   • Optional for Server/Data Center: Leave empty or enter your username
5. Enter your Jira API token

Getting a Jira API Token

For Jira Cloud:

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a name and click "Create"
4. Copy the token (you won't be able to see it again)
5. Important: Use your email address as the username for authentication

For Jira Server/Data Center:

1. Go to your Jira Server admin panel or user profile
2. Generate an API token or use your password
3. Authentication can be done with username/password or token depending on server configuration

GitHub Configuration

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Super Merger: Configure GitHub"
3. Enter your GitHub API base URL:
   • For GitHub.com: https://api.github.com (default)
   • For GitHub Enterprise: https://your-github-enterprise.com/api/v3
4. Enter your GitHub personal access token
5. Enter your repository in format owner/repo
6. Enter your default beta branch name (default: beta)

Creating a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens (or your GitHub Enterprise equivalent)
2. Click "Generate new token (classic)"
3. Give it a name and select the following scopes:
   • repo (Full control of private repositories)
   • read:org (Read org and team membership)
4. Click "Generate token"
5. Copy the token immediately

GitHub Enterprise Support

Super Merger fully supports GitHub Enterprise Server installations. When configuring GitHub:

1. API URL Format: Use https://your-github-enterprise.com/api/v3

   • Correct: https://github.company.com/api/v3
   • Incorrect: https://github.company.com (missing /api/v3)

2. Token Creation: Create your personal access token in your GitHub Enterprise instance:

   • Navigate to: https://your-github-enterprise.com/settings/tokens
   • Same scopes as GitHub.com: repo and read:org

3. SSL Certificates: The extension supports custom SSL configurations for enterprise environments

4. Repository Format: Use the same owner/repo format as GitHub.com

GitHub Enterprise Troubleshooting

• Connection Issues: Verify your enterprise server allows API access
• SSL Errors: Check if your enterprise uses custom certificates
• Token Permissions: Ensure your token has the required repository access
• URL Format: Always include /api/v3 for enterprise installations

Usage

Loading a Fix Version

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run "Super Merger: Load Fix Version"
3. Enter the fix version (e.g., v1.4-beta)
4. The extension will fetch all Jira tickets with that fix version and their associated GitHub PRs

Using the Tree View

The Super Merger tree view appears in the Explorer sidebar and shows:

• Fix Version: The loaded release version
• Tickets: Jira tickets with the fix version
• Merge Requests: GitHub PRs linked to each ticket

Available Actions

For individual Merge Requests:

• Open MR in Browser: Opens the pull request in your default browser
• Check Merge Status: Fetches the latest status of the pull request
• Fetch Locally: Fetches all remote branches including the PR's source branch
• Merge to Beta Branch: Merges the PR to your beta branch (local or via API)

For individual code lines (in selective merge):

• Copy & Search: Click on any line of code in the diff to:
  • Copy the line text to your clipboard
  • Search for that exact line in the corresponding file in your workspace
  • Navigate to the matching line in the file
  • Highlight the found text for easy identification
  • Visual feedback shows processing and success states

Bulk Operations:

• Super Merger: Merge All to Beta: Merges all open pull requests to the beta branch

Merge Methods

When merging, you can choose between:

1. Local Git Merge: Uses local git commands to merge branches

   • Checks out to beta branch
   • Pulls latest changes
   • Merges the source branch
   • Optionally pushes changes

2. GitHub API Merge: Uses GitHub's API to merge pull requests

   • Merges directly on GitHub
   • Faster but less control over the process

Commands

All commands are available through the Command Palette:

• Super Merger: Configure Jira - Configure Jira connection
• Super Merger: Configure GitHub - Configure GitHub connection
• Super Merger: Test Connections - Test Jira and GitHub connections (shows detailed error info)
• Super Merger: Diagnose Configuration - Show detailed configuration analysis and auth format
• Super Merger: Load Fix Version - Load tickets and PRs for a fix version
• Super Merger: Merge All to Beta - Merge all open PRs to beta branch

Status Bar

The status bar shows:

• Current loaded fix version
• Number of tickets and merge requests
• Click to quickly load a new fix version

Output Panel

The "Super Merger" output panel shows detailed logs of all operations:

• API calls to Jira and GitHub
• Merge operations and their results
• Error messages and debugging information

Settings

You can also configure Super Merger through VS Code settings (settings.json):

For GitHub.com:

{
  "superMerger.jira.url": "https://your-company.atlassian.net",
  "superMerger.jira.email": "your.email@company.com",
  "superMerger.jira.token": "your-jira-api-token",
  "superMerger.github.url": "https://api.github.com",
  "superMerger.github.token": "your-github-pat",
  "superMerger.github.repo": "owner/repository",
  "superMerger.defaultBetaBranch": "beta"
}

For GitHub Enterprise:

{
  "superMerger.jira.url": "https://jira.company.com",
  "superMerger.jira.email": "your.email@company.com",
  "superMerger.jira.token": "your-jira-api-token",
  "superMerger.github.url": "https://github.company.com/api/v3",
  "superMerger.github.token": "your-enterprise-github-pat",
  "superMerger.github.repo": "owner/repository",
  "superMerger.defaultBetaBranch": "beta"
}

Requirements

• VS Code 1.74.0 or higher
• Active Jira instance with API access
• GitHub repository with appropriate permissions
• Git installed and configured in your workspace

Security Notes

• API tokens are stored in VS Code's secure storage
• Tokens are not logged in the output panel
• Use tokens with minimal required permissions

Troubleshooting

Common Issues

1. "Configuration invalid" error

   • Check that all required fields are configured
   • Verify Jira URL format includes protocol (https://)
   • Ensure GitHub repo format is owner/repo

2. "Jira connection test failed" (403 Forbidden)

   • For Jira Cloud: Ensure you've entered your email address (required for authentication)
   • Authentication Format: Jira Cloud uses email:token, not just token
   • Verify your Jira URL is correct
   • Check that your API token is valid and not expired
   • Ensure you have permissions to access the Jira instance
   • Test Command: Use "Super Merger: Test Connections" for detailed error information

3. "GitHub connection test failed"

   • Verify your GitHub token is valid
   • Check that the token has required permissions
   • Ensure the repository exists and you have access
   • For GitHub Enterprise: Verify the API URL format includes /api/v3
   • For GitHub Enterprise: Check SSL certificate configuration

4. "Not in a Git repository" error

   • Open a folder that contains a Git repository
   • Initialize git in your workspace (git init)

5. Merge failures

   • Check that the source branch exists
   • Ensure you have push permissions to the repository
   • Verify the beta branch exists and is up to date

6. GitHub Enterprise specific issues

   • Invalid API URL: Ensure URL format is https://your-server.com/api/v3
   • SSL Certificate errors: Contact your IT admin about certificate trust
   • Network access: Verify the extension can reach your enterprise server
   • Token scope: Ensure tokens have same permissions as GitHub.com tokens

Getting Help

1. Check the "Super Merger" output panel for detailed error messages
2. Verify your configuration using the configure commands
3. Test individual operations before running batch merges

Development

To set up the development environment:

# Clone the repository
git clone <repository-url>
cd super-merger

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

Building the Extension

# Install vsce globally
npm install -g vsce

# Package the extension
vsce package

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.