From ea64e04c05a87a00f890ea6731b370e17520a0e4 Mon Sep 17 00:00:00 2001 From: eFAILution Date: Fri, 2 Oct 2026 08:50:48 -0400 Subject: [PATCH 1/2] docs(readme): modernize the README layout Centered header with Marketplace badges, a short quick start, one section per feature next to its demo, and collapsible reference sections for settings, advanced setup, and troubleshooting. --- README.md | 264 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 163 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 8548f4a..a473473 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,65 @@ -# ๐Ÿš€ GitLab Component Helper +

+ GitLab Component Helper +

-[![AICaC](https://img.shields.io/badge/AICaC-Comprehensive-success.svg)](https://github.com/eFAILution/AICaC) +

GitLab Component Helper

-> Browse, insert, and manage reusable GitLab CI/CD components in VS Code โ€” from any GitLab instance, public or private. +

+ 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. +

-### Component Browser -![componentBrowser](https://github.com/user-attachments/assets/6e4ad12e-d3f5-4165-8b72-c59bda51ae38) +

+ Marketplace version + Installs + CI status + MIT license + AICaC +

---- +

+ Quick start ยท + Features ยท + Configuration ยท + Commands ยท + Settings ยท + Troubleshooting +

-## โœจ Features +![Browsing and inserting a component from the Component Browser](https://github.com/user-attachments/assets/6e4ad12e-d3f5-4165-8b72-c59bda51ae38) -- **Component Browser** โ€” explore and insert components from any GitLab project or group -- **Smart Completion** โ€” context-aware suggestions for components and versions as you type -- **Hover Docs** โ€” full documentation and parameter hints inline; when a component declares no description, its README's opening lines stand in -- **Input Validation** โ€” real-time checking of component inputs, with Quick Fix suggestions -- **Local Includes** โ€” the same hover, completion, and validation for `include: - local:` entries that declare a `spec.inputs` block -- **Version Picker & Upgrade Hints** โ€” pick the right tag, and get flagged when a pinned semver falls behind (with one-click updates) -- **Variable Expansion** โ€” resolves GitLab CI/CD variables (`$CI_SERVER_FQDN`, `$CI_PROJECT_PATH`, โ€ฆ) in component URLs -- **Private Access** โ€” add private projects/groups with a token, stored encrypted per instance -- **Fast** โ€” caching and batched API calls keep large catalogs responsive +[GitLab CI/CD components](https://docs.gitlab.com/ci/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. -![componentAutofill](https://github.com/user-attachments/assets/a76ba19a-240b-4799-a08f-88a78a5cf004) +## Quick start ---- +1. Install **GitLab Component Helper** from the Extensions view, or run `code --install-extension eFAILution.gitlab-component-helper`. +2. Open a `.gitlab-ci.yml` and type `component:`. Suggestions come with versions already filled in. +3. Hover any component URL to read its docs and inputs. +4. Run **GitLab CI: Browse Components** from the Command Palette to explore everything your sources offer. -## ๐Ÿ› ๏ธ Quick Start +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. -1. **Install** "GitLab Component Helper" from the VS Code Extensions view. -2. **Browse** โ€” `Ctrl+Shift+P` โ†’ **GitLab CI: Browse Components**. -3. **Add a source** โ€” **GitLab CI: Add Component Project/Group** (public or private; token optional). -4. **Author** โ€” type `component:` in a `.gitlab-ci.yml` and accept the versioned suggestions. -5. **Hover** any component URL for instant documentation. +## Features -![hoverContext](https://github.com/user-attachments/assets/3c92f336-db04-4a68-80cf-43732d96b6f1) +### 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. -## ๐Ÿ”’ Private Components +### Complete as you type -Add a private project or group with a personal access token โ€” once per GitLab instance, then it's reused for that instance. Tokens are stored with VS Code **SecretStorage** (encrypted, never in plain text or files) and used only for API calls to the instance you added. +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. -Create the token with the **`read_api`** scope, and ensure its user has at least **Reporter** access to the project. +![Autocompleting a component and its version](https://github.com/user-attachments/assets/a76ba19a-240b-4799-a08f-88a78a5cf004) -> โš ๏ธ The legacy `gitlabComponentHelper.gitlabToken` setting stores tokens in plain text in `settings.json` and is **deprecated**. Use **GitLab CI: Add Component Project/Group** instead, then clear the field. +### 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. -## โšก Example +![Hover documentation for a component](https://github.com/user-attachments/assets/3c92f336-db04-4a68-80cf-43732d96b6f1) + +### Inputs that check themselves + +Inputs are checked as you type. Unknown names and missing required inputs get flagged, with Quick Fixes to add what's missing. ```yaml include: @@ -57,7 +69,12 @@ include: workspace: "default" ``` -Local templates work the same way โ€” point a `- local:` entry at a workspace YAML that declares a `spec.inputs` block and you get the same hover, completion, and validation: +![Inserting component inputs](https://github.com/user-attachments/assets/098f4eaf-3c4a-45a8-9caf-9a1351730b93) +![Validating component inputs](https://github.com/user-attachments/assets/54d4b2ce-ad84-4bbc-8cd7-911a01565536) + +### Local includes too + +`include: - local:` entries get the same hover, completion, and validation, as long as the target file declares a `spec.inputs` block. ```yaml include: @@ -67,53 +84,76 @@ include: job_type: nightly ``` -![insertInputs](https://github.com/user-attachments/assets/098f4eaf-3c4a-45a8-9caf-9a1351730b93) -![inputsValidation](https://github.com/user-attachments/assets/54d4b2ce-ad84-4bbc-8cd7-911a01565536) +### 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. -## ๐Ÿ†™ Stay on the Latest Version +To change that, open the Component Browser, load a component's versions, and right-click the version dropdown: -When a component is pinned to a semantic version (`X.Y.Z`), the extension checks whether a newer **stable** release exists and helps you upgrade: +- **Set as Default Version** pins the version you picked. +- **Always Use Latest** always offers the highest stable version. -- **Hover** shows the latest available version next to the one you're on โ€” `โœ“ up to date` or `โš ๏ธ update available`. -- An outdated pin gets a **warning squiggle** on the version ref, with an **Update to `X.Y.Z`** quick fix (`Ctrl+.`). -- **GitLab CI: Update All Component Versions to Latest** rewrites every outdated pin in the active file at once. +Choosing one replaces the other. The choice is saved in `gitlabComponentHelper.versionPreferences` in your user settings, keyed by `//`, 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. -Completion and the Component Browser pick the same default version for each component: the highest semantic version, falling back to `main` or `master` when the project has no releases. To pin a different choice, open the Component Browser, load a component's versions, and right-click the version dropdown. **Set as Default Version** pins that version, and **Always Use Latest** offers the highest stable version available when you insert. Choosing one replaces the other for that component. The choice is stored in `gitlabComponentHelper.versionPreferences` in your user settings, keyed by `//`, where `~latest` marks Always Use Latest. You can edit or clear it there. A workspace entry for the same component takes precedence over your user setting. +
-Only clean `X.Y.Z` pins (optionally `v`-prefixed) are checked โ€” floating refs (`main`, `latest`, `~latest`), partial pins (`1`, `1.2`), and commit SHAs are left untouched, and pre-release tags are never suggested. The check runs when a CI file is opened or saved (not on every keystroke) and reuses the version cache. Toggle it with `gitlabComponentHelper.versionCheck.enabled`; soften the squiggle to an informational underline with `gitlabComponentHelper.versionCheck.severity`. +### 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. -## โš™๏ธ Configuration +- 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. -Point the extension at your component sources in VS Code settings: +> **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. -```json +### Fast on big catalogs + +Component data is cached (one hour by default) and API calls are batched, so large groups stay responsive. + +## Configuration + +Most people only need component sources. Add them with the command above, or in `settings.json`: + +```jsonc "gitlabComponentHelper.componentSources": [ { "name": "OpenTofu Components", "path": "components/opentofu", "gitlabInstance": "gitlab.com" }, { "name": "Internal CI Components", "path": "devops/ci-components", "gitlabInstance": "gitlab.company.com" } ] ``` -To recognise CI files kept outside the defaults (`.gitlab-ci.yml`, `.gitlab-ci.yaml`, and anything under `.gitlab/`), add globs โ€” they're merged with the built-in defaults and match at any depth: +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: ```jsonc "gitlabComponentHelper.additionalFileGlobs": ["**/ci/*.yml", "**/pipelines/**/*.yaml"] ``` -**Advanced setups** have their own guides: -- [Component discovery tuning](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/discovery.md) โ€” scan custom directories or depths for repos that pre-date the [GitLab Components spec](https://docs.gitlab.com/ci/components/#directory-structure). -- [Monorepo tag conventions](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/monorepo-tags.md) โ€” scope per-component tags in a tag-per-component monorepo. +
+Advanced setups +
-Every setting is listed in the [Settings Reference](#-settings-reference) below and editable from the VS Code Settings UI. +- **[Component discovery tuning](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/discovery.md):** scan custom directories or depths for repos that pre-date the [GitLab components layout](https://docs.gitlab.com/ci/components/#directory-structure). +- **[Monorepo tag conventions](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/monorepo-tags.md):** scope per-component tags in a tag-per-component monorepo. ---- +
-## ๐Ÿ“ Template Header Spec (Optional) +
+Template header comments (for component authors) +
-Add spec-compliant header comments to the top of a template to surface consistent context in the Component Browser. Supported keys: `summary`, `usage`, `note`. +Add header comments to the top of a template to show consistent context in the Component Browser. Supported keys are `summary`, `usage`, and `note`. ```yaml # @gitlab-component-helper: summary: Push a Helm chart to Sonic @@ -121,42 +161,42 @@ Add spec-compliant header comments to the top of a template to surface consisten # @gitlab-component-helper: note: Requires a protected ref for publish ``` -The short prefix `# @gch:` works too. Headers must appear before any non-comment content; multiple `note` lines are allowed, and the section stays hidden if no header is present. Component details also include a **Raw YAML** toggle for inspecting the original template. - -When a component or project has no description of its own, the Component Browser and hover fall back to the opening paragraph of its `README.md` โ€” checked alongside the template first, then at the repository root. - ---- +- 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. -## ๐Ÿงฉ Commands +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. -Run from the Command Palette (`Ctrl+Shift+P`): +
-- **GitLab CI: Browse Components** โ€” explore and insert from your sources -- **GitLab CI: Add Component Project/Group** โ€” add a project/group (optional token for private access) -- **GitLab CI: Update All Component Versions to Latest** โ€” bump outdated semver pins in the active file -- **GitLab CI: Refresh Components Cache** / **Update Cache** / **Reset Cache** โ€” refresh, force a full re-fetch, or clear cached data -- **GitLab CI: Show Cache Status** โ€” cache info and stats +## Commands -Debugging commands are also available: **Debug Cache (Detailed)**, **Show Performance Statistics**, and **Test Providers**. +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 | -## ๐Ÿ†˜ Troubleshooting +For debugging there's also **Debug Cache (Detailed)**, **Show Performance Statistics**, and **Test Providers**. -- **No components showing?** Confirm the file's language mode is YAML and that component sources are configured. -- **HTTP 401 / "token expired" errors?** The token is expired or invalid โ€” re-add it via **GitLab CI: Add Component Project/Group**, or the **Update Token** action in the error view. Confirm it has the **`read_api`** scope and at least **Reporter** access. -- **Version dropdown not loading?** Check connectivity to the GitLab instance, verify token/permissions, and refresh the cache. -- **Still stuck?** Set `gitlabComponentHelper.logLevel` to `DEBUG`, reproduce, and open an issue with the output and your configuration. +## Settings reference ---- +Every setting is also editable from the Settings UI under **GitLab Component Helper**. -## โš™๏ธ Settings Reference - -Add these to `settings.json` or configure them via the Settings UI. +
+All settings +
| Setting | Type | Default | Description | -|--------|------|---------|-------------| -| `gitlabComponentHelper.componentSources` | array | _see [Configuration](#-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.componentSources` | array | _see [Configuration](#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`. | @@ -169,21 +209,49 @@ Add these to `settings.json` or configure them via the Settings UI. | `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](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/discovery.md). | | `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.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. | +| `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. -## ๐Ÿ”Œ API +
-The extension is designed to expose a programmatic API for other extensions to consume โ€” see [docs/api.md](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/api.md). **Status: not yet exposed** (`activate()` does not return the API today); the doc describes the intended contract. +
+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**. -## ๐Ÿง‘โ€๐Ÿ’ป Development +
-**Prerequisites:** VS Code 1.120.0+, Node.js 22.x+, npm. +
+Still stuck? +
+ +Set `gitlabComponentHelper.logLevel` to `DEBUG`, reproduce the problem, and [open an issue](https://github.com/eFAILution/gitlab-component-helper/issues) with the output and your configuration (leave out any tokens). + +
+ +## Contributing + +Issues and pull requests are welcome. ```bash git clone https://github.com/eFAILution/gitlab-component-helper.git @@ -192,20 +260,14 @@ npm install npm run compile ``` -Press `F5` to launch an Extension Development Host with the extension loaded. - ---- - -## ๐Ÿค Contributing - -1. Fork and branch (`git checkout -b feat/your-feature`). -2. Commit using [conventional commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `chore:`, โ€ฆ). -3. Open a Pull Request. +Press `F5` to launch an Extension Development Host with the extension loaded. You'll need VS Code 1.120.0+ and Node.js 22+. -Releases are two-stage: **[release-it](https://github.com/release-it/release-it)** bumps the version and `CHANGELOG.md` from the commit history when changes land on `beta`/`main`, then publishing to the Marketplace is a **manually-dispatched** GitHub Actions workflow (Publish / Publish Beta). See [docs/RELEASING.md](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/RELEASING.md). +- Branch from `beta` and use [conventional commits](https://www.conventionalcommits.org/) (`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](https://github.com/release-it/release-it) when changes land on `beta` or `main`. Publishing to the Marketplace is a manual workflow. See [docs/RELEASING.md](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/RELEASING.md). ---- +A programmatic API for other extensions is planned but not exposed yet. [docs/api.md](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/api.md) describes the intended contract. -## ๐Ÿ“„ License +## License -MIT โ€” see [`LICENSE`](./LICENSE). +[MIT](https://github.com/eFAILution/gitlab-component-helper/blob/main/LICENSE) From 366c8fa4aebd42753b8e3cf1d17beab51b7334b6 Mon Sep 17 00:00:00 2001 From: eFAILution Date: Fri, 2 Oct 2026 09:11:46 -0400 Subject: [PATCH 2/2] docs(readme): swap in new feature GIFs Re-recorded demos for the Component Browser, completion, hover, input checks, and version upgrades. Adds a GIF to the version section, which had none. --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a473473..7ed29df 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Troubleshooting

-![Browsing and inserting a component from the Component Browser](https://github.com/user-attachments/assets/6e4ad12e-d3f5-4165-8b72-c59bda51ae38) +![Searching the Component Browser, picking inputs, and inserting a component](https://github.com/user-attachments/assets/83dd2645-7cdc-4bfa-a6bc-4a315f0c1ea8) [GitLab CI/CD components](https://docs.gitlab.com/ci/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. @@ -49,13 +49,13 @@ The Component Browser lists every component from your configured projects and gr 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. -![Autocompleting a component and its version](https://github.com/user-attachments/assets/a76ba19a-240b-4799-a08f-88a78a5cf004) +![Autocompleting a component and picking its version](https://github.com/user-attachments/assets/84e9a936-ed33-471b-8f59-5e8126b23577) ### 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. -![Hover documentation for a component](https://github.com/user-attachments/assets/3c92f336-db04-4a68-80cf-43732d96b6f1) +![Hovering a component and one of its inputs](https://github.com/user-attachments/assets/4c945758-e077-4890-8285-cf69dfb16891) ### Inputs that check themselves @@ -69,8 +69,7 @@ include: workspace: "default" ``` -![Inserting component inputs](https://github.com/user-attachments/assets/098f4eaf-3c4a-45a8-9caf-9a1351730b93) -![Validating component inputs](https://github.com/user-attachments/assets/54d4b2ce-ad84-4bbc-8cd7-911a01565536) +![Fixing a mistyped input, then filling a local template's inputs](https://github.com/user-attachments/assets/97f44dd4-105b-4002-9bf5-8584cfee0940) ### Local includes too @@ -92,6 +91,8 @@ When a component is pinned to a semantic version (`X.Y.Z`, optionally `v`-prefix - 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. +![Updating an outdated pin with a Quick Fix, then updating the rest](https://github.com/user-attachments/assets/85ecce79-7187-42b3-9b97-c88437026e1c) + 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.