> ## Documentation Index
> Fetch the complete documentation index at: https://glua.bluejutzu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing

> Cut a release, and set up publishing to the VS Code Marketplace and Open VSX.

Every release goes to GitHub Releases with the `.vsix` attached. Registry
publishing is layered on top and is opt-in — each registry is gated on its own
token, and the workflow skips one cleanly when its token is absent.

There are two registries, and they are independent:

|                                                 | Reaches                         | Needs               |
| ----------------------------------------------- | ------------------------------- | ------------------- |
| **[Open VSX](#open-vsx)**                       | Cursor, VSCodium, Gitpod, Theia | A GitHub account    |
| **[VS Code Marketplace](#vs-code-marketplace)** | VS Code                         | A Microsoft account |

<Tip>
  Cursor moved to Open VSX in June 2025, because Microsoft's terms restrict the
  VS Code Marketplace to Microsoft's own products. If you only publish to one,
  Open VSX is the one with no Microsoft dependency.
</Tip>

## Cutting a release

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
pnpm run release minor      # or patch, major, or an explicit 0.2.0
git push origin main --follow-tags
```

`release` bumps `packages/glua-lsp/package.json`, commits, and creates an
annotated `v<version>` tag. Pushing the tag runs the release workflow:
typecheck, test, build, package, GitHub release, then publish.

<Note>
  The workflow refuses to build when the tag and the manifest version disagree.
  That mismatch produces a release whose filename and contents contradict each
  other, and you only find out after the tag is public. The script exists so you
  cannot hit it by hand.
</Note>

A tag containing a hyphen (`v0.2.0-beta.1`) is published as a GitHub prerelease
and is **not** pushed to either marketplace.

## Open VSX

The registry Cursor, VSCodium, Gitpod and Theia install from. Free, and the only
account involved is GitHub.

<Steps>
  <Step title="Sign in and create a token">
    Sign in to [open-vsx.org](https://open-vsx.org) with GitHub, then
    **Settings → Access Tokens → Generate New Token**. Copy it now; it is not
    shown again.
  </Step>

  <Step title="Sign the publisher agreement">
    Open VSX requires the Eclipse Foundation Publisher Agreement before your
    first publish. There is a prompt in the UI, it is free, and it is a one-off.
  </Step>

  <Step title="Claim the namespace">
    The namespace must match the `publisher` field in the manifest.

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
    npx ovsx create-namespace bluejutzu --pat <token>
    ```
  </Step>

  <Step title="Add the token to GitHub">
    Repository **Settings → Secrets and variables → Actions → New repository
    secret**, named `OVSX_PAT`.
  </Step>
</Steps>

To publish by hand:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
pnpm run build
pnpm run package
npx ovsx publish packages/glua-lsp/glua-lsp-0.1.0.vsix --pat <token>
```

<Note>
  Open VSX namespaces are unverified by default, which shows as a small warning
  on the listing. You can request verification through the Eclipse Foundation
  once the extension is up, but it is not required to publish or install.
</Note>

## VS Code Marketplace

<Warning>
  **Azure DevOps is not Azure.** Publishing uses
  [dev.azure.com](https://dev.azure.com), which is free and does not ask for a
  payment method. `portal.azure.com` — the cloud platform that wants a card — is
  a different product and is not involved here.
</Warning>

<Steps>
  <Step title="Create an Azure DevOps organisation">
    Sign in at [dev.azure.com](https://dev.azure.com) with a Microsoft account.
    The organisation itself is only a container for the token; its name does not
    appear anywhere public.
  </Step>

  <Step title="Create a Personal Access Token">
    In Azure DevOps: **User settings → Personal access tokens → New Token**.

    * **Organization**: `All accessible organizations` — this matters, a
      single-org token will not work
    * **Scopes**: `Custom defined` → **Marketplace → Manage**
    * **Expiration**: as long as you are comfortable with; you will need to
      rotate it

    Copy the token now. It is not shown again.
  </Step>

  <Step title="Create the publisher">
    Go to the [Marketplace publisher page](https://marketplace.visualstudio.com/manage)
    and create a publisher. The **ID** is what goes in `package.json`, and it is
    public and permanent — renaming later means a new extension page and losing
    your installs.

    The manifest currently says:

    ```json packages/glua-lsp/package.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
    {
      "publisher": "bluejutzu"
    }
    ```

    Change it if you want a different ID, and make sure it matches the one you
    registered.
  </Step>

  <Step title="Add the token to GitHub">
    In the repository: **Settings → Secrets and variables → Actions → New
    repository secret**, named `VSCE_PAT`.
  </Step>
</Steps>

Tag a release and the workflow publishes automatically. To do it by hand:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
pnpm run build
pnpm run package
pnpm --filter glua-lsp exec vsce publish --no-dependencies --packagePath glua-lsp-0.1.0.vsix
```

## Before the first publish

A checklist:

* **Publisher ID** matches what you registered
* **Icon** is present at `packages/glua-lsp/resources/icon.png`. Regenerate with
  `pnpm run generate-icon` after changing the palette
* **README** in `packages/glua-lsp/` is what the listing shows, not the one at
  the repository root
* **LICENSE** is in the package, not just at the root
* `pnpm run package` reports no warnings

## What gets shipped

`.vscodeignore` keeps source, tests and tooling out. The published package is
around 920 KB, most of which is the bundled Garry's Mod API dataset. Check
before publishing:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-macchiato"}}
pnpm --filter glua-lsp package:ls
```

## Rotating a token

Both tokens expire. When one does, the publish step fails but the GitHub release
still succeeds — generate a new token, update the secret, and re-run the failed
job rather than cutting another release.


## Related topics

- [Install GLua Language Server for VS Code](/installation.md)