Skip to content

feat(linting): check CI job scripts with ShellCheck - #396

Open
X-Guardian wants to merge 1 commit into
eFAILution:betafrom
X-Guardian:feat/shellcheck-script-linting
Open

X-Guardian wants to merge 1 commit into
eFAILution:betafrom
X-Guardian:feat/shellcheck-script-linting

Conversation

@X-Guardian

@X-Guardian X-Guardian commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Job before_script, script and after_script blocks 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.
  • The design follows YAML with Script (MIT, credited in the README), rewritten to fix its position mapping, to lint only job-level keys, and to understand GitLab variables.
  • Closes #

Change Type

  • feat
  • fix
  • refactor
  • docs
  • test
  • chore

Context

User-facing impact

  • ShellCheck findings on script blocks. Squiggles land on the exact span in the YAML for every scalar style: literal |, folded >, plain (including multi-line), and single- or double-quoted with escapes.
  • Only job scripts are linted. A component input named script, include: inputs: script: and keys nested inside a job (such as trigger:) are left alone.
  • GitLab variables aren't "referenced but not assigned". ShellCheck already skips all-uppercase names. Lowercase and mixed-case names defined in the file's variables: (global, job, and same-file extends templates), rules: variables: and parallel: matrix: are no longer reported as SC2154. Variables set in project or group settings can be listed in shellcheck.knownVariables (names or globs).
  • Shell boundaries match GitLab. A job's effective before_script (its own, else a same-file extends template's, else default:'s unless inherit:default excludes it, else the legacy global) is linted in one shell with its script. So variables set in before_script count as assigned. Findings in an inherited before_script are reported once, where it is defined. A lone before_script doesn't report SC2034 ("appears unused"), because jobs use those variables. after_script is linted on its own.
  • Component interpolation ($[[ 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, so if [ "$[[ 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.
  • Quick fixes. Each finding offers Ignore SC#### in workspace settings, which adds the code to shellcheck.exclude. Inside a literal | block it also offers Disable SC#### for this command:
    • It inserts # shellcheck disable=SC#### above the line where the command starts, moving up past \ continuation lines.
    • If a disable line is already directly above at the same indent, it adds the code to that line instead.
    • It isn't offered for other scalar styles, where the comment would never reach ShellCheck. In a plain or quoted item the line would be a YAML comment, and in a > block it would be folded into the command and comment it out.
  • No ShellCheck installed: one information message (with "Don't show again"), then linting is skipped until settings change.

Settings

gitlabComponentHelper.shellcheck.enabled (default true), .path, .shell (default bash), .severity (minimum level, default warning), .exclude, .knownVariables. path is "scope": "machine", so a cloned workspace's settings can't point it at an arbitrary binary.

Notes for reviewers

  • New dependency: yaml (eemeli) v2, bundled by esbuild like everything else. js-yaml has no source ranges, and those are what make exact positions possible. Existing js-yaml code is unchanged. The production bundle is 455 KB.
  • Merge keys are enabled ({ merge: true }). Without them the library treats << as an ordinary key, so a job with two <<: *anchor entries is a duplicate-key error. Documents with errors are skipped, so the whole file would go unlinted. GitLab's own Auto DevOps Deploy template is written this way.
  • Character-level alignment. alignScalar walks 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.
  • ShellCheck runs with --format=json1, which counts a tab as one column, so columns match string indices. It runs asynchronously through execFile with a 10 s timeout and at most 4 runs at a time. Results for an outdated document version are dropped.
  • Diagnostics: collection gitlab-component-helper-shellcheck, source: 'shellcheck'. Only file-scheme yaml documents that match the CI globs are linted, so diff views and plain .sh files are skipped.

GitLab scope

  • gitlab.com
  • self-managed GitLab
  • both

Affected areas

  • Component Browser
  • Hover provider
  • Completion provider
  • Validation provider (new ShellCheck provider alongside it)
  • Cache and refresh behavior
  • GitLab API calls/auth/token storage
  • Docs only

What changed by bucket

Bucket Files Approach
YAML helpers src/utils/ciYamlNodes.ts Job lookup (top-level keys minus global keywords), extends chain resolution with cycle guard, inherit:default check.
Extraction src/utils/shellScriptExtractor.ts Builds lint units per shell session, with per-character source offsets, reportable segments, interpolation masking (with the masked ranges recorded) and the ranges that came from literal | blocks. Skips !reference and aliases, and skips documents with parse errors.
Variables src/utils/scriptVariables.ts Known variable names per job, and glob matching for knownVariables. (gitlabVariables.ts already holds the predefined-variable list, hence the separate module.)
ShellCheck I/O src/utils/shellcheckOutput.ts Argument building, json1 parsing 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.
Provider src/providers/shellCheckProvider.ts, src/extension.ts Event wiring, 500 ms debounce, binary lookup, missing-binary message, diagnostics, and the quick-fix provider and exclude command.
Config/docs package.json, README.md Settings, yaml dependency, a Script Linting section, and the acknowledgement.
Tests 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.yml See below.

Validation

Local checks

  • npm ci (clean install)
  • npm run check-types
  • npm test (425 passing)
  • npm run lint (clean, --max-warnings 0)
  • npm run test:extension-host, with ShellCheck 0.10.0 installed
  • Manual verification in VS Code Extension Host

Tests

  • Extractor:

    • The job-level rule: spec input, include inputs, variables.script, nested keys, hidden and interpolated jobs, default:, legacy globals.
    • Sequence joining and flattening; !reference and alias skipping.
    • before_script sharing across default:, extends and inherit:default: false.
    • Source offsets for literal, quoted (with escapes), multi-line plain, folded, inline and CRLF sources.
    • Masking, and recording masked ranges and literal-block ranges.
  • Variables: global, own, extends, rules and matrix variables; extends cycles; glob matching.

  • Output:

    • argument building and exclusion sanitising; malformed JSON;
    • SC2154 and SC2034 filtering, and constant-expression filtering only on lines with an interpolation;
    • mapping, including dropping findings in inherited segments and clipping ranges that run past a segment;
    • disable positions set only in | blocks, moved up past \ continuations;
    • disable edits: insert, append to an existing line, skip a code already disabled.
  • 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 the variables: one. A second test opens a fixture with a $[[ ]] comparison and checks:

    • no SC2050 is reported for the comparison;
    • a finding in a plain item offers only the settings action;
    • a finding in a | block offers "Disable … for this command", and applying it clears that finding.

    Both tests skip when shellcheck isn't on PATH (GitHub's Ubuntu runners have it).

Breaking Changes

  • No breaking changes
  • Breaking changes (describe below)

Linting is on by default but needs a ShellCheck binary. Users without one see a single dismissible message.

@X-Guardian
X-Guardian force-pushed the feat/shellcheck-script-linting branch from 1815a2b to 09827e8 Compare November 16, 2026 13:52
@X-Guardian
X-Guardian marked this pull request as ready for review November 16, 2026 13:54
@X-Guardian
X-Guardian changed the base branch from beta to main November 18, 2026 15:49
@X-Guardian
X-Guardian changed the base branch from main to beta November 18, 2026 15:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant