gitlab-integration.md

RFC: setup-vp GitLab CI/CD Remote Template

The original rollout examples below describe the initial release. For current inputs and usage, see the README. Version resolution, Node selection, project auth, and install execution now use shared portable primitives under src/ci/.

Summary

This RFC proposes a GitLab CI/CD remote template for voidzero-dev/setup-vp. The template lets GitLab users install Vite+, configure registry auth, and optionally run vp install while keeping the source of truth in this GitHub repository.

The template is published as a plain YAML file plus a shell bootstrap. The maintainable runtime is TypeScript under src/gitlab/ and is distributed as a precompiled JavaScript bundle under dist/gitlab/.

gitlab/setup-vp.yml
gitlab/bootstrap.sh
src/gitlab/*.ts
dist/gitlab/index.mjs

GitLab users load it with include:remote:

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

Motivation

setup-vp is currently a GitHub Action. Its TypeScript implementation depends on the GitHub Actions runtime, including action inputs, path management, state, outputs, and post-action cache behavior. GitLab CI/CD cannot execute that action directly with equivalent semantics.

The goal is to provide a GitLab-native entry point without creating a separate GitLab project or mirror. GitLab supports remote YAML includes, so a template hosted from GitHub can be reused directly by GitLab pipelines.

Relevant GitLab documentation:

• https://docs.gitlab.com/ci/yaml/#includeremote
• https://docs.gitlab.com/ci/yaml/#includeinputs
• https://docs.gitlab.com/ci/yaml/#includeintegrity
• https://docs.gitlab.com/ci/caching/
• https://docs.gitlab.com/ci/migration/github_actions/

Goals

1. Provide a GitLab CI/CD template from this GitHub repository only.
2. Support include:remote with spec:inputs.
3. Keep GitLab input names as close as possible to the GitHub Action inputs.
4. Install Vite+ from the official installer with retry and fallback URLs.
5. Support the default run-install: true experience and advanced run-install entries with cwd and args.
6. Support private registry auth through registry-url, scope, and NODE_AUTH_TOKEN.
7. Support sfw: true for vp install.
8. Require Node.js in the selected GitLab runner image, matching the model that the runtime script is executed by Node.js.
9. Document where GitLab behavior cannot match GitHub Actions.

Non-Goals

1. Do not create or require a GitLab project.
2. Do not publish a GitLab CI/CD component.
3. Do not use include:component for the initial design.
4. Do not run the GitHub Action bundle (dist/index.mjs) inside GitLab.
5. Do not implement GitHub Actions cache semantics inside the GitLab template.
6. Keep shell-specific bootstraps thin; Windows uses gitlab/setup-vp-windows.yml and the same compiled runtime.

Design

Distribution Model

The template is stored in this repository and referenced by raw GitHub URL.

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"

Consumers should pin a tag or commit instead of main. GitLab 17.9+ users can also use include:integrity when they want to pin the remote file hash.

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.0.0/gitlab/setup-vp.yml"
    integrity: "sha256-..."
    inputs:
      run-install: "true"

include:component is intentionally not used. It is designed for GitLab CI/CD components resolved from a GitLab component project, which conflicts with the "GitHub repository only" constraint.

Template Shape

gitlab/setup-vp.yml defines two YAML documents and intentionally stays thin:

1. spec:inputs for GitLab include inputs.
2. A hidden .setup-vp job that exports inputs, downloads bootstrap.sh, and executes it.

spec:
  inputs:
    version:
      default: "latest"
    working-directory:
      default: "."
    run-install:
      default: "true"
    sfw:
      type: boolean
      default: false
    registry-url:
      default: ""
    scope:
      default: ""
    setup-ref:
      default: "v1"
---
.setup-vp:
  before_script:
    - |
      # export inputs, download bootstrap.sh, and execute it

Bootstrap And Runtime

Implementation logic is split to keep shell small:

• gitlab/setup-vp.yml handles GitLab inputs and downloads bootstrap.sh.
• gitlab/bootstrap.sh installs Vite+, checks that Node.js is available, downloads dist/gitlab/index.mjs, and runs it.
• src/gitlab/*.ts handles maintainable logic split by responsibility: registry auth, sfw, run-install parsing, install execution, shell helpers, path resolution, and final orchestration.
• dist/gitlab/index.mjs is generated from src/gitlab/index.ts by vp pack, mirroring how the GitHub Action runs dist/index.mjs generated from TypeScript.

This intentionally requires users to choose a runner image that already contains Node.js, such as node:24. GitLab remote templates run inside the user-selected image, so requiring Node.js keeps the template simple and avoids bootstrapping a runtime before the compiled JavaScript can execute.

Remote includes do not provide a portable way for the included YAML to discover the exact Git ref used in the include:remote URL. For that reason the template has a setup-ref input. The default points at v1, and users who need strict reproducibility should pass the same tag or commit SHA as the template include.

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.0.0/gitlab/setup-vp.yml"
    inputs:
      setup-ref: "v1.0.0"

The runtime handoff is intentionally explicit:

Execution Flow

The hidden job runs in before_script so that the user's script can assume vp is available.

1. Export GitLab inputs into SETUP_VP_* environment variables.
2. Download and execute bootstrap.sh from setup-ref.
3. Install Vite+ from https://viteplus.dev/install.sh.
4. Fall back to the raw GitHub installer if the primary installer fails.
5. Add ~/.vite-plus/bin to PATH.
6. Verify that node is available in the runner image.
7. Download and execute dist/gitlab/index.mjs from setup-ref.
8. Resolve working-directory.
9. Configure temporary npm auth when registry-url is set.
10. Install or detect sfw when sfw: true.
11. Run vp install when run-install is enabled.
12. Print vp --version.

Node.js Runtime Requirement

The GitLab template does not expose node-version or node-version-file. Instead, jobs must select an image or environment where Node.js is already available:

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

This differs from the GitHub Action, where GitHub provides a built-in Node.js runtime for actions. In both cases, TypeScript source is not executed directly: GitHub Actions runs dist/index.mjs, and the GitLab template runs dist/gitlab/index.mjs.

Run Install

The default matches GitHub Actions:

run-install: "true"

The GitLab template also supports multiple install entries:

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"
    inputs:
      run-install: |
        - cwd: ./packages/app
          args: ['--frozen-lockfile']
        - cwd: ./packages/lib

test:
  extends: .setup-vp
  image: node:24
  script:
    - vp run test

This is intentionally modeled after the GitHub Action's structured run-install input rather than adding a separate install-args input. Keeping one input avoids diverging user experience between GitHub and GitLab.

Socket Firewall Free

sfw: true wraps install commands as sfw vp install ....

include:
  - remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"
    inputs:
      sfw: true
      run-install: "true"

If sfw is already on PATH, the template reuses it. Otherwise it downloads a pinned sfw-free release for Linux, macOS, or Windows when a matching binary exists. If the runner architecture is unsupported, the template logs a warning and falls back to plain vp install.

Public API

Input	Default	Description
version	latest	Version of Vite+ to install.
working-directory	.	Project directory used for relative paths and default vp install execution.
run-install	true	Run vp install; accepts boolean or YAML object/array with cwd and args.
sfw	false	Wrap vp install with Socket Firewall Free.
registry-url		Optional registry URL to write to a temporary .npmrc.
scope		Optional scope for authenticating against scoped registries.
setup-ref	v1	Ref used to download bootstrap.sh and dist/gitlab/index.mjs.

Current Parity and Cache Design

GitLab and GitHub now share Vite+ version resolution from explicit inputs, package manifests, catalogs, and lockfiles. Both support Node version files and explicit vp env use selection, project .npmrc auth, full YAML install entries, and the bounded sfw command-lookup retry. Windows runners use the PowerShell template; Unix runners keep the Bash template.

Native caching remains provider-specific. Extend .setup-vp-cached to persist .setup-vp-cache/. GitLab restores this project-relative directory before setup; the runtime then copies a compatible snapshot into the store returned by vp pm cache dir. Snapshots are separated by OS, architecture, and package manager. A lock-file hash distinguishes exact hits from fallback data. The job's after_script snapshots the store again before GitLab uploads it. The same native cache also holds version/platform-specific sfw binaries.

The cache-dependency-path input selects a lock file. cache-policy: pull restores without uploading; the default is pull-push. Cache policy is static YAML because GitLab restores before any job scripts run. Existing jobs can override the native cache mapping. See GitLab caching.

SETUP_VP_INSTALLED_VERSION and SETUP_VP_CACHE_HIT are exported to the job shell and written to .setup-vp-outputs.env. Consumers can publish that file as a dotenv report. Auth values are not included.

Security

Remote includes execute as CI configuration, so examples should recommend pinning:

• Prefer v1, an immutable version tag such as v1.0.0, or a commit SHA.
• Avoid main in production pipelines.
• Use include:integrity where available for stricter remote file validation.
• Pin setup-ref to the same immutable tag or commit SHA when strict reproducibility is required. include:integrity validates the included YAML, not the bootstrap or compiled runtime downloaded by that YAML.

The template downloads installers and optional sfw binaries at runtime. The downloaded sfw version is pinned in the template for reproducibility. Users who need stronger supply-chain guarantees can install a SHA-pinned sfw binary before extending .setup-vp; the template will reuse sfw from PATH.

Rollout

1. Add gitlab/setup-vp.yml.
2. Add gitlab/bootstrap.sh.
3. Add the src/gitlab/ TypeScript runtime modules.
4. Generate dist/gitlab/index.mjs with vp pack.
5. Add this RFC under rfcs/.
6. Document GitLab usage in README.md.
7. Validate YAML parsing and shell/Node syntax locally.
8. Validate the remote include through GitLab CI Lint before release.
9. Release under v1 and an immutable semver tag.