@vzn/vx-ci 0.0.643 → 0.0.644

package/README.md

@@ -2,9 +2,10 @@
 
 Website: <https://vznjs.github.io/vx/> · this plugin: <https://vznjs.github.io/vx/plugins/vx-ci/> · source: <https://github.com/vznjs/vx>
 
-GitHub Actions integration for [`@vzn/vx`](https://vznjs.github.io/vx/) — a
-telemetry plugin that writes every `vx run` as a **job summary** on the
-workflow run page.
+GitHub Actions and GitLab CI integration for [`@vzn/vx`](https://vznjs.github.io/vx/):
+`github()` writes every `vx run` as a **job summary** on the workflow run
+page and names the run's cache scope; `gitlab()` names the run's cache
+scope on GitLab CI ([below](#gitlab-ci)).
 
 ```sh
 npm install -D @vzn/vx @vzn/vx-ci   # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
@@ -39,8 +40,8 @@ checked and nothing loads, so declaring it unconditionally is safe.
 
 The options type is `GithubPluginOptions`; `renderJobSummary` renders the
 summary lines the plugin posts (the site's CI guide sample is rendered from it).
-The package exports `github`, `renderJobSummary` and the types `GithubPluginOptions`
-and `FetchFn`; nothing else. `fetchFn`, `append` and `sizeOf` are test seams:
+The package exports `github`, `gitlab`, `renderJobSummary` and the types
+`GithubPluginOptions`, `GitlabPluginOptions` and `FetchFn`; nothing else. `fetchFn`, `append` and `sizeOf` are test seams:
 they replace the Checks API transport, the summary writer and its size probe.
 
 ```ts
@@ -64,7 +65,10 @@ the default keys). A push to, or a pull request from, a branch names
 fork's pull request names the fork; so does a `pull_request_target` or
 `workflow_run` run on a PR's behalf (by `GITHUB_EVENT_NAME`, though its
 ref is main's), and an `issue_comment` on a PR, which names no branch,
-`pr-<n>`. A pull request also names its base commit
+`pr-<n>`. A merge queue's run (`merge_group`) is trusted: no scope,
+whatever its `gh-readonly-queue/...` branch, so it reads and writes only
+the default keys (`x-vx-cache-scope: trusted`), compared with
+`merge_group.base_sha`. A pull request also names its base commit
 (`pull_request.base.sha`), so vx diffs the merge checkout from it with
 no git call. A scoped run's changed tasks read the scope's remote entry,
 the rest the default keys, and every task it builds is saved to the
@@ -76,6 +80,33 @@ real boundary is a cache token the server limits, so give PR jobs one
 that cannot write the default keys (`docs/security.md` § Cache
 poisoning).
 
+## GitLab CI
+
+```ts
+// .vx/workspace.ts
+import { defineWorkspace } from '@vzn/vx/config'
+import { github, gitlab } from '@vzn/vx-ci'
+
+export default defineWorkspace({ plugins: [github(), gitlab()] })
+```
+
+On GitLab CI (`GITLAB_CI=true`) `gitlab()`'s `config` stage names the
+run's branch through `ctx.setBranch`, from GitLab's predefined
+variables, as `github()` does on Actions. The default branch
+(`CI_DEFAULT_BRANCH`) names no scope. Another branch or a tag (`CI_COMMIT_TAG`) names
+`<project path>:<ref>` (`CI_PROJECT_PATH`, `CI_COMMIT_REF_NAME`), so a
+subgroup's project is `group/sub/app:feat-x`, the scope a laptop on
+`feat-x` derives. A merge request pipeline names its source branch
+(`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`) in the project it lives in (a
+fork's `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base
+(`CI_MERGE_REQUEST_DIFF_BASE_SHA`), so vx diffs from it with no git
+call. A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
+builds what lands on the target, so it is trusted: no scope, only the
+default keys. `gitlab({ cacheScope: false })` (`GitlabPluginOptions`) turns it off;
+`VX_CACHE_SCOPE` overrides it. Anywhere else `gitlab()` returns
+`undefined`, so declaring both plugins is safe. Merge request comments
+and reports are not part of it yet.
+
 ## How it works
 
 `github()` contributes one observe-only telemetry sink through vx's

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.643",
+  "version": "0.0.644",
   "license": "MIT",
-  "description": "GitHub Actions integration for vx — a telemetry plugin that writes the run as a GitHub Actions job summary.",
+  "description": "GitHub Actions and GitLab CI integration for vx — a job summary on Actions and the branch cache scope on both.",
   "keywords": [
     "vx",
     "vx-plugin",
     "monorepo",
     "github-actions",
+    "gitlab-ci",
     "job-summary",
     "checks"
   ],
@@ -33,7 +34,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.643"
+    "@vzn/vx": "^0.0.644"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -2,7 +2,7 @@
 // `setBranch`: the default branch writes the default keys, a branch its own
 // scope, the one a laptop on that branch reads (owner, 2026-10-17).
 import { readFile } from 'node:fs/promises'
-import { branchCacheScope } from '@vzn/vx'
+import { type BranchFacts, branchCacheScope } from '@vzn/vx'
 
 /**
  * What an Actions run knows of its branch (owner, 2026-10-17). `scope`:
@@ -15,15 +15,21 @@ import { branchCacheScope } from '@vzn/vx'
  * `workflow_run` a PR started) is the PR's, whatever `GITHUB_REF` says: a
  * workflow that checks out the PR's head there would otherwise write the
  * default keys. `issue_comment` names no branch, so it writes `pr-<n>`.
+ * A merge queue's run (`merge_group`) is trusted (owner, 2026-10-18): no
+ * scope, only the default keys, compared with `merge_group.base_sha`.
  * `base`: a pull request's base commit (`pull_request.base.sha`), what its
  * merge checkout is compared with, no git call needed.
  */
 export async function githubBranch(
   env: Readonly<Record<string, string | undefined>>,
-): Promise<{ scope?: string; base?: string }> {
+): Promise<BranchFacts> {
   if (env['GITHUB_ACTIONS'] !== 'true') return {}
   const ref = env['GITHUB_REF'] ?? ''
   const event = await eventOf(env['GITHUB_EVENT_PATH'])
+  if (env['GITHUB_EVENT_NAME'] === 'merge_group') {
+    const base = stringOf(event?.merge_group?.base_sha)
+    return { trusted: true, ...(base !== undefined ? { base } : {}) }
+  }
   const repo = stringOf(event?.repository?.full_name) ?? env['GITHUB_REPOSITORY']
   const base = stringOf(event?.pull_request?.base?.sha)
   const withBase = (scope: string | undefined): { scope?: string; base?: string } => ({
@@ -54,6 +60,7 @@ interface ActionsEvent {
     base?: { sha?: unknown }
   }
   issue?: { number?: unknown; pull_request?: unknown }
+  merge_group?: { base_sha?: unknown }
   workflow_run?: {
     event?: unknown
     head_branch?: unknown

package/src/gitlab.ts

@@ -0,0 +1,63 @@
+// The `gitlab()` plugin (owner, 2026-10-18): on GitLab CI it names the
+// run's branch through `setBranch`, as `github()` does on Actions. Off
+// GitLab CI (`GITLAB_CI` not 'true') the factory returns undefined, which
+// `plugins` skips, so declaring it costs nothing on a laptop.
+import {
+  type BranchFacts,
+  branchCacheScope,
+  definePlugin,
+  type PluginOptionKinds,
+  refuseUnknownOptions,
+  type VxPlugin,
+} from '@vzn/vx'
+
+export interface GitlabPluginOptions {
+  /**
+   * Name the run's cache scope and base commit from GitLab's predefined
+   * variables: the default branch and a merge train read and write the
+   * default keys, any other branch `<project path>:<branch>`, and a merge
+   * request is compared with its diff base. `VX_CACHE_SCOPE` beats it.
+   * Default: on; `false` opts out.
+   */
+  cacheScope?: boolean
+}
+
+const GITLAB_PLUGIN_KEYS: PluginOptionKinds<GitlabPluginOptions> = {
+  cacheScope: 'boolean',
+}
+
+export function gitlab(options: GitlabPluginOptions = {}): VxPlugin | undefined {
+  if (process.env['GITLAB_CI'] !== 'true') return undefined
+  refuseUnknownOptions('gitlab()', options, GITLAB_PLUGIN_KEYS)
+  return definePlugin(import.meta, {
+    config(_workspace, ctx) {
+      if (options.cacheScope === false) return
+      ctx.setBranch(gitlabBranch(process.env))
+    },
+  })
+}
+
+/**
+ * What a GitLab CI job knows of its branch. A merge request pipeline names
+ * its source branch in the project it lives in (a fork's own,
+ * `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`) and its diff base; a merge
+ * train's pipeline builds what lands on the target, so it is trusted; a
+ * branch or tag pipeline names its ref, none on the default branch.
+ */
+function gitlabBranch(env: Readonly<Record<string, string | undefined>>): BranchFacts {
+  const value = (key: string): string | undefined => env[key] || undefined
+  const base = value('CI_MERGE_REQUEST_DIFF_BASE_SHA')
+  const withBase = (facts: BranchFacts): BranchFacts =>
+    base === undefined ? facts : { ...facts, base }
+  if (value('CI_MERGE_REQUEST_EVENT_TYPE') === 'merge_train') return withBase({ trusted: true })
+  const project = value('CI_PROJECT_PATH')
+  const source = value('CI_MERGE_REQUEST_SOURCE_BRANCH_NAME')
+  if (source !== undefined) {
+    const from = value('CI_MERGE_REQUEST_SOURCE_PROJECT_PATH') ?? project
+    return withBase(from === undefined ? {} : { scope: branchCacheScope(from, source) })
+  }
+  const ref = value('CI_COMMIT_REF_NAME')
+  if (project === undefined || ref === undefined) return {}
+  if (value('CI_COMMIT_TAG') === undefined && ref === value('CI_DEFAULT_BRANCH')) return {}
+  return { scope: branchCacheScope(project, ref) }
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-// Public API for @vzn/vx-ci — the GitHub Actions integration plugin.
+// Public API for @vzn/vx-ci — the GitHub Actions and GitLab CI plugins.
 //
 // Usage in .vx/workspace.ts:
 //   import { defineWorkspace } from '@vzn/vx'
@@ -9,6 +9,7 @@
 // appends a job summary: verdict, stats, failures, and the per-task table.
 // Anywhere else the plugin declines and costs nothing.
 export { github, type GithubPluginOptions } from './plugin.js'
+export { gitlab, type GitlabPluginOptions } from './gitlab.js'
 export { renderJobSummary } from './summary.js'
 
 // The Checks API helpers are the plugin's own; only the transport type