Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
17 changes: 6 additions & 11 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,10 @@ name: Publish
# the tag with SHA256SUMS signed by this workflow and pushed with them to the public package
# ghcr.io/spin-stack/vscode-spinbox-release, which `spin vscode install` reads while this
# repository's releases are a 404 to it (job release), then published to the Visual
# Studio Marketplace and to Open VSX (job publish), as a pre-release when the tag holds -pre. The
# release comes first and on its own: it exists, and is installable, whether or not a registry is
# set up yet or answers. Both registries trust this workflow in the publish environment by OIDC
# (docs/publishing.md), so no token is kept: the Marketplace retires personal access tokens on
# 2026-12-01. OVSX_PAT is only for Open VSX's first publish, before its trusted publisher can be
# registered; once it is, the secret is deleted and ovsx exchanges the job's ID token instead.
# Studio Marketplace (job publish), as a pre-release when the tag holds -pre. The release comes
# first and on its own: it exists, and is installable, whether or not the Marketplace is set up
# yet or answers. The Marketplace trusts this workflow in the publish environment by OIDC
# (docs/publishing.md), so no token is kept: it retires personal access tokens on 2026-12-01.

on:
push:
Expand Down Expand Up @@ -64,7 +62,7 @@ jobs:
- run: go tool task publish:ghcr
env:
GH_TOKEN: ${{ github.token }}
# The registries publish these very bytes, the ones SHA256SUMS lists, not a second package.
# The Marketplace publishes these very bytes, the ones SHA256SUMS lists, not a second package.
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: spinbox-vsix
Expand All @@ -79,7 +77,7 @@ jobs:
environment: publish
permissions:
contents: read
# The token each registry exchanges for a short-lived publishing credential.
# The token the Marketplace exchanges for a short-lived publishing credential.
id-token: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Expand All @@ -98,6 +96,3 @@ jobs:
with:
name: spinbox-vsix
- run: go tool task publish:marketplace
- run: go tool task publish:openvsx
env:
OVSX_PAT: ${{ secrets.OVSX_PAT }}
17 changes: 8 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +52,16 @@ A tag `v*` pushed to this repository runs `.github/workflows/publish.yml`. It pa
platform once (`task package:all`), makes the tag's GitHub release (`task publish:github`),
pushes the same files to the public package `ghcr.io/spin-stack/vscode-spinbox-release`
(`task publish:ghcr`), and then publishes the same VSIXs to the Visual Studio Marketplace
(`vsce`) and to Open VSX (`ovsx`). The tag is `v` followed by `package.json`'s `version`.
(`vsce`). The tag is `v` followed by `package.json`'s `version`.

Nobody pushes that tag for a release. A push to main that changes `package.json` runs
`.github/workflows/tag.yml` (`task release:tag`): when no tag has the version it holds, it tags
that commit `v<version>`, or `v<version>-pre` for an odd minor (the Marketplace's convention for a
pre-release), as the release app, since a tag pushed with the run's own token would start no
workflow. So merging a bump releases it, and so does merging a version set by hand. The tag workflow needs `RELEASE_APP_KEY` too.

The GitHub release comes first, in a job of its own, so it exists whether or not a registry is set
up or answers. It holds:
The GitHub release comes first, in a job of its own, so it exists whether or not the Marketplace is
set up or answers. It holds:

| File | What |
|---|---|
Expand Down Expand Up @@ -89,7 +89,7 @@ a tag moved to another artifact can only point at another release this workflow
release notes say, and then `code --install-extension spinbox-<target>.vsix`.

The package is made private by its first push, and nothing installs from it until someone makes
it public, once: [docs/publishing.md](docs/publishing.md#6-ghcr-make-the-package-public).
it public, once: [docs/publishing.md](docs/publishing.md#4-ghcr-make-the-package-public).

A tag with `-pre` after it (`v0.3.0-pre`) publishes that version as a pre-release: the Marketplace takes no semver
pre-release versions, and its convention is an odd minor for pre-releases.
Expand All @@ -98,9 +98,8 @@ pre-release versions, and its convention is an odd minor for pre-releases.
git tag v0.3.0-pre && git push origin v0.3.0-pre # package.json says "version": "0.3.0"
```

Both registries trust the workflow by OIDC in the GitHub environment `publish`, so it keeps no
token. A run that failed halfway is run again whole: both registries skip a version they already
have.
The Marketplace trusts the workflow by OIDC in the GitHub environment `publish`, so it keeps no
token. A run that failed halfway is run again whole: the Marketplace skips a version it already
has.

How to create the two accounts, the publisher and the namespace, and the order to do it in, is
[docs/publishing.md](docs/publishing.md).
How to create the publisher, and the order to do it in, is [docs/publishing.md](docs/publishing.md).
8 changes: 3 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,9 @@ one in a new window, without leaving the editor.

## Requirements

- VS Code 1.146 or newer, or an editor built on it that installs from Open VSX (VSCodium,
Cursor, ...).
- A Remote-SSH extension: Microsoft's `ms-vscode-remote.remote-ssh` in VS Code, or
`jeanp413.open-remote-ssh` elsewhere. When none is installed, Spinbox offers to install the one
your editor's marketplace carries.
- Microsoft VS Code 1.146 or newer.
- Microsoft's Remote-SSH, `ms-vscode-remote.remote-ssh`. When it is not installed, Spinbox offers
to install it.
- A Spinbox account, with an SSH key of this machine added to it. If none is, Spinbox says so and
offers to add one.

Expand Down
13 changes: 3 additions & 10 deletions Taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,13 @@ tasks:
rm -rf bin

publish:
desc: Package every platform, attach each VSIX to the tag's GitHub release, and publish each to the Visual Studio Marketplace and to Open VSX - what the Publish workflow runs on a tag v*, step by step. It authenticates by the workflow's OIDC token (docs/publishing.md), so it runs only in that workflow.
desc: Package every platform, attach each VSIX to the tag's GitHub release, and publish each to the Visual Studio Marketplace - what the Publish workflow runs on a tag v*, step by step. It authenticates by the workflow's OIDC token (docs/publishing.md), so it runs only in that workflow.
cmds:
- task: publish:check
- task: package:all
- task: publish:github
- task: publish:ghcr
- task: publish:marketplace
- task: publish:openvsx

publish:github:
desc: >-
Expand Down Expand Up @@ -148,7 +147,7 @@ tasks:
TAG: '{{.TAG}}'
silent: true
cmds:
# Without id-token: write, or outside Actions, both registries would only say they refused.
# Without id-token: write, or outside Actions, the Marketplace would only say it refused.
- cmd: |
if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
echo "publish: no OIDC token: it runs in the Publish workflow, whose job has id-token: write (docs/publishing.md)" >&2
Expand All @@ -164,15 +163,9 @@ tasks:
publish:marketplace:
desc: Publish every VSIX in the repository's root to the Visual Studio Marketplace, as the publisher's trusted publishing policy for this workflow.
cmds:
# --skip-duplicate: a run that failed on Open VSX is run again whole, and what the Marketplace already has is no error.
# --skip-duplicate: a run that failed after it is run again whole, and what the Marketplace already has is no error.
- pnpm exec vsce publish --oidc --skip-duplicate {{.PRE_RELEASE}} --packagePath *.vsix

publish:openvsx:
desc: Publish every VSIX in the repository's root to Open VSX - with OVSX_PAT for the first publish, by the namespace's trusted publisher once one is registered.
cmds:
# With no OVSX_PAT, ovsx exchanges the job's ID token itself (trusted publishing).
- pnpm exec ovsx publish --skip-duplicate {{.PRE_RELEASE}} --packagePath *.vsix

spin:newer:
desc: Whether GIVEN, a spin release, is newer than versions.yaml's spin, as release=<it or nothing> - the Bump spin workflow's first step (versions newer).
cmds:
Expand Down
102 changes: 18 additions & 84 deletions docs/publishing.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,25 @@
# Publishing: the accounts, once

Spinbox is published to two registries: the **Visual Studio Marketplace**, which VS Code reads, and
**Open VSX**, which VSCodium, Cursor and other editors read. Both trust this repository's Publish
workflow by OIDC (*trusted publishing*), so no token is kept in GitHub.

The Marketplace retires personal access tokens on **2026-12-01**. Open VSX needs one token only for
the very first publish, because it registers a trusted publisher only for an extension that already
exists.
Spinbox is published to the **Visual Studio Marketplace**, which VS Code reads. It trusts this
repository's Publish workflow by OIDC (*trusted publishing*), so no token is kept in GitHub. The
Marketplace retires personal access tokens on **2026-12-01**.

What a person does, once, in this order:

| # | Where | What | Takes |
|---|---|---|---|
| 1 | GitHub | The `publish` environment in this repository | 2 min |
| 2 | Visual Studio Marketplace | The publisher `spin-stack`, and its trusted publishing policy | 10 min |
| 3 | Open VSX | An Eclipse account, the Publisher Agreement, the namespace `spin-stack`, a token | 15 min |
| 4 | Here | The first release, a pre-release | 15 min |
| 5 | Open VSX | Claim the namespace and register the trusted publisher; delete the token | days (a person at Eclipse reviews the claim) |
| 6 | GitHub | Make the package `vscode-spinbox-release` public, after the first release pushed it | 2 min |
| 3 | Here | The first release, a pre-release | 15 min |
| 4 | GitHub | Make the package `vscode-spinbox-release` public, after the first release pushed it | 2 min |

## 1. GitHub: the `publish` environment

1. In this repository, open **Settings → Environments → New environment**, and name it `publish`.
2. Under **Deployment branches and tags**, choose **Selected branches and tags**, then **Add
deployment branch or tag rule**, with *Ref type* **Tag** and the pattern `v*`.
- Only a tag `v*` can run in it.
- Both registries' policies name this environment, so no other ref can publish.
- The Marketplace's policy names this environment, so no other ref can publish.
3. Optional: add yourself under **Required reviewers**, so a person approves each publish.

## 2. Visual Studio Marketplace
Expand Down Expand Up @@ -58,34 +52,7 @@ organization when publishing is by trusted publishing.
Later, once the publisher has had an extension listed for 6 months, it can verify the domain
(publisher → **Details → Verified domain**, a DNS TXT record). Nothing needs it now.

## 3. Open VSX

You need the GitHub account you will log in to open-vsx.org with.

1. **Create an Eclipse account** at <https://accounts.eclipse.org/user/register>.
- Fill in the **GitHub Username** field with exactly that GitHub account.
- Open VSX matches the two accounts by this field.
2. **Log in to <https://open-vsx.org>** with that GitHub account: the account icon, top right.
3. **Sign the Publisher Agreement.**
1. Open the avatar menu → **Settings**, then select **Log in with Eclipse** and authorize.
2. Select **Show Publisher Agreement**, read it to the end, and select **Agree**.
4. **Create a token for the first publish.**
1. Open **Settings → Access Tokens** (<https://open-vsx.org/user-settings/tokens>) and select
**Generate New Token**.
2. Describe it `vscode-spinbox first publish`, then select **Generate Token**.
3. Copy it now: it is shown once.
5. **Create the namespace** with that token. Its name must match `publisher` in `package.json`,
including case:

```sh
pnpm exec ovsx create-namespace spin-stack -p <token>
```

6. **Hand the token to the first publish.**
1. In this repository, open **Settings → Environments → publish → Add environment secret**.
2. Name it `OVSX_PAT` and paste the token as its value.

## 4. The first release
## 3. The first release

1. **Make sure the VSIX carries a current CLI.** `versions.yaml`'s `spin` entry names a spin
release that has the four CLIs (linux-amd64, linux-arm64, darwin-amd64, darwin-arm64).
Expand All @@ -105,52 +72,22 @@ You need the GitHub account you will log in to open-vsx.org with.

3. **Watch the run.** Actions → **Publish**, approving it if you set a reviewer.
- Its first job, **GitHub release**, needs no account: it attaches the VSIXs, `SHA256SUMS` and
their signature to the tag's release before either registry is asked, so the release is
there to install from even when a registry refuses. The same job pushes those files to
`ghcr.io/spin-stack/vscode-spinbox-release`, which the first push creates private (step 6).
- A run that fails halfway is run again whole: both registries skip a version they already
have.
their signature to the tag's release before the Marketplace is asked, so the release is
there to install from even when the Marketplace refuses. The same job pushes those files to
`ghcr.io/spin-stack/vscode-spinbox-release`, which the first push creates private (step 4).
- A run that fails halfway is run again whole: the Marketplace skips a version it already
has.
- Its first step fails, saying why, if the job has no OIDC token.
- Each registry refuses with its own message if the publisher, namespace or policy is not set
up.
4. **Check both listings.**
- <https://marketplace.visualstudio.com/items?itemName=spin-stack.spinbox>
- <https://open-vsx.org/extension/spin-stack/spinbox>

## 5. Open VSX: from a token to trusted publishing

1. **Claim the namespace.**
1. Open an issue at <https://github.com/EclipseFdn/open-vsx.org/issues/new/choose> asking to
own `spin-stack`.
2. Once granted, the namespace is *verified*.
3. Add other people in **Settings → Namespaces**: an *Owner* manages members, a *Contributor*
only publishes.

A trusted publisher needs an owner; a contributor is not enough.
2. **Register the trusted publisher.**
1. Open **Settings → Trusted Publishers**
(<https://open-vsx.org/user-settings/trusted-publishers>) and select the namespace
`spin-stack`.
2. Select the GitHub provider and fill in:

| Field | Value |
|---|---|
| Organization or User name | `spin-stack` |
| Repository name | `vscode-spinbox` |
| Workflow filename | `publish.yml` |
| Environment name | `publish` |

3. If the dialog offers no GitHub provider, keep the token and look again later.
3. **Drop the token.** Delete the environment secret `OVSX_PAT`, and revoke the token in
**Settings → Access Tokens**. With no token, `ovsx` exchanges the job's ID token by itself.
- The Marketplace refuses with its own message if the publisher or policy is not set up.
4. **Check the listing:** <https://marketplace.visualstudio.com/items?itemName=spin-stack.spinbox>

## 6. ghcr: make the package public
## 4. ghcr: make the package public

`spin vscode install` pulls the extension anonymously from
`ghcr.io/spin-stack/vscode-spinbox-release`. GitHub creates a package private on its first push,
and a package linked to a repository takes that repository's access permissions but not its
visibility; nor is there a REST endpoint that changes it. So, once, after
the first run of Publish has pushed the package (step 4):
the first run of Publish has pushed the package (step 3):

1. You need the admin role on the package: an owner of `spin-stack` has it on every package of the
organization.
Expand All @@ -170,16 +107,13 @@ the first run of Publish has pushed the package (step 4):

answers `{"token":...}`; while the package is private it answers `DENIED`.

A public package cannot be made private again. That is what is wanted: everything in it is in
the public registries too, and what the CLI trusts is the signature, not the package.
A public package cannot be made private again. That is what is wanted: everything in it is on
the Marketplace too, and what the CLI trusts is the signature, not the package.

While the package is private, or before the first push, `spin vscode install` fails with
`no_extension_release`, saying the package is missing or not public.

## Sources

- [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension), VS Code: the publisher, trusted publishing, the PAT retirement, platform-specific and pre-release versions.
- [Publishing Extensions](https://github.com/eclipse/openvsx/wiki/Publishing-Extensions), Open VSX wiki: the Eclipse account, the agreement, tokens, `create-namespace`.
- [Namespace Access](https://github.com/eclipse/openvsx/wiki/Namespace-Access), Open VSX wiki: claiming a namespace, members.
- [Trusted Publishing](https://github.com/eclipse-openvsx/openvsx/wiki/Trusted-Publishing), Open VSX wiki: the trusted publisher, private repositories.
- [Configuring a package's access control and visibility](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility), GitHub: private on first publish, visibility not inherited, who may change it, public cannot go back.
2 changes: 1 addition & 1 deletion hack/spinpropose/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ func body(release, run, version, tag string, targets []string) string {
"Left to whoever merges it, as versions.yaml's note says: the CLI's contract against `src/cli/contract.ts`, " +
"and the extension tried against an installation of " + release + ".\n\n" +
"Merging it releases the extension as " + version + ": `.github/workflows/tag.yml` tags main `" + tag + "`, " +
"and that tag publishes it to the GitHub release, ghcr, the Marketplace and Open VSX.\n\n" +
"and that tag publishes it to the GitHub release, ghcr and the Marketplace.\n\n" +
"spin-stack/shipset dispatches this for each spin release (`.github/workflows/bump-spin.yml`); " +
"a newer one rewrites this branch and this pull request, commits added here included.\n"
}
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -221,7 +221,6 @@
"@vscode/test-electron": "3.1.0",
"@vscode/vsce": "4.1.0",
"esbuild": "0.28.2",
"ovsx": "1.3.0",
"typescript": "7.0.2",
"vitest": "5.0.5"
}
Expand Down
Loading
Loading