feat: remove custom gitlab-ci language contribution and defer to Red Hat YAML extension

[X-Guardian]

Problem statement

The extension currently registers a custom gitlab-ci language for .gitlab-ci.yml and .gitlab-ci.yaml files (see contributes.languages and contributes.grammars in package.json). This claims the language ID away from VS Code's built-in yaml, which has two consequences:

1. Red Hat's YAML extension stops working on GitLab CI files. Once the document's language ID is gitlab-ci rather than yaml, Red Hat's schema validation, formatting, folding, and GitLab CI schema integration no longer fire. Users lose the richest YAML experience on exactly the files where they need it most.
2. The custom grammar adds limited value over the built-in YAML grammar. It recolours roughly 13 well-known top-level keys (image:, stages:, include:, etc.) to slightly different TextMate scopes. It also defines a gitlab-ci-components rule keyed off a job-name suffix convention that doesn't match how GitLab actually identifies components in CI files, and two further rules (job-definition, job-keywords) that are declared in the grammar's repository but aren't referenced from the top-level patterns block, so they don't run. There's also no embedded shell highlighting inside script: blocks, no !reference handling, and no $CI_* variable highlighting — the kinds of things that would be a meaningful upgrade over plain YAML.

The net effect is that the extension takes a significant feature (full YAML tooling) away from users in exchange for relatively minor cosmetic differences.

Proposed solution

Remove the contributes.languages and contributes.grammars entries from package.json and delete the now-unused syntaxes/gitlab-ci.tmLanguage.json and language-configuration.json files. .gitlab-ci.yml files will then keep their natural yaml language ID and be handled by Red Hat's YAML extension (or the built-in YAML grammar if Red Hat isn't installed).

The extension's own providers (hover, completion, validation, code actions) already register against language: 'yaml' and filter by filename — they will keep working unchanged. The dead { language: 'gitlab-ci' } selectors and the document.languageId === 'gitlab-ci' defensive branches can be removed at the same time.

Optionally, add "extensionPack": ["redhat.vscode-yaml"] to nudge users to install the Red Hat YAML extension alongside this one.

Example .gitlab-ci.yml usage

N/A

Command/UI impact

New command: none.
Setting changes: none.
Browser/hover/completion changes: hover, completion, validation, and code action providers register against language: 'yaml' only; the redundant { language: 'gitlab-ci' } selectors are removed. User-visible behaviour for these providers is unchanged because the filename-based filter is the load-bearing check.

Acceptance criteria

• Opening a .gitlab-ci.yml file shows language ID yaml in the status bar.
• Red Hat YAML extension's schema validation activates on .gitlab-ci.yml files.
• Hover over an include: - component: line still shows the component card.
• Completion still suggests components after component: and versions after @.
• Invalid component inputs still produce diagnostics.
• npm run check-types passes; npm test passes.

Priority

Important

Alternatives considered

• Add a setting to disable the language contribution at runtime. Not viable: VS Code reads contributes.languages and contributes.grammars from package.json at extension-load time only; there is no API to unregister a language contribution from activate(). A setting could only mutate the user's files.associations, which is surprising behaviour and still requires a reload.
• Switch to an injection grammar (injectTo: ["source.yaml"]). Architecturally the most correct alternative — layers GitLab-specific scopes on top of the host YAML grammar without claiming the language ID. Rejected because the current grammar's actual contribution is minimal and largely redundant; the cost/benefit doesn't justify the work over simply removing it.
• Document the user workaround (files.associations override). Useful as a transitional note but doesn't fix the default experience for users who never read the README.

Target GitLab instance(s)

both

Pre-submit checks

• I searched existing feature requests and did not find a duplicate.
• I included concrete examples and acceptance criteria.

[X-Guardian]

I'm happy to raise a PR for this if you agree.

[eFAILution]

Discovery notes — this is a product/UX tradeoff, not a mechanical cleanup

Investigated against beta. Recommendation up front: make a direction decision + a short spike before writing any code. The issue frames removal as low-cost, but the current state complicates that. Capturing the findings so the call is informed.

The actual tradeoff

• Gain: .gitlab-ci.yml reverts to language ID yaml, so Red Hat's YAML extension (schema validation, formatting, folding, GitLab CI schema) works again on exactly the files where it's most useful.
• Lose: the custom TextMate grammar's highlighting. That matters more than the issue implies — see below.

What the code shows

1. The grammar was just invested in. 8dab15a fix(syntax): correct grammar filename to restore syntax highlighting (#116) landed recently — i.e. the custom highlighting is actively maintained and was deliberately fixed, which cuts against the "adds little value, just remove it" premise. Removing it now would undo that work; worth confirming that's intended.
2. Providers register on three selectors, not one. src/extension.ts registers hover/completion/validation against { language: 'yaml' }, { language: 'gitlab-ci' }, and { language: 'shellscript' }. The issue only accounts for yaml + the redundant gitlab-ci.
   • The gitlab-ci selectors are indeed safe to drop once the language contribution is gone.
   • ⚠️ The shellscript selector is intentional and must stay — it's there because CI files are sometimes viewed/associated under the shellscript language, not because of script: blocks (that rationale is a myth). A "clean up the non-yaml selectors" pass must not remove it.
3. Activation: confirm activation still fires once onLanguage:gitlab-ci (if present) is gone — activationEvents already includes workspaceContains:**/.gitlab-ci.{yml,yaml}, which should cover it, but verify.

Open questions for the maintainer

1. Accept losing the custom highlighting entirely, or is the injection grammar (injectTo: ["source.yaml"]) alternative — keep GitLab scopes layered on top of YAML without claiming the language ID — worth the extra work? (The issue rejects it on cost/benefit; fix: correct grammar filename to restore syntax highlighting for GitLab CI files #116 suggests the highlighting is valued, so this deserves a second look.)
2. extensionPack: ["redhat.vscode-yaml"] (auto-installs Red Hat YAML) vs a softer README nudge vs nothing — adding a pack dependency is a user-facing choice.
3. README updates: any sections documenting the custom language/highlighting need revising.

If we proceed (removal path) — scope + verification

• Remove contributes.languages + contributes.grammars from package.json; delete syntaxes/gitlab-ci.tmLanguage.json + language-configuration.json.
• Drop the { language: 'gitlab-ci' } selectors and any document.languageId === 'gitlab-ci' branches — keep yaml and shellscript.
• Verify the acceptance criteria from the issue, especially: language ID shows yaml, Red Hat schema activates, and hover/completion/validation still fire (the filename filter is load-bearing) — including on a file a user has manually associated as shellscript.

Net: low code effort, but a real product decision (highlighting-vs-tooling, plus the injection-grammar option) and a couple of load-bearing nuances (shellscript selector, recent #116 work). Holding for a decision before implementation.

[eFAILution]

Implemented in #210 (feat: remove custom gitlab-ci language contribution), which removes the custom gitlab-ci language + TextMate grammar, deletes syntaxes/gitlab-ci.tmLanguage.json and language-configuration.json, drops the contributes.languages/contributes.grammars blocks, and adds extensionPack: [redhat.vscode-yaml]. .gitlab-ci.yml files now keep the native YAML language mode so Red Hat's YAML extension activates. #210 is merged to beta and ships to main via the beta→main integration (#208). Closing as done.