If you're managing your technical debt using SonarQube's issue workflow, then you probably want to manage all your technical debt with that workflow. But even after you've enabled the rules that flag duplicated blocks, insufficient branch coverage by unit tests, insufficient comment density, and insufficient line coverage by unit tests (these rules in the "Common Sonar" repository are available to all languages) there will still be problems in your code that SonarQube can't catch.

For instance you might come across a laborious re-implementation of some function that's already offered by a library you're using. Even though there may be nothing technically wrong with the code (except ignorance or sheer bone-headedness) you want to flag it for remediation. That's where manual issues come in to play.

You can create all the manual rules you want, and they can be about anything you choose. In this case, the rule might be "use library function." Or, if that's too narrow and specific, you might create a simple "refactor" rule. When you create individual issues against the rule, you'll have the opportunity to fill in the details of the specific instance. "Use library function X", in this case.

Creating a Manual Issue

To create a manual issue, you must be logged in and have the Browse permission on the project:

Manual issues are logged against manual rules. (Note that manual rules have to be previously defined by a System administrator.) Choose the rule to use from the rule dropdown and enter the issue message in the text area: (Once created, you cannot edit the rule or description of a manual issue.)

The issue is then displayed within the source code and can be reviewed as any other issues:

Note that just as you manually created the issue, you will need to manually resolve it. Since SonarQube did not detect it originally, it cannot detect when it has been corrected.


Creating Manual Rules

A user with the "Administer Quality Profiles and Gates" permission can create new manual rules and administer existing ones in the Rules page:

As for any other rule, it description can be written using the Markdown syntax.

The description you enter is used as the rule detail:

Manual Rules can be found in the Rules page by selecting the "Manual Rules" repository.