Skip to content

docs: use exact version tags instead of the moving v1 tag #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fengmk2 merged 4 commits into from
Aug 4, 2026
+78 −81
Merged

docs: use exact version tags instead of the moving v1 tag #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d25fc12
docs: recommend exact version tags, stop using the moving v1 tag
fengmk2 Aug 4, 2026
35e88bc
docs: track the release version in package.json
fengmk2 Aug 4, 2026
4dfec3f
docs: clarify the release example tags the next version
fengmk2 Aug 4, 2026
987589a
docs: use v1.15.0 to v1.16.0 in the release example
fengmk2 Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 77 additions & 80 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,35 @@ GitHub Action, GitLab CI/CD remote template, and Azure Pipelines step template t
- GitLab CI/CD support through a reusable `include:remote` template
- Azure Pipelines support through a reusable step template and compiled runtime

## Versioning

Reference this action with an exact release tag, or a commit SHA:

```yaml
- uses: voidzero-dev/setup-vp@v1.16.0
```

Releases are listed on the [tags page](https://github.com/voidzero-dev/setup-vp/tags). [Renovate](https://docs.renovatebot.com/) and Dependabot can keep a pinned tag up to date.

> [!WARNING]
> The moving major tag `v1` is frozen at `v1.15.0` and no longer updated. Workflows that use `voidzero-dev/setup-vp@v1` keep working but stay on v1.15.0 and will not receive new releases: switch them to an exact version tag. The same applies to the GitLab and Azure templates; use an exact tag in the `include:remote` URL / repository `ref` and in `setup-ref` / `setupRef`.

## Usage

### Basic Usage

```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
```

### With Node.js Version

```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
```
Expand All @@ -38,7 +51,7 @@ steps:
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version-file: ".node-version"
```
Expand All @@ -48,7 +61,7 @@ steps:
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
working-directory: web
node-version-file: ".nvmrc"
Expand All @@ -61,7 +74,7 @@ steps:
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
cache: true
Expand All @@ -73,7 +86,7 @@ steps:
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
version: "1.2.3"
node-version: "lts"
Expand All @@ -97,7 +110,7 @@ to `latest` only when nothing pins a resolvable version. So a project that pins
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
cache: true
```
Expand All @@ -110,7 +123,7 @@ worth watching for, since it means the pinned version was not applied:
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
version-file: package.json
cache: true
Expand Down Expand Up @@ -170,7 +183,7 @@ action warns and falls back to `latest`. (Auto-detection instead resolves a
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
cache: true
Expand All @@ -195,7 +208,7 @@ minimal:

steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
env:
Expand All @@ -212,7 +225,7 @@ read the repo `.npmrc` per its own config resolution):
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
registry-url: "https://npm.pkg.github.com"
Expand All @@ -230,7 +243,7 @@ Set `sfw: true` to wrap `vp install` with [Socket Firewall Free](https://docs.so
```yaml
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
sfw: true
run-install: true
Expand All @@ -251,7 +264,7 @@ steps:
- uses: socketdev/action@<sha>
with:
mode: firewall-free
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
sfw: true
run-install: true
Expand All @@ -275,7 +288,7 @@ jobs:
steps:
- run: apk add --no-cache bash curl gcompat libstdc++
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
```

### Matrix Testing with Multiple Node.js Versions
Expand All @@ -289,7 +302,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: ${{ matrix.node-version }}
cache: true
Expand Down Expand Up @@ -349,9 +362,13 @@ See [GitLab integration notes](rfcs/gitlab-integration.md) for the design backgr

### Basic GitLab Usage

Use an exact release tag in the `include:remote` URL, and pin `setup-ref` to the same tag so the bootstrap and compiled runtime are downloaded from the same version as the included template:

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

test:
extends: .setup-vp
Expand All @@ -364,8 +381,9 @@ test:

```yaml
include:
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.16.0/gitlab/setup-vp.yml"
inputs:
setup-ref: "v1.16.0"
version: "latest"
working-directory: "web"
run-install: "true"
Expand All @@ -377,37 +395,20 @@ test:
- vp run test
```

### With Pinned GitLab Runtime

When using an immutable tag or commit SHA, pin `setup-ref` to the same ref so the bootstrap and compiled runtime are downloaded from the same version as the included template:

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

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

### With Existing GitLab `before_script`

GitLab replaces array keywords such as `before_script` when a job uses `extends`; it does not append them. If the job already needs setup commands, reference `.setup-vp-bootstrap` explicitly before the job-specific commands and configure setup-vp with variables:

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

test:
image: node:24
variables:
SETUP_VP_VERSION: "latest"
SETUP_VP_RUN_INSTALL: "true"
SETUP_VP_SETUP_REF: "v1"
SETUP_VP_SETUP_REF: "v1.16.0"
before_script:
- !reference [.setup-vp-bootstrap, before_script]
- npm config set //registry.example.com/:_authToken "$NODE_AUTH_TOKEN"
Expand All @@ -422,8 +423,9 @@ Use the same pattern when the project has `default:before_script`; put the share

```yaml
include:
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.16.0/gitlab/setup-vp.yml"
inputs:
setup-ref: "v1.16.0"
run-install: |
- cwd: ./packages/app
args: ['--frozen-lockfile']
Expand All @@ -440,8 +442,9 @@ test:

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

Expand All @@ -458,8 +461,9 @@ Pass `NODE_AUTH_TOKEN` as a GitLab CI/CD variable and set `registry-url` when th

```yaml
include:
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1/gitlab/setup-vp.yml"
- remote: "https://raw.githubusercontent.com/voidzero-dev/setup-vp/v1.16.0/gitlab/setup-vp.yml"
inputs:
setup-ref: "v1.16.0"
registry-url: "https://npm.pkg.github.com"
scope: "@myorg"

Expand All @@ -474,20 +478,20 @@ test:

### GitLab Inputs

| Input | Description | Default |
| ------------------- | --------------------------------------------------------------------------------------------------------- | -------- |
| `version` | Version of Vite+ to install | `latest` |
| `working-directory` | Project directory used for relative paths and default `vp install` execution | `.` |
| `run-install` | String input for `vp install` after setup. Use `"true"`/`"false"` or a YAML object/list with `cwd`/`args` | `true` |
| `sfw` | Wrap `vp install` with [Socket Firewall Free](https://docs.socket.dev/docs/socket-firewall-free) | `false` |
| `registry-url` | Optional registry URL to write to a temporary `.npmrc` | |
| `scope` | Optional scope for authenticating against scoped registries | |
| `setup-ref` | setup-vp ref used to download the GitLab bootstrap and compiled runtime | `v1` |
| Input | Description | Default |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `version` | Version of Vite+ to install | `latest` |
| `working-directory` | Project directory used for relative paths and default `vp install` execution | `.` |
| `run-install` | String input for `vp install` after setup. Use `"true"`/`"false"` or a YAML object/list with `cwd`/`args` | `true` |
| `sfw` | Wrap `vp install` with [Socket Firewall Free](https://docs.socket.dev/docs/socket-firewall-free) | `false` |
| `registry-url` | Optional registry URL to write to a temporary `.npmrc` | |
| `scope` | Optional scope for authenticating against scoped registries | |
| `setup-ref` | setup-vp ref used to download the GitLab bootstrap and compiled runtime. Always set it to the same tag as the remote URL; the default `v1` is frozen at v1.15.0 | `v1` |

### GitLab Notes

- Use a tag such as `v1` or `v1.0.0` in the remote URL instead of `main`.
- Pin `setup-ref` to the same tag or commit SHA as the remote URL when strict reproducibility is required.
- Use an exact release tag such as `v1.16.0` in the remote URL. Do not use `main` (mutable) or `v1` (frozen at v1.15.0, no longer updated).
- Always pin `setup-ref` to the same tag or commit SHA as the remote URL, so the compiled runtime matches the included template.
- Quote GitLab string inputs such as `run-install: "false"`; unquoted booleans are rejected by GitLab before the setup runtime can parse them.
- GitLab 17.9+ users can add `integrity` to pin the remote file hash.
- The template expects a Unix-like runner image with Node.js, `bash`, and either `curl` or `wget`.
Expand All @@ -512,7 +516,7 @@ resources:
type: github
endpoint: github
name: voidzero-dev/setup-vp
ref: refs/tags/v1
ref: refs/tags/v1.16.0

pool:
vmImage: ubuntu-latest
Expand All @@ -530,22 +534,22 @@ steps:
- script: vp run test
```

Pin `ref` and `setupRef` to the same tag or commit SHA for strict reproducibility. The moving `v1` tag is supported for convenience but is not immutable.
Pin `ref` and `setupRef` to the same exact tag or commit SHA. Do not use the `v1` tag: it is frozen at v1.15.0 and no longer updated.

### Azure Parameters

| Parameter | Default | Description |
| --------------------- | -------- | ------------------------------------------------------------------------- |
| `version` | `latest` | Vite+ version/dist-tag passed to the official installer. |
| `workingDirectory` | `.` | Project directory for lock detection and default `vp install`. |
| `runInstall` | `true` | Run `vp install`; accepts boolean or object/list with `cwd` and `args`. |
| `sfw` | `false` | Wrap `vp install` with Socket Firewall Free. |
| `registryUrl` | | Optional registry URL for a temporary `.npmrc`. |
| `scope` | | Optional npm registry scope. |
| `setupRef` | `v1` | Ref used to download bootstrap scripts and `dist/azure/index.mjs`. |
| `nodeVersion` | `24.x` | Passed to `UseNode@1`; an empty string skips Node setup. |
| `cache` | `false` | Enable Azure `Cache@2` around the package-manager cache directory. |
| `cacheDependencyPath` | | Explicit lock file relative to `workingDirectory`; otherwise auto-detect. |
| Parameter | Default | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `latest` | Vite+ version/dist-tag passed to the official installer. |
| `workingDirectory` | `.` | Project directory for lock detection and default `vp install`. |
| `runInstall` | `true` | Run `vp install`; accepts boolean or object/list with `cwd` and `args`. |
| `sfw` | `false` | Wrap `vp install` with Socket Firewall Free. |
| `registryUrl` | | Optional registry URL for a temporary `.npmrc`. |
| `scope` | | Optional npm registry scope. |
| `setupRef` | `v1` | Ref used to download bootstrap scripts and `dist/azure/index.mjs`. Always set it to the same tag as `ref`; the default `v1` is frozen at v1.15.0. |
| `nodeVersion` | `24.x` | Passed to `UseNode@1`; an empty string skips Node setup. |
| `cache` | `false` | Enable Azure `Cache@2` around the package-manager cache directory. |
| `cacheDependencyPath` | | Explicit lock file relative to `workingDirectory`; otherwise auto-detect. |

### Azure Job Variables

Expand Down Expand Up @@ -580,7 +584,7 @@ jobs:
steps:
- uses: actions/checkout@v6

- uses: voidzero-dev/setup-vp@v1
- uses: voidzero-dev/setup-vp@v1.16.0
with:
node-version: "lts"
cache: true
Expand Down Expand Up @@ -624,34 +628,27 @@ vp install

### Releasing

Releases are published as git tags (there is no npm package, so `package.json` stays at `1.0.0`). Consumers reference the moving major tag `voidzero-dev/setup-vp@v1` (or pin a commit SHA), so every release also moves `v1` forward to the new commit.
Releases are published as git tags; there is no npm package, but the `package.json` version tracks the latest release. Consumers pin an exact version tag such as `voidzero-dev/setup-vp@v1.16.0` or a commit SHA. The `v1` major tag is frozen at v1.15.0 and is never moved (an org-level ruleset rejects tag force-pushes).

To cut a release:

After the changes are merged to `main`:
1. Open and merge a PR that bumps the `version` in `package.json` and the version tag in the README examples to the upcoming release.

1. Update `main` and confirm `dist/index.mjs` is in sync (the working tree must stay clean after building):
2. Update `main` and confirm `dist/index.mjs` is in sync (the working tree must stay clean after building):

```bash
git checkout main && git pull --ff-only
vp run build
git status --short # must be empty
```

2. Create the new annotated version tag (bump the minor from the latest `v1.x.0`) on the merged commit, then move the `v1` major tag to the same commit:
3. Create the new annotated version tag, bumping the minor from the latest release, and push it. For example, with `v1.15.0` as the latest release, the next tag is `v1.16.0`:

```bash
git tag -a v1.13.0 -m "v1.13.0"
git tag -fa v1 -m "v1"
git tag -a v1.16.0 -m "v1.16.0"
git push origin v1.16.0
```

3. Push the new version tag, then force-push the moved `v1` tag:

```bash
git push origin v1.13.0
git push origin v1 --force
```

Both are annotated tags whose message is the tag name. `v1` always points at the latest `v1.x.0` release, so `@v1` consumers pick it up automatically.

## Feedback

If you have any feedback or issues, please [submit an issue](https://github.com/voidzero-dev/setup-vp/issues).
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "setup-vp",
"version": "1.0.0",
"version": "1.16.0",
"private": true,
"type": "module",
"scripts": {
Expand Down
Loading