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/.
This RFC adds an Azure Pipelines step template for voidzero-dev/setup-vp. Azure users install Vite+, optionally select Node.js, restore and save the Vite+ package-manager cache through Azure Cache@2, optionally run vp install, and can use Socket Firewall Free and private npm registry authentication.
The template is published from this GitHub repository as:
azure/setup-vp.yml
azure/bootstrap.sh
azure/bootstrap.ps1
src/azure/*.ts
src/ci/*.ts
dist/azure/index.mjs
Consumers reference it through resources.repositories and a GitHub service connection:
resources:
repositories:
- repository: setupVp
type: github
endpoint: github
name: voidzero-dev/setup-vp
ref: refs/tags/v1.16.0
steps:
- template: azure/setup-vp.yml@setupVp
parameters:
setupRef: v1.16.0setup-vp already ships a GitHub Action and a GitLab remote template. Azure Pipelines cannot execute the GitHub Action bundle because it depends on GitHub-specific inputs, state, outputs, and post-action cache APIs.
The GitLab integration established the right pattern: a provider-native template plus a dependency-light compiled runtime. Azure differs in two important ways:
- External templates from GitHub require a service connection.
- Azure
Cache@2restores immediately and saves in a post-job step, so setup-vp must prepare cache metadata before the cache task and runvp installafter it.
- Provide an Azure-native step template from this repository only.
- Support Microsoft-hosted Linux, macOS, and Windows agents.
- Keep Azure parameter names close to the GitHub Action inputs while using Azure camelCase.
- Install Vite+ from the official installer with retry and fallback URLs.
- Support structured
runInstallentries withcwdandargs. - Support private registry auth through
registryUrl,scope, andNODE_AUTH_TOKEN. - Support
sfw: trueforvp install, including Windows assets. - Support Azure
Cache@2around the package-manager cache directory. - Document parity gaps explicitly.
- Do not publish an Azure DevOps Marketplace extension in this release.
- Do not run
dist/index.mjsinside Azure Pipelines. - Keep version resolution shared with GitHub and GitLab; no provider-specific parser.
- Keep provider-specific cache transport outside the shared resolvers.
Azure expands azure/setup-vp.yml from the external repository but does not check out bootstrap/runtime files onto the agent. Each prepare step downloads azure/bootstrap.* from https://raw.githubusercontent.com/voidzero-dev/setup-vp/<setupRef>/azure/ into Agent.TempDirectory, then executes it. The bootstrap downloads dist/azure/index.mjs and runs node <runtime> prepare.
The prepare and finalize steps use the same deterministic runtime path under
$(Agent.TempDirectory)/setup-vp-azure/dist/azure/index.mjs. The runtime is
built as a standalone entrypoint, so downloading that file is sufficient. The
bootstrap also recognizes generated sibling chunks for compatibility with older
refs, and places them beside the runtime when present; finalize therefore does
not depend on cross-step macro expansion of a runtime path.
Pin ref and setupRef to the same immutable tag or commit SHA for strict reproducibility.
- Optional
UseNode@1whenbootstrapNodeVersionis non-empty. prepare: install Vite+, prepend Vite+ bin to PATH, compute cache metadata.- Optional
Cache@2whencache: trueandSETUP_VP_CACHE_READY=true. finalize: configure npm auth, install/reusesfw, runvp install, emitSETUP_VP_INSTALLED_VERSIONand the Node.js and package-manager versions fromvp env current --json.
Provider-independent logic lives in src/ci/ and is reused by GitLab (src/gitlab/) and Azure (src/azure/). Azure-specific logging uses ##vso[task.setvariable] and ##vso[task.prependpath].
| Parameter | Default | GitHub/GitLab equivalent |
|---|---|---|
version |
latest |
version |
workingDirectory |
. |
working-directory |
runInstall |
true |
run-install |
sfw |
false |
sfw |
registryUrl |
registry-url |
|
scope |
scope |
|
setupRef |
v1 |
setup-ref |
nodeVersion |
24.x |
node-version |
cache |
false |
cache |
cacheDependencyPath |
cache-dependency-path |
Provider-visible variables:
| Variable | Purpose |
|---|---|
SETUP_VP_INSTALLED_VERSION |
Installed global Vite+ version |
SETUP_VP_CACHE_HIT |
true, inexact, or false from Cache@2 |
SETUP_VP_INSTALLED_NODE_VERSION |
Node.js version from vp env current (Vite+ 0.3.1+) |
SETUP_VP_PACKAGE_MANAGER_NAME |
Package manager from vp env current (Vite+ 0.3.1+) |
SETUP_VP_PACKAGE_MANAGER_VERSION |
Version of that package manager (Vite+ 0.3.1+) |
For private registries, consumers define NODE_AUTH_TOKEN as an Azure secret
pipeline variable. Both finalize branches explicitly map that secret into the
runtime environment before configuring registry authentication.
| Capability | GitHub | GitLab | Azure |
|---|---|---|---|
| Vite+ package/catalog/lockfile resolution and version files | Shared resolver | Shared resolver | Shared resolver |
| Node version and version-file selection | vp env use |
vp env use |
vp env use |
Project .npmrc auth and explicit registry/scope |
Yes | Yes | Yes; custom secrets use authEnv |
Full YAML install entries and sfw lookup retry |
Yes | Yes | Yes |
| Windows bootstrap | Action runtime | PowerShell template | PowerShell branch |
Dependency and sfw caching |
Actions cache | .setup-vp-cached |
Cache@2 |
| Restore-only dependency cache | cache-save: false |
cache-policy: pull |
Not supported by Cache@2 |
| Version/cache-hit outputs | Step outputs | Shell variables/dotenv | Job variables/named task outputs |
When cache: true, prepare detects the lock file, resolves vp pm cache dir, and emits:
SETUP_VP_CACHE_READYSETUP_VP_CACHE_PATHSETUP_VP_LOCK_FILESETUP_VP_LOCK_TYPE
Cache@2 runs only when SETUP_VP_CACHE_READY=true. Missing lock files or cache paths log a warning and skip caching without failing setup.
The template also restores a separate version/platform-specific sfw cache before finalize. Azure Cache@2 automatically registers post-job saving and has no supported restore-only input. A cacheSave parameter would not be enforceable with this backend, so none is exposed. Azure pipeline caching
Finalize tasks are named <stepName>Unix and <stepName>Windows. Both publish version, a boolean cacheHit, nodeVersion, packageManager, and packageManagerVersion; the existing SETUP_VP_CACHE_HIT variable retains Azure's inexact value. The default prefix is setupVp.
nodeVersion now selects the managed runtime; bootstrapNodeVersion retains the former UseNode@1 role. The prepare phase records its actual Node executable so finalize does not depend on the selected project Node version.
Native Azure E2E provisioning and execution are deferred. Local runtime and template tests remain part of repository verification.
- Land the template, runtime, docs, and repository CI smoke coverage.
- Validate on real Azure Pipelines agents before release.
- After merge and tag, run one consumer pipeline using the public external-repository template plus matching immutable
setupRef.