sonar_link_existing_project

Link an existing SonarQube project to the current directory.

Description

Creates a local configuration file to connect an existing SonarQube project to your local codebase. Useful when you already have a project on SonarQube and want to use Bob the Fixer with it.

Parameters

Parameter	Type	Required	Default	Description
sonarUrl	string	Yes	-	SonarQube server URL
projectKey	string	Yes	-	Existing project key
token	string	Yes	-	Authentication token
projectPath	string	No	Current directory	Project directory

Usage

Basic Link

Link my project to an existing SonarQube project

Tool call:

{
  "sonarUrl": "http://localhost:9000",
  "projectKey": "my-existing-project",
  "token": "squ_abc123def456..."
}

Link Different Directory

Link the backend folder to a SonarQube project

Tool call:

{
  "sonarUrl": "http://localhost:9000",
  "projectKey": "backend-service",
  "token": "squ_abc123def456...",
  "projectPath": "/Users/dev/monorepo/backend"
}

Response Format

Successful Link

PROJECT LINKED SUCCESSFULLY
━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Configuration created

📁 Local Path: /Users/dev/myproject
🔗 SonarQube URL: http://localhost:9000
📊 Project Key: my-existing-project

Config File: /Users/dev/myproject/bobthefixer.env

VERIFICATION:
  ✓ Server connection successful
  ✓ Token valid
  ✓ Project exists
  ✓ Token has project access

📊 PROJECT INFO:
  Name: My Existing Project
  Last Analysis: 2024-01-15 10:30:00
  Quality Gate: PASSED

  Issues:
  ├── Bugs: 3
  ├── Vulnerabilities: 1
  └── Code Smells: 45

READY TO USE:

You can now run:
• sonar_scan_project - Scan with existing project
• sonar_get_project_metrics - View current metrics
• sonar_get_issue_details - Analyze issues

Link Failed

PROJECT LINK FAILED
━━━━━━━━━━━━━━━━━━━

❌ Could not link project

ERRORS:

1. Project not found
   Key: my-wrong-project
   Server: http://localhost:9000

   Available projects with similar names:
   • my-existing-project
   • my-other-project

SUGGESTIONS:

1. Verify project key in SonarQube UI
2. Check token has access to this project
3. Ensure server URL is correct

Getting Required Values

SonarQube URL

Default: http://localhost:9000

For cloud: https://sonarcloud.io
For self-hosted: Your server URL

Project Key

Find in SonarQube UI:

1. Go to your project
2. Look at URL: .../dashboard?id=PROJECT_KEY
3. Or: Project Settings → General

Token

Generate in SonarQube:

1. Account → Security
2. Generate Token
3. Type: Project Analysis Token
4. Select your project

Examples

Example 1: Local SonarQube

Prompt:

Link to my existing project on local SonarQube

Tool Call:

{
  "sonarUrl": "http://localhost:9000",
  "projectKey": "my-app-12345",
  "token": "squ_abc123..."
}

Example 2: SonarCloud

Prompt:

Connect to my SonarCloud project

Tool Call:

{
  "sonarUrl": "https://sonarcloud.io",
  "projectKey": "myorg_myproject",
  "token": "squ_cloud_token..."
}

Example 3: CI/CD Setup

Prompt:

Link the project for CI/CD pipeline

Tool Call:

{
  "sonarUrl": "https://sonar.company.com",
  "projectKey": "backend-service",
  "token": "squ_cicd_token...",
  "projectPath": "/workspace/backend"
}

When to Use

Scenario	Use This Tool
Project exists on SonarQube	✅
Team shared project	✅
CI/CD linking	✅
Brand new project	❌ Use sonar_auto_setup
Need new project	❌ Use sonar_auto_setup

Token Permissions

Required permissions for the token:

Permission	Required	Description
Browse	✅	View project
Execute Analysis	✅	Run scans
Administer	❌	Not needed

Best Practices

1. Use project tokens - More secure than user tokens
2. Store tokens safely - Never commit to git
3. Verify before linking - Check project key is correct
4. One link per project - Don't share configs

Common Issues

"Project not found"

Cause: Wrong project key or no access.

Solution:

1. Verify key in SonarQube UI
2. Check token permissions
3. Ensure project exists

"Connection refused"

Cause: SonarQube not running or wrong URL.

Solution:

1. Check SonarQube is running
2. Verify URL is correct
3. Check network/firewall

"Token invalid"

Cause: Expired or revoked token.

Solution:

1. Generate new token in SonarQube
2. Ensure token type is correct

Related Tools

• sonar_auto_setup - Create new project
• sonar_config_manager - View/manage config
• sonar_diagnose_permissions - Check permissions