@vzn/vx-ci 0.0.642 → 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
@@ -55,16 +56,56 @@ github({
 
 ## Cache scope
 
-On Actions (`GITHUB_ACTIONS=true`), when `.vx/workspace.ts` sets no `cache.scope`, the plugin's
-`config` stage sets it from the ref (`GITHUB_REF`, `GITHUB_REF_NAME`, and
-the default branch from the `GITHUB_EVENT_PATH` payload): a push to the default branch sets
-none (reads and writes the default keys), a pull request becomes
-`pr-<n>` (so is a `pull_request_target`, `issue_comment` or `workflow_run`
-run on a PR's behalf, by `GITHUB_EVENT_NAME`, though its ref is main's) and any other branch or tag `ref-<name>`, which read the
-default keys, then their own, and write only their own. A PR never writes what main
-reads. Whether a run writes at all is `cache.policy`'s call. `VX_CACHE_SCOPE` or a `cache.scope` in `.vx/workspace.ts` 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).
+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
+`<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 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
+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).
+
+## 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
 

package/package.json

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

package/src/cache-scope.ts

@@ -1,49 +1,99 @@
-// The cache scope a GitHub Actions run gets when the workspace names none:
-// the default branch writes the default keys, anything else its own scope.
+// 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).
 import { readFile } from 'node:fs/promises'
+import { type BranchFacts, branchCacheScope } from '@vzn/vx'
 
 /**
- * `undefined` (the default keys) on a push to the
- * default branch, outside Actions, or when the ref is unknown; else
- * `pr-<n>` for a pull request and `ref-<name>` for any other branch or tag.
- * 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.
+ * What an Actions run knows of its branch (owner, 2026-10-17). `scope`:
+ * none on a push to the default branch, outside Actions, or when the ref
+ * is unknown; else `<owner>/<repo>:<branch>`, the repository and branch a
+ * pull request comes from, or the branch or tag pushed. A fork's pull
+ * request names the fork, a scope a laptop on the base repository never
+ * 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>`.
+ * 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 githubCacheScope(
+export async function githubBranch(
   env: Readonly<Record<string, string | undefined>>,
-): Promise<string | undefined> {
-  if (env['GITHUB_ACTIONS'] !== 'true') return undefined
+): Promise<BranchFacts> {
+  if (env['GITHUB_ACTIONS'] !== 'true') return {}
   const ref = env['GITHUB_REF'] ?? ''
-  const pr = /^refs\/pull\/(\d+)\//.exec(ref)
-  if (pr !== null) return `pr-${pr[1]}`
   const event = await eventOf(env['GITHUB_EVENT_PATH'])
-  const onBehalf = prOf(env['GITHUB_EVENT_NAME'], event)
-  if (onBehalf !== undefined) return onBehalf
+  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 } => ({
+    ...(scope !== undefined ? { scope } : {}),
+    ...(base !== undefined ? { base } : {}),
+  })
+  if (/^refs\/pull\/\d+\//.test(ref)) {
+    const head = event?.pull_request?.head
+    const branch = env['GITHUB_HEAD_REF'] || stringOf(head?.ref)
+    if (branch !== undefined)
+      return withBase(headScope(branch, stringOf(head?.repo?.full_name), repo))
+    return withBase('pr-target')
+  }
+  const onBehalf = prOf(env['GITHUB_EVENT_NAME'], event, repo)
+  if (onBehalf !== undefined) return withBase(onBehalf)
   const name = env['GITHUB_REF_NAME']
-  if (ref === '' || name === undefined || name === '') return undefined
+  if (ref === '' || name === undefined || name === '' || repo === undefined) return {}
   const branch = event?.repository?.default_branch
-  if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`)
-    return undefined
-  // `cache.scope` takes letters, digits and . _ - / @; a ref may hold more.
-  return `ref-${name.replace(/[^\w.@/-]/g, '_').slice(0, 124)}`
+  if (typeof branch === 'string' && branch !== '' && ref === `refs/heads/${branch}`) return {}
+  return { scope: branchCacheScope(repo, name) }
 }
 
 interface ActionsEvent {
-  repository?: { default_branch?: unknown }
-  pull_request?: { number?: unknown }
+  repository?: { default_branch?: unknown; full_name?: unknown }
+  pull_request?: {
+    number?: unknown
+    head?: { ref?: unknown; repo?: { full_name?: unknown } }
+    base?: { sha?: unknown }
+  }
   issue?: { number?: unknown; pull_request?: unknown }
-  workflow_run?: { event?: unknown; pull_requests?: { number?: unknown }[] }
+  merge_group?: { base_sha?: unknown }
+  workflow_run?: {
+    event?: unknown
+    head_branch?: unknown
+    head_repository?: { full_name?: unknown }
+    pull_requests?: { number?: unknown }[]
+  }
 }
 
-/** The PR scope of an event that runs in the base branch's context for a PR; `pr-target` when its number is unknown. */
-function prOf(name: string | undefined, event: ActionsEvent | undefined): string | undefined {
-  const scope = (n: unknown): string =>
-    typeof n === 'number' && Number.isInteger(n) && n > 0 ? `pr-${n}` : 'pr-target'
-  if (name === 'pull_request_target') return scope(event?.pull_request?.number)
+function stringOf(v: unknown): string | undefined {
+  return typeof v === 'string' && v !== '' ? v : undefined
+}
+
+/** A head branch's scope: the repository it lives in (a fork's own), then the branch. */
+function headScope(branch: string, headRepo: string | undefined, repo: string | undefined): string {
+  return branchCacheScope(headRepo ?? repo ?? 'unknown/unknown', branch)
+}
+
+/** The scope of an event that runs in the base branch's context for a PR; `pr-target` when its head is unknown. */
+function prOf(
+  name: string | undefined,
+  event: ActionsEvent | undefined,
+  repo: string | undefined,
+): string | undefined {
+  if (name === 'pull_request_target') {
+    const head = event?.pull_request?.head
+    const branch = stringOf(head?.ref)
+    return branch === undefined
+      ? 'pr-target'
+      : headScope(branch, stringOf(head?.repo?.full_name), repo)
+  }
   if (name === 'issue_comment' && event?.issue?.pull_request != null) {
-    return scope(event.issue.number)
+    const n = event.issue.number
+    return typeof n === 'number' && Number.isInteger(n) && n > 0 ? `pr-${n}` : 'pr-target'
   }
   const run = event?.workflow_run
   if (
@@ -51,7 +101,10 @@ function prOf(name: string | undefined, event: ActionsEvent | undefined): string
     typeof run?.event === 'string' &&
     run.event.startsWith('pull_request')
   ) {
-    return scope(run.pull_requests?.[0]?.number)
+    const branch = stringOf(run.head_branch)
+    return branch === undefined
+      ? 'pr-target'
+      : headScope(branch, stringOf(run.head_repository?.full_name), repo)
   }
   return undefined
 }

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

package/src/plugin.ts

@@ -13,7 +13,7 @@ import {
   type VxPlugin,
 } from '@vzn/vx'
 import type { FetchFn } from './checks.js'
-import { githubCacheScope } from './cache-scope.js'
+import { githubBranch } from './cache-scope.js'
 
 // Every run evaluates `.vx/workspace.ts`; the sink, the summary renderer
 // and the Checks API client load only where a summary file is set. The
@@ -40,9 +40,11 @@ export interface GithubPluginOptions {
   /** Check-run name. Default: `'vx'`. */
   checkName?: string
   /**
-   * Set the workspace's `cache.scope` from the run's ref when it names none:
-   * a push to the default branch keeps the default keys, a pull request writes to
-   * `pr-<n>`, any other ref to `ref-<name>`. Default: on; `false` opts out.
+   * 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.
    */
   cacheScope?: boolean
   /** Test seam — inject the append. Defaults to fs appendFile. */
@@ -94,10 +96,9 @@ export function github(options: GithubPluginOptions = {}): VxPlugin | undefined
       throw new UserError(`github() option "${key}" must be a non-empty string, got ""`)
   }
   return definePlugin(import.meta, {
-    async config(workspace) {
-      if (options.cacheScope === false || workspace.cache?.scope !== undefined) return
-      const scope = await githubCacheScope(process.env)
-      if (scope !== undefined) workspace.cache = { ...workspace.cache, scope }
+    async config(_workspace, ctx) {
+      if (options.cacheScope === false) return
+      ctx.setBranch(await githubBranch(process.env))
     },
     telemetry(ctx) {
       const file = options.summaryFile ?? process.env['GITHUB_STEP_SUMMARY']