[heurtematte]

Description

Code scanning default setup analyzes the CodeQL languages that GitHub detects in a repository, and GitHub adds the languages it detects later on (see About setup types for code scanning). otterdog compared code_scanning_default_languages exactly with the live settings, so every repository with default setup drifts from its configuration as soon as it contains code:

• a new repository can only enable default setup without languages, as validate rejects languages for a repository that does not exist yet or a language that is not detected
• once code is pushed, GitHub adds the detected languages, and check-sync reports them on every pull request of the organization until someone adds them to the configuration by hand

For example, check-sync of eclipse-xfsc/.eclipsefdn#50 reports 10 changes, 7 of them only languages added by GitHub, which hide the actual drift (gh_pages_build_type, branch_policies of an environment):

!   repository[name="facis-zero-trust-demonstrator"] {
!     code_scanning_default_languages = [
-      "actions"
-      "go"
-      "javascript"
-      "python"
-      "typescript"
!     ]
!   }

With this PR, the configured languages are the minimum set of languages to analyze:

• Empty list: without configured languages, the languages are left to GitHub. They are not compared with the live settings, and an empty list is no longer sent to GitHub, only state and query_suite.
• Missing language: a difference is only reported for a configured language that is not analyzed. javascript and typescript count as one, as CodeQL analyzes them together. The change adds the missing language to the analyzed ones instead of replacing them:

  !     code_scanning_default_languages = [
  +      "java-kotlin"
  !     ]

• Updating the languages: the languages analyzed by the current default setup are read first and kept. This is needed because the apply of a merged pull request compares the configuration with the previous configuration, not with the live settings: without it, adding java-kotlin would remove the python that GitHub added.

The user guide gets a new section "Languages analyzed by GitHub". It now recommends leaving the languages to GitHub and only configuring a language that GitHub does not analyze on its own, e.g. a compiled language.

Related issue

Relates to eclipse-xfsc/.eclipsefdn#50 (comment)

Type of change

• 🐛 Bug fix (non-breaking change fixing an issue)

Tests

• Unit tests added / updated under tests/

Manual testing

• GitHub API calls only stubbed / mocked in unit tests (no live testing)

Checklist

• Documentation updated (docs/, reference docs for new/changed settings, make docs builds)
• Default template / examples updated if the config schema changed: not needed, the schema and the default code_scanning_default_languages: [] are unchanged, only their meaning changes

Notes for reviewers

• Behavior change: a language that GitHub analyzes can no longer be removed with otterdog, as languages analyzed in addition to the configured ones are kept. This is the intent of the "minimum" semantics, but it changes the previous behavior.
• otterdog import: unchanged, it still writes the languages of the live settings. That is harmless now, as they act as a minimum.

[github-actions]

📖 The preview of the documentation was removed (pull request closed).

[Copilot]

🟡 Changes recommended

The language-preservation update can remove GitHub-added languages after a failed settings read and reintroduce removed requirements by including previous-configuration values.

2 open issues

• Exclude previous configuration from preserved languages · New
• Abort updates when current settings cannot be read · New

What changed in this PR

This PR reduces false code-scanning drift reports by treating configured languages as a minimum, while preserving languages GitHub already analyzes.

Changes:

• Ignore additional analyzed languages during comparison and omit empty language lists from provider payloads.
• Read current default-setup languages before adding configured languages.
• Add regression tests and update documentation to explain the minimum-language behavior.

File	Description
tests/​providers/​github/​rest/​test_repo_client.py	Tests language preservation and normalization during updates.
tests/​providers/​github/​integration/​test_repositories.py	Adds provider-level language-preservation coverage.
tests/​models/​test_repository.py	Tests minimum-language comparisons and provider payloads.
otterdog/​webapp/​home/​playground-reference.json	Explains minimum-language semantics in the playground reference.
otterdog/​providers/​github/​rest/​repo_client.py	Reads and merges currently analyzed languages before updates.
otterdog/​models/​repository.py	Implements minimum-language differences and omits empty language payloads.
docs/​userguide/​guides/​repository-security.md	Explains GitHub-managed languages and updates configuration guidance.
docs/​reference/​organization/​repository/​index.md	Documents the revised language-setting behavior.

_{Review effort: Balanced}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

🔵 Needs a closer look

Enabling default setup while shrinking a previously ignored language list can omit the requested language from the PATCH because disabled configurations are incorrectly treated as already analyzing those languages.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Enabling setup can drop newly selected languages

otterdog/​models/​repository.py:971

When local apply enables default setup while shrinking a previously ignored language list (for example, disabled with ['actions', 'java-kotlin'] → enabled with ['java-kotlin']), this treats the disabled configuration's languages as already analyzed and drops the language change. The resulting PATCH contains only state: configured, so the explicitly requested language is not selected if GitHub's automatic setup does not include it. Treat the previous languages as empty when the previous setup is disabled, and cover this transition in the enabling test.

2 resolved since last review

• Abort updates when current settings cannot be read
• Exclude previous configuration from preserved languages

_{Review effort: Balanced}

[heurtematte]

@netomi I would like your opinion on this PR.

[netomi]

LGTM to apply that logic, I regret supporting that feature due to fact that the live settings are not stable as GitHub adds new languages when it detects them which just is a constant headache.

Also you cant set default languages as long as GitHub has not detected them in the repo, so that also fails often when creating a repo with some default languages from the start. That should probably be disabled alltogether.