@vzn/vx-ci 0.0.643 → 0.0.645

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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
@@ -49,7 +50,7 @@ github({
   title: 'build & test', // default: 'vx run'
   checks: true, // default: on with GITHUB_TOKEN; true warns when it is missing, false opts out
   checkName: 'ci', // default: 'vx', the check run's name
-  cacheScope: false, // default: on; scope remote cache writes by ref
+  cacheScope: false, // default: on; scope plugin cache entries by ref
 })
 ```
 
@@ -58,23 +59,46 @@ github({
 On Actions (`GITHUB_ACTIONS=true`) the plugin's `config` stage names the
 run's branch through `ctx.setBranch`, from the ref (`GITHUB_REF`,
 `GITHUB_REF_NAME`, `GITHUB_HEAD_REF`, `GITHUB_REPOSITORY`) and the
-`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope (reads and writes
-the default keys). A push to, or a pull request from, a branch names
+`GITHUB_EVENT_PATH` payload. A push to the default branch names no scope.
+A push to, or a pull request from, a branch names
 `<owner>/<repo>:<branch>` of the repository the branch lives in, so a
 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
-(`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
-remote under the scope; the local cache never knows a scope. A
-PR never writes what main reads, and a laptop on the branch derives the
-same scope. Whether a run writes at all is `cache.policy`'s call.
-`VX_CACHE_SCOPE` overrides it. This is a client-side convention: the
-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).
+`pr-<n>`. A merge queue's run (`merge_group`) is trusted: no scope,
+whatever its `gh-readonly-queue/...` branch, compared with
+`merge_group.base_sha`. A pull request also names its base commit
+(`pull_request.base.sha`), the base of a bare `--affected`. The scope
+keys only what plugins store themselves (`ctx.cache`, run records):
+task keys never carry it, and the cache server decides from the CI OIDC
+token where a task's entry lands. `VX_CACHE_SCOPE` overrides it.
+
+## 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`), the base of a bare `--affected`.
+A merge train's pipeline (`CI_MERGE_REQUEST_EVENT_TYPE=merge_train`)
+builds what lands on the target, so it is trusted: no scope. As on
+Actions, the scope keys only plugin entries. `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
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vzn/vx-ci",
-  "version": "0.0.643",
+  "version": "0.0.645",
   "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.645"
   },
   "repository": {
     "type": "git",

package/src/cache-scope.ts

@@ -1,8 +1,8 @@
 // The cache scope and base commit a GitHub Actions run names through
-// `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).
+// `setBranch`: none on the default branch, a branch its own scope, the one
+// a laptop on that branch derives (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`:
@@ -13,17 +13,23 @@ import { branchCacheScope } from '@vzn/vx'
  * derives. An event that runs in the default branch's context on a pull
  * request's behalf (`pull_request_target`, `issue_comment` on a PR, a
  * `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>`.
+ * workflow that checks out the PR's head there would otherwise share main's
+ * scope. `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, 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: none on the default branch or a merge train, else
+   * `<project path>:<branch>`; a merge request is compared with its diff
+   * base. The scope keys plugin entries only. `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

package/src/plugin.ts

@@ -40,11 +40,11 @@ export interface GithubPluginOptions {
   /** Check-run name. Default: `'vx'`. */
   checkName?: string
   /**
-   * Name the run's cache scope and base commit from the Actions event: a
-   * push to the default branch keeps the default keys, a branch or its pull
-   * request writes to `<owner>/<repo>:<branch>` (a fork's names the fork),
-   * and a pull request is compared with its base commit. `VX_CACHE_SCOPE`
-   * beats it. Default: on; `false` opts out.
+   * Name the run's cache scope and base commit from the Actions event: none
+   * on the default branch, else `<owner>/<repo>:<branch>` (a fork's names
+   * the fork); a pull request is compared with its base commit. The scope
+   * keys plugin entries only. `VX_CACHE_SCOPE` beats it. Default: on;
+   * `false` opts out.
    */
   cacheScope?: boolean
   /** Test seam — inject the append. Defaults to fs appendFile. */