createRepository vs createExternalRepository


I would like to understand what the difference between createRepository and createExternalRepository is?

Looking in the API description I found The repository key will be "external_[engineId]". But is that the only difference?

In the documentation I found something about Issue Backdating also speaking about “external”. Is this different for rules created with the one or the other?

Thanks for your answer.


Hi @guwirth

External repositories/rules/issues is a concept that is used to import issues produced by third party tools. See:

External issues are displayed in SonarQube/SonarCloud with a little badge to differentiate them from “native” issues. They count in the quality gate, but we assume the management of the rule configuration/issue exclusion will also be handled in the third-party tool. So it is not possible to enable/disable the external rules in a quality profile, nor mark an issue as false positive.

Since rule execution/configuration is out of our control, we decided to always backdate such issues, since there is no accurate way for us to know why the issue is new.

@Julien_HENRY Many thanks for the quick response. To be honest, now I’m even more confused?

  1. "Internal issues" are for me issues detected by a SonarQube internal code analyzer. A precondition is to have a repository with rules. I create this repository with new createRepository() and add NewIssue with createIssue()/save().

  2. On the other hand there are “generic issues” where I don’t need a repository with rules. I create a NewExternalIssue with newExternalIssue()/save(). Rule definition and issue detection is all outside of SQ.

  3. Then we have this “external issues” (not generic issues) where I have to create a repository with createExternalRepository() and add NewIssues with createIssue()/save()?

My question is how this 3rd option is different compared to 1?

There are only 2 types of issues:

  • “normal” issues (what you call “internal”). Those are the issues entirely managed by SQ.
  • “external” issues. Issues reported by third party tools, not controlled by the SQ scanner.

External issues can be created programmatically using Sensor API newExternalIssue(). Some SonarSource analyzers also provide out of the box support of some well known issue report format for each languages. If you issue report format is not supported, and you don’t want to write a custom Java plugin, you can also convert your issue report to the Generic XML format.

External issues don’t require a rule definition. If you try to report a new external issue with a rule key that is not known by SonarQube, it will create a new empty rule definition on the fly. You can also provide rule definition during the analysis (we call that addhoc rules). Finally, you may still want to pre-register rules definitions, in order to enforce consistency/reserve the engine id/rule id.

So your options 2 and 3 are basically the same concept (external issues) but with the optional possibility to pre-register rules definition.

External issues summary:

  1. External issue created without (external) rule definition (an empty one will be created automatically) using newExternalIssue()
  2. External rule + External issue created during analysis (=adhoc rule). Using newAdHocRule() + newExternalIssue()
  3. External rule defined in advance in the SQ server using createExternalRepository() then external issues created during the analysis

Does that clarify?

1 Like

@Julien_HENRY many thanks for your detailed answer! That makes it much clearer.

I understand most of the use cases except newAdHocRule(). Why should I create a rule if newExternalIssue() is already doing this? What’s the use case behind this?

newExternalIssue() doesn’t allow to provide rules metadata (like description, tags, …). This is not mandatory, but if you have a way to know those details when processing the third party tool issue report, you can use newAdHocRule to provide them.

1 Like

@Julien_HENRY thanks a lot. Now everything is clear.