SonarSource/sonarqube · warning

Cannot mint a GitHub installation token: unknown project

Error message

Cannot mint a GitHub installation token: unknown project '{}'

What it means

GithubInstallationTokenProviderImpl.mint logs this warning and returns Optional.empty() when selectProjectByKey cannot find a project for the supplied project key. Without a project, no GitHub App installation token can be minted. The Javadoc-described design returns empty at the first missing step rather than throwing, so callers see an empty Optional from mint().

Solutions

  1. Look up the correct project key via GET api/projects/search and fix it in the calling configuration.
  2. Recreate the deleted project or re-import it from GitHub.
  3. Point the caller at the correct SonarQube server/organization.
  4. Pre-validate the key before minting so automation fails fast with a clear message.

Example fix

// before
POST api/alm_integrations/install_github_app?projectKey=legacy-key -> empty
// after
# confirm key
KEY=$(curl -s -u token: "$SQ_URL/api/projects/search?q=service-api" | jq -r '.components[0].key')
POST api/alm_integrations/install_github_app?projectKey=$KEY
Defensive patterns

Strategy: validation

Validate before calling

# Verify the project exists before requesting a GitHub installation token
KEY=$(curl -s -u "$TOKEN:" "$SQ_URL/api/projects/search?q=$RAW_KEY" | jq -r '.components[0].key // empty')
[ -n "$KEY" ] || { echo "unknown project" >&2; exit 1; }

Prevention

When it happens

Trigger: Requesting a GitHub installation token (api/alm_integrations/install_github_app path or internal mint call) with a projectKey that does not exist in the projects table.

Common situations: Stale project key in CI after the project was renamed/deleted; calling the wrong SonarQube instance; copy-paste of a key from a different organization or branch of environments (staging key used on production).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/efdb5041b18a7418. Report an issue: GitHub.

Appendix: source

Thrown at server/sonar-webserver-common/src/main/java/org/sonar/server/common/almsettings/github/GithubInstallationTokenProviderImpl.java:79

  private final GithubGlobalSettingsValidator githubGlobalSettingsValidator;
  private final GithubApplicationClient githubApplicationClient;

  public GithubInstallationTokenProviderImpl(DbClient dbClient, GithubGlobalSettingsValidator githubGlobalSettingsValidator,
    GithubApplicationClientImpl githubApplicationClient) {
    this.dbClient = dbClient;
    this.githubGlobalSettingsValidator = githubGlobalSettingsValidator;
    this.githubApplicationClient = githubApplicationClient;
  }

  @Override
  public Optional<GithubInstallationToken> mint(String projectKey) {
    String safeProjectKey = sanitizeForLog(projectKey);
    AlmSettingDto resolvedAlmSetting;
    String resolvedAlmRepo;
    try (DbSession dbSession = dbClient.openSession(false)) {
      Optional<ProjectDto> project = dbClient.projectDao().selectProjectByKey(dbSession, projectKey);
      if (project.isEmpty()) {
        LOG.warn("Cannot mint a GitHub installation token: unknown project '{}'", safeProjectKey);
        return Optional.empty();
      }

      Optional<ProjectAlmSettingDto> projectAlmSetting = dbClient.projectAlmSettingDao().selectByProject(dbSession, project.get());
      if (projectAlmSetting.isEmpty()) {
        LOG.warn("Cannot mint a GitHub installation token: project '{}' is not bound to any DevOps Platform", safeProjectKey);
        return Optional.empty();
      }

      Optional<AlmSettingDto> almSetting = dbClient.almSettingDao().selectByUuid(dbSession, projectAlmSetting.get().getAlmSettingUuid());
      if (almSetting.isEmpty() || almSetting.get().getAlm() != ALM.GITHUB) {
        LOG.warn("Cannot mint a GitHub installation token: project '{}' is not bound to a GitHub App", safeProjectKey);
        return Optional.empty();
      }

      String almRepo = projectAlmSetting.get().getAlmRepo();
      if (almRepo == null || almRepo.isBlank()) {
        LOG.warn("Cannot mint a GitHub installation token: project '{}' has no repository configured on its DevOps Platform binding", safeProjectKey);

View on GitHub (pinned to 184c821202)