Quick Merge Jenkins

A config-driven VSCode helper for test deployments and demand branch workflows. Reads .quick-merge.jsonc from the project root for optional settings.

中文说明

Recommended Workflow

This tool is designed around the typical development workflow. Here's a step-by-step guide:

Step 1: Initialize Config

When using for the first time, click the Quick Merge Jenkins icon in the sidebar. If the project is not configured:

• Create base config: Generate a .quick-merge.jsonc config template in the project root. Customize Jenkins URL, branch settings, etc. as needed.

Step 2: Start a New Demand

When you receive a new requirement, create a demand branch:

• Create Demand Branch: Select type (feature/fix), enter a Chinese description, auto-translate to English and create a new branch from the latest release branch
  • Auto-translation uses DeepSeek API, requires deepseekApiKey in config
  • Example: Enter "用户登录优化" → Creates branch feature_user_login_optimization_20260116

Step 3: Develop & Commit

During development, use this button to commit code:

• Commit changes: Select files to commit first, then confirm/edit the commit message (defaults to the demand description)

Step 4: Deploy to Test

After development, deploy to the test environment:

• Merge to test: Fetch the latest remote updates, then merge current branch into the target test branch and push (no Jenkins)
• Deploy to test: Auto-merge current branch to target test branch (configurable, default pre-test) and trigger Jenkins build
  • Shows merge result (commit, changed files, duration)
  • Shows Jenkins trigger result
• Commit, Merge & Deploy to Test: Commit current changes first, then merge into the target test branch and trigger Jenkins build

Conflict Handling

If conflicts occur during merge:

• The tool lists all conflict files
• Click a conflict file to open VS Code's built-in merge editor
• After resolving, continue pushing, or click to return to original branch

Step 5: Squash Commits

After testing passes, optionally clean up commit history before release:

• Squash commits: Defaults to selecting recent commits with the same prefix on current branch. Manually adjust selection range, then confirm to squash into one commit for a clean history.

Step 6: Create Production Branch

When ready to release:

• Merge into Prod: Create today's release branch from the latest release branch (prefix configurable, e.g., release, hotfix), then merge selected feature branches. This does not trigger an actual production deploy.
• Deploy to Prod: Open the Jenkins page by default; if deployToProd.autoDeploy is enabled, confirm and trigger Jenkins builds for the latest production branch per prefix. If the latest branch is not today, an extra confirmation is required.

Or complete squash and merge in one step:

• Squash & Merge into Prod: First squash commits, then create release branch and merge current branch

After merge actions complete, the extension opens the Jenkins page configured in the selected prefix (falls back to VS Code settings if missing).

Additional Notes

Run Quick Merge Jenkins: Open Config File from the Command Palette to quickly open the config file.

Config File Format

Project root: .quick-merge.jsonc (supports comments)

Example:

{
  // Demand branch settings (created from latest release_YYYYMMDD branch)
  "demandBranch": {
    // Demand type list
    "types": [
      // prefix: branch prefix, commitPrefix: commit message prefix
      { "prefix": "feature", "commitPrefix": "feat" },
      { "prefix": "fix", "commitPrefix": "fix" }
    ],
    // Base branch prefix for matching (default: release)
    "releasePrefix": "release",
    // DeepSeek API key for auto-translation
    "deepseekApiKey": "",
    // DeepSeek API base URL
    "deepseekBaseUrl": "https://api.deepseek.com/v1",
    // DeepSeek model name
    "deepseekModel": "deepseek-chat"
  },
  // Commit settings
  "commit": {
    // Push after commit (default: true)
    "pushAfterCommit": true
  },
  // Deploy to test environment config (targetBranch is also used by Merge to test)
  "deployToTest": {
    // Target branch for merge (default: pre-test)
    "targetBranch": "pre-test",
    // Jenkins trigger config (required for deploy to test)
    "jenkins": {
      // Jenkins base URL (without /job/...)
      "url": "https://jenkins.example.com",
      // Job path in folder/jobName format
      "job": "team/release/deploy-test",
      // Jenkins username
      "user": "jenkins-user",
      // Jenkins API token
      "apiToken": "jenkins-api-token",
      // Enable CSRF crumb (set true if Jenkins has CSRF enabled)
      "crumb": true,
      // Build parameters (supports variables)
      "parameters": {
        "BRANCH": "${currentBranch}",
        "COMMIT": "${headCommit}",
        "ENV": "${deployEnv}"
      }
    }
  },
  // Create production branch config (create today's branch from latest prefix branch)
  "deployToProd": {
    // Branch prefix list for production releases
    "prodPrefix": [
      "release",
      {
        "prefix": "hotfix",
        "jenkins": {
          "url": "https://jenkins-prod.example.com",
          "job": "team/release/deploy-prod"
        }
      }
    ],
    // Auto trigger Jenkins build when clicking Deploy to Prod (default: false)
    "autoDeploy": false
  }
}

Field Reference

• demandBranch: Demand branch settings (optional)
• Demand branches are created from the latest releasePrefix_YYYYMMDD branch (remote preferred); if none found, prompts to select a branch as base
  • types: Demand type list (optional, defaults to feature/fix)
    • prefix: Branch prefix
    • commitPrefix: Commit message prefix (defaults to prefix)
  • releasePrefix: Base branch prefix for matching (default release, also used for prod branch creation)
  • deepseekApiKey: DeepSeek API key (can be stored in config)
  • deepseekBaseUrl: DeepSeek API base URL (default https://api.deepseek.com/v1)
  • deepseekModel: DeepSeek model name (default deepseek-chat)
• deployToTest: Test branch config (optional)
  • targetBranch: Merge target branch (default pre-test, used by Merge to test too)
  • jenkins: Jenkins trigger config (required for Deploy to test)
• commit: Commit config (optional)
  • pushAfterCommit: Push after commit (default true)
• deployToProd: Create production branch config (optional)
  • prodPrefix: Branch prefix list, supports strings or objects { prefix, jenkins } (per-prefix Jenkins config); clicking create shows the latest branch per prefix for multi-select
  • autoDeploy: Auto trigger Jenkins build when clicking Deploy to Prod (default false, requires prodPrefix[].jenkins.job; url/user/token can fall back to VS Code settings; if no parameters provided, the branch param defaults to the latest prod branch ref)
  • branchParamName: Jenkins parameter name for the branch when auto-injecting (default branch)

Jenkins Config

• url: Jenkins base URL (without /job/...)
• job: Job path in folder/jobName format
• user + apiToken: Jenkins user auth (recommended, API token at http://192.168.1.169:8080/user/admin/security/)
• crumb: Set true when CSRF is enabled
• parameters: Supports variables:
  • ${currentBranch} ${sourceBranch} ${targetBranch} ${mergeCommit} ${headCommit} ${deployEnv}
• url, user, apiToken can be omitted if set in VS Code settings
• deployToProd.prodPrefix[].jenkins is used for prod deploy (when autoDeploy is enabled) and to open the Jenkins page after prod merge; falls back to VS Code settings when missing; when parameters are empty, the branch param is sent automatically

Troubleshooting

• Jenkins Crumb 403: Verify user + apiToken are correct, or set crumb to false
• Push failed: Check repo permissions and remote settings

Global Configuration (VS Code Settings)

In addition to the project config file (.quick-merge.jsonc), you can set global parameters in VS Code settings as fallback values. Global settings are ideal for sharing common credentials across multiple projects. Settings in the project config file will override global settings.

Search for quick-merge-jenkins in VS Code settings (Preferences: Open Settings) to find these options:

DeepSeek API Configuration

Used for auto-translation when creating demand branches:

Jenkins Configuration

Used for authentication when triggering Jenkins builds:

Note: Global Jenkins settings are also used as fallback for production deploy (base URL/user/token). The job name still comes from deployToProd.prodPrefix[].jenkins.

💡 Tip: Sensitive information like API Keys and Tokens should be configured in VS Code global settings to avoid committing them to version control.