GitLab Component Helper
Autocomplete, inline docs, and a component browser for GitLab CI/CD, right in VS Code.
Works with gitlab.com and self-hosted GitLab, public or private.
Quick start ·
Features ·
Configuration ·
Commands ·
Settings ·
Troubleshooting

GitLab CI/CD components make pipelines reusable, but writing them means jumping between your editor, the catalog, and each component's docs to find the right path, version, and inputs. This extension brings all of that into the file you're editing.
Quick start

- Install GitLab Component Helper from the Extensions view, or run
code --install-extension eFAILution.gitlab-component-helper.
- Open a
.gitlab-ci.yml and type component:. Suggestions come with versions already filled in.
- Hover any component URL to read its docs and inputs.
- Run GitLab CI: Browse Components from the Command Palette to explore everything your sources offer.
Want your own components in the list? Run GitLab CI: Add Component Project/Group and point it at a project or group. A token is only needed for private ones.
Using Copilot Chat? Turn on gitlabComponentHelper.mcp.enabled and let the agent fix your components.
Features
Browse and insert
The Component Browser lists every component from your configured projects and groups, on any GitLab instance. Pick one, choose a version, and insert it, with its inputs stubbed out if you want them. A Raw YAML toggle shows the original template.
Complete as you type
Context-aware completion for component paths, versions, and input names. GitLab CI/CD variables such as $CI_SERVER_FQDN and $CI_PROJECT_PATH are resolved in component URLs.

Docs on hover
Hover a component to see its description, inputs, defaults, and version status. If a component has no description of its own, the opening paragraph of its README.md stands in.

Inputs are checked as you type. Unknown names and missing required inputs get flagged, with Quick Fixes to add what's missing.
include:
- component: gitlab.com/components/terraform@v1.0.0
inputs:
terraform_version: "1.5.0"
workspace: "default"

Local includes too
include: - local: entries get the same hover, completion, and validation, as long as the target file declares a spec.inputs block.
include:
- local: "gitlab/templates/nx-test.yml"
inputs:
job_name: test-nightly
job_type: nightly
Stay on the latest version
When a component is pinned to a semantic version (X.Y.Z, optionally v-prefixed), the extension checks for a newer stable release:
- Hover shows
✓ up to date or ⚠️ update available next to your version.
- An outdated pin gets a warning squiggle with an Update to
X.Y.Z Quick Fix (Ctrl+. / Cmd+.).
- GitLab CI: Update All Component Versions to Latest bumps every outdated pin in the file at once.

Floating refs (main, latest, ~latest), partial pins (1, 1.2), and commit SHAs are left alone, and pre-releases are never suggested. The check runs when a CI file is opened or saved and reuses the version cache.
Choosing a default version per component
Completion and the Component Browser offer the same default for each component: the highest semantic version, falling back to main or master when the project has no releases.
To change that, open the Component Browser, load a component's versions, and right-click the version dropdown:
- Set as Default Version pins the version you picked.
- Always Use Latest always offers the highest stable version.
Choosing one replaces the other. The choice is saved in gitlabComponentHelper.versionPreferences in your user settings, keyed by <instance>/<project path>/<component>, with ~latest meaning Always Use Latest. You can edit or clear it there. A workspace entry for the same component wins over your user setting.
Private components
Add a private project or group with GitLab CI: Add Component Project/Group. You enter a token once per GitLab instance, and it's reused for everything on that instance.
- Tokens live in VS Code SecretStorage: encrypted, never in plain text or settings files.
- They're only sent to the instance you added them for.
- Use the
read_api scope, on a user with at least Reporter access to the project.
Heads up: the old gitlabComponentHelper.gitlabToken setting stores tokens in plain text and is deprecated. Re-add the source with the command above, then clear that field.
Fast on big catalogs
Component data is cached (one hour by default) and API calls are batched, so large groups stay responsive.
Let Copilot fix your components (beta)
The extension includes an MCP server, so AI agents can check your components the same way the editor does. In Copilot Chat agent mode, the agent can find unknown or missing inputs and outdated versions, look up the exact inputs a component version takes, and apply the fixes. Your editor's normal approval flow still applies.
It's off by default. To try it:
- In your user settings, turn on
gitlabComponentHelper.mcp.enabled.
- Open Copilot Chat, switch to Agent, and check that GitLab Component Helper is enabled in the tools picker. VS Code may ask you to trust the server the first time.
- Ask something like:
- "Find and fix the GitLab CI component problems in this repo."
- "What inputs does
gitlab.com/components/opentofu/full-pipeline@4.9.0 take, and which am I missing?"
- "Are any of my components out of date?"
| Tool |
What the agent gets |
validate_ci_file |
Unknown and missing inputs, outdated versions, and broken local includes, with suggested edits |
check_component_versions |
Outdated components and the version to move to |
get_component_spec |
A component's inputs at a version: type, required, default, allowed values, description |
list_component_versions |
Available versions and the latest stable one |
list_component_usages |
Every component and local include in a file or the workspace |
The server only reads. It never edits files itself: it suggests edits and the agent applies them. It also keeps your tokens safe:
- Your tokens go to the server through a one-time private file that's deleted right away. They're never in tool results or logs.
- Tokens are only sent to GitLab instances from your user settings or saved tokens. A cloned repo can't add hosts.
- Files are only read inside your open workspace folders.
It also works with other MCP clients, like Claude Code, by running the bundled server with Node. See the MCP server guide.
Configuration
Most people only need component sources. Add them with the command above, or in settings.json:
"gitlabComponentHelper.componentSources": [
{ "name": "OpenTofu Components", "path": "components/opentofu", "gitlabInstance": "gitlab.com" },
{ "name": "Internal CI Components", "path": "devops/ci-components", "gitlabInstance": "gitlab.company.com" }
]
CI files are recognised at .gitlab-ci.yml, .gitlab-ci.yaml, and anywhere under .gitlab/. Keep pipelines somewhere else? Add globs. They're merged with the defaults and match at any depth:
"gitlabComponentHelper.additionalFileGlobs": ["**/ci/*.yml", "**/pipelines/**/*.yaml"]
Advanced setups
Template header comments (for component authors)
Add header comments to the top of a template to show consistent context in the Component Browser. Supported keys are summary, usage, and note.
# @gitlab-component-helper: summary: Push a Helm chart to Sonic
# @gitlab-component-helper: usage: include + set SONIC_TARGET_* variables
# @gitlab-component-helper: note: Requires a protected ref for publish
- The short prefix
# @gch: works too.
- Headers must come before any non-comment content.
- Multiple
note lines are allowed.
- The section stays hidden when no header is present.
When a component or project has no description, the browser and hover use the opening paragraph of its README.md, checked next to the template first and then at the repository root.
Commands
Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type GitLab CI.
| Command |
What it does |
| Browse Components |
Explore and insert components from your sources |
| Add Component Project/Group |
Add a project or group, with an optional token for private access |
| Update All Component Versions to Latest |
Bump every outdated semver pin in the active file |
| Refresh Components Cache |
Refresh cached component data |
| Update Cache |
Force a full re-fetch |
| Reset Cache |
Clear all cached data |
| Show Cache Status |
Show cache info and stats |
For debugging there's also Debug Cache (Detailed), Show Performance Statistics, and Test Providers.
Settings reference
Every setting is also editable from the Settings UI under GitLab Component Helper.
All settings
| Setting |
Type |
Default |
Description |
gitlabComponentHelper.componentSources |
array |
see Configuration |
GitLab repositories with reusable components. Each item takes name, path, gitlabInstance, and optionally a discovery block or a tagPattern (see the advanced guides). |
gitlabComponentHelper.additionalFileGlobs |
array |
[] |
Extra GitLab CI file globs, merged with the built-in defaults. Patterns match at any depth (e.g. ci/*.yml → **/ci/*.yml). |
gitlabComponentHelper.versionCheck.enabled |
boolean |
true |
Warn when a component pinned to a semantic version has a newer stable release. Checked on open/save. |
gitlabComponentHelper.versionCheck.severity |
string |
warning |
Severity of the "newer version available" diagnostic. One of warning, information. |
gitlabComponentHelper.mcp.enabled |
boolean |
false |
Offer the bundled MCP server to Copilot Chat and other in-editor AI clients. When one starts it, it gets your workspace folders and the tokens for your user-level instances. Application scope only. |
gitlabComponentHelper.versionPreferences |
object |
{} |
Version offered per component, keyed by <instance>/<project path>/<component>: a version, or ~latest for the highest stable version. Set via Set as Default Version or Always Use Latest in the Component Browser. |
gitlabComponentHelper.cacheTime |
number |
3600 |
Component cache lifetime, in seconds. |
gitlabComponentHelper.logLevel |
string |
ERROR |
Logging level. One of DEBUG, INFO, WARN, ERROR. |
gitlabComponentHelper.autoShowOutput |
boolean |
false |
Show the output channel automatically when the log level changes. |
gitlabComponentHelper.httpTimeout |
number |
10000 |
HTTP request timeout, in milliseconds. |
gitlabComponentHelper.retryAttempts |
number |
3 |
Retry attempts for failed HTTP requests. |
gitlabComponentHelper.batchSize |
number |
5 |
Components processed in parallel per batch. |
gitlabComponentHelper.discovery.templateRoots |
array |
["templates"] |
Directories scanned for components (up to 5). See discovery tuning. |
gitlabComponentHelper.discovery.maxDepth |
number |
1 |
Subdirectory depth to recurse under each root. Range 0–3. |
gitlabComponentHelper.discovery.filePatterns |
array |
["*.yml", "*.yaml"] |
Filename globs for template files (filename only, no path globs). |
gitlabComponentHelper.discovery.templateFileNames |
array |
["template.yml", "template.yaml"] |
Filenames recognised inside per-component subfolders. |
gitlabComponentHelper.gitlabToken |
string |
"" |
Deprecated. Stores tokens in plain text. Use GitLab CI: Add Component Project/Group instead. |
Troubleshooting
No components showing up
Check that the file's language mode is YAML and that at least one component source is configured.
HTTP 401 or "token expired"
The token is expired or invalid. Re-add it with GitLab CI: Add Component Project/Group, or use the Update Token action in the error view. Make sure it has the read_api scope and at least Reporter access.
Version dropdown won't load
Check that you can reach the GitLab instance, verify the token and its permissions, then run GitLab CI: Refresh Components Cache.
Copilot doesn't see GitLab Component Helper
- Turn on
gitlabComponentHelper.mcp.enabled in your user settings. Workspace settings can't turn it on.
- Open a folder. The server isn't offered when no folder is open.
- Use Agent mode, and enable the server in the tools picker.
- Run MCP: List Servers to start, restart, or see the server's output.
- After you add or change a token, restart the server from MCP: List Servers if it doesn't pick the change up.
- "Host isn't allowed": add that instance to
gitlabComponentHelper.componentSources in your user settings.
Still stuck?
Set gitlabComponentHelper.logLevel to DEBUG, reproduce the problem, and open an issue with the output and your configuration (leave out any tokens).
Contributing
Issues and pull requests are welcome.
git clone https://github.com/eFAILution/gitlab-component-helper.git
cd gitlab-component-helper
npm install
npm run compile
Press F5 to launch an Extension Development Host with the extension loaded. You'll need VS Code 1.120.0+ and Node.js 22+.
- Start from an issue, one PR per issue. Branch from
beta as <type>/<issue>-<short-description> (for example fix/412-hover-crash), open the PR against beta, and put Closes #<issue> on its first line. The full rules are in AGENTS.md.
- Use conventional commits (
feat:, fix:, docs:, chore:, …).
npm test runs the unit suite. npm run test:extension-host runs the tests inside real VS Code.
- Releases are cut by release-it: on every push to
beta, and on main when a maintainer runs the Release workflow. Publishing to the Marketplace is a manual step for both. See docs/RELEASING.md.
A programmatic API for other extensions is planned but not exposed yet. docs/api.md describes the intended contract.
License
MIT