Repository navigation
feat(linting): check CI job scripts with ShellCheck - #396
Open
X-Guardian wants to merge 1 commit into
Open
X-Guardian wants to merge 1 commit into
X-Guardian wants to merge 1 commit into
Conversation
X-Guardian
force-pushed
the
feat/shellcheck-script-linting
branch
from
November 16, 2026 13:52
1815a2b to
09827e8
Compare
X-Guardian
marked this pull request as ready for review
November 16, 2026 13:54
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
before_script,scriptandafter_scriptblocks are now linted with the user's own ShellCheck binary, and findings appear in the Problems panel with a link to each rule's wiki page.Change Type
Context
User-facing impact
|, folded>, plain (including multi-line), and single- or double-quoted with escapes.script,include: inputs: script:and keys nested inside a job (such astrigger:) are left alone.variables:(global, job, and same-fileextendstemplates),rules: variables:andparallel: matrix:are no longer reported as SC2154. Variables set in project or group settings can be listed inshellcheck.knownVariables(names or globs).before_script(its own, else a same-fileextendstemplate's, elsedefault:'s unlessinherit:defaultexcludes it, else the legacy global) is linted in one shell with itsscript. So variables set inbefore_scriptcount as assigned. Findings in an inheritedbefore_scriptare reported once, where it is defined. A lonebefore_scriptdoesn't report SC2034 ("appears unused"), because jobs use those variables.after_scriptis linted on its own.$[[ inputs.x ]]) is masked with a word of the same length, so it isn't read as$[arithmetic and columns stay aligned. A masked input is a fixed string to ShellCheck, soif [ "$[[ inputs.mode ]]" == "fast" ]would be reported as a constant expression. GitLab fills inputs in per pipeline, so those comparisons are deliberate. Constant-expression findings (SC2050, SC2078, SC2157, SC2194) are dropped on lines that contain an interpolation. Other findings on those lines are kept.shellcheck.exclude. Inside a literal|block it also offers Disable SC#### for this command:# shellcheck disable=SC####above the line where the command starts, moving up past\continuation lines.>block it would be folded into the command and comment it out.Settings
gitlabComponentHelper.shellcheck.enabled(defaulttrue),.path,.shell(defaultbash),.severity(minimum level, defaultwarning),.exclude,.knownVariables.pathis"scope": "machine", so a cloned workspace's settings can't point it at an arbitrary binary.Notes for reviewers
yaml(eemeli) v2, bundled by esbuild like everything else.js-yamlhas no source ranges, and those are what make exact positions possible. Existingjs-yamlcode is unchanged. The production bundle is 455 KB.{ merge: true }). Without them the library treats<<as an ordinary key, so a job with two<<: *anchorentries is a duplicate-key error. Documents with errors are skipped, so the whole file would go unlinted. GitLab's own Auto DevOpsDeploytemplate is written this way.alignScalarwalks the parsed value and its source text together, skipping what the parser consumed (indentation, folded line breaks, quotes, escape markers). That gives an offset per character for every style, instead of a per-line guess.--format=json1, which counts a tab as one column, so columns match string indices. It runs asynchronously throughexecFilewith a 10 s timeout and at most 4 runs at a time. Results for an outdated document version are dropped.gitlab-component-helper-shellcheck,source: 'shellcheck'. Onlyfile-schemeyamldocuments that match the CI globs are linted, so diff views and plain.shfiles are skipped.GitLab scope
Affected areas
What changed by bucket
src/utils/ciYamlNodes.tsextendschain resolution with cycle guard,inherit:defaultcheck.src/utils/shellScriptExtractor.ts|blocks. Skips!referenceand aliases, and skips documents with parse errors.src/utils/scriptVariables.tsknownVariables. (gitlabVariables.tsalready holds the predefined-variable list, hence the separate module.)src/utils/shellcheckOutput.tsjson1parsing with type guards, GitLab false-positive filtering, mapping findings to source offsets (plus where a disable line can go), and working out the disable-line edit.src/providers/shellCheckProvider.ts,src/extension.tspackage.json,README.mdyamldependency, a Script Linting section, and the acknowledgement.tests/unit/shellScriptExtractor.test.ts,tests/unit/scriptVariables.test.ts,tests/unit/shellcheckOutput.test.ts,tests/extension-host/suite/shellcheck.test.ts,tests/fixtures/shellcheck/.gitlab-ci.yml,tests/fixtures/shellcheck-quickfix/.gitlab-ci.ymlValidation
Local checks
npm ci(clean install)npm run check-typesnpm test(425 passing)npm run lint(clean,--max-warnings 0)npm run test:extension-host, with ShellCheck 0.10.0 installedTests
Extractor:
variables.script, nested keys, hidden and interpolated jobs,default:, legacy globals.!referenceand alias skipping.before_scriptsharing acrossdefault:,extendsandinherit:default: false.Variables: global, own,
extends, rules and matrix variables; extends cycles; glob matching.Output:
|blocks, moved up past\continuations;Extension host: opens a fixture and checks that SC2086 lands exactly on
$unquoted_value, that SC2154 is reported for the undefined variable, and that nothing is reported for thevariables:one. A second test opens a fixture with a$[[ ]]comparison and checks:|block offers "Disable … for this command", and applying it clears that finding.Both tests skip when
shellcheckisn't on PATH (GitHub's Ubuntu runners have it).Breaking Changes
Linting is on by default but needs a ShellCheck binary. Users without one see a single dismissible message.