Skip to content

distribution.md

Latest commit

 

History

History
207 lines (143 loc) · 9.38 KB

distribution.md

File metadata and controls

207 lines (143 loc) · 9.38 KB
Raw

Distribution Guide

This project ships through several channels, but they do not all work the same way.

What is already automated

When a release is cut from main, the GitHub Actions release workflow will:

  • publish the npm package
  • attach cross-platform binaries to the GitHub release
  • push the Docker image to ghcr.io/robbeverhelst/tsarr
  • render the packaging files in the release job workspace
  • update the Homebrew tap if DIST_REPO_TOKEN is configured
  • update the Scoop bucket if DIST_REPO_TOKEN is configured
  • update the AUR package if AUR_SSH_PRIVATE_KEY is configured
  • publish the Chocolatey package if CHOCOLATEY_API_KEY is configured

That means Homebrew, Scoop, AUR, and Chocolatey can all run from CI once their one-time credentials are in place. nixpkgs submission is still manual.

1Password-backed CI secrets

This repo reads release-channel credentials from 1Password when OP_SERVICE_ACCOUNT_TOKEN is available to GitHub Actions.

Current 1Password items:

  • op://Tsarr/clawhub/api-token
  • op://Tsarr/tsarr-release-ci/dist-repo-token
  • op://Tsarr/tsarr-release-ci/ci/chocolatey-api-key
  • op://Tsarr/tsarr-aur-ed25519-v2/private key
  • op://Tsarr/tsarr-aur-ed25519-v2/public key

Current secret references:

  • op://Tsarr/clawhub/api-token
  • op://Tsarr/tsarr-release-ci/dist-repo-token
  • op://Tsarr/tsarr-release-ci/ci/chocolatey-api-key
  • op://Tsarr/tsarr-aur-ed25519-v2/private key
  • op://Tsarr/tsarr-aur-ed25519-v2/public key

The Linux release job uses the official 1Password GitHub Action. The Windows Chocolatey job uses op read directly because the official action does not support Windows runners.

Generate the channel manifests

The files under packaging/ are generated from the release binaries. Before you submit anything to AUR, Scoop, Chocolatey, or Nix, generate the versioned manifests with the current release number and binary checksums.

Use the same sequence as the release workflow on the release commit:

bun install --frozen-lockfile
bun run generate
bun run generate:types
bun run build:js
bun run build:cli
bun run build:types

mkdir -p release-assets/binaries
bun build src/cli/index.ts --compile --target=bun-linux-x64 --outfile release-assets/binaries/tsarr-linux-x64
bun build src/cli/index.ts --compile --target=bun-linux-arm64 --outfile release-assets/binaries/tsarr-linux-arm64
bun build src/cli/index.ts --compile --target=bun-darwin-x64 --outfile release-assets/binaries/tsarr-darwin-x64
bun build src/cli/index.ts --compile --target=bun-darwin-arm64 --outfile release-assets/binaries/tsarr-darwin-arm64
bun build src/cli/index.ts --compile --target=bun-windows-x64 --outfile release-assets/binaries/tsarr-windows-x64.exe

bun run update-packaging <released-version>

After that, the files in packaging/ will contain the actual version and SHA256 values you should submit. The release workflow also commits the generated Nix flake back to main so the repo-hosted flake stays installable.

Channel checklist

Channel End-user install External account/repo needed Fully automated from this repo
npm npm install -g tsarr npm account + NPM_TOKEN secret Yes
GitHub Releases Download binary asset GitHub repo Yes
Docker docker run --rm ghcr.io/robbeverhelst/tsarr doctor GitHub repo / GHCR Yes
ClawHub openclaw clawhub install tsarr or clawhub install tsarr ClawHub account + token stored at op://Tsarr/clawhub/api-token Yes
Homebrew brew install robbeverhelst/tsarr/tsarr GitHub tap repo Yes
Scoop scoop bucket add tsarr https://github.com/robbeverhelst/scoop-tsarr then scoop install tsarr GitHub bucket repo or upstream Scoop PR Yes, if you use the repo-owned bucket
Chocolatey choco install tsarr Chocolatey account + API key Yes, after the Tsarr/tsarr-release-ci chocolatey-api-key field is populated and OP_SERVICE_ACCOUNT_TOKEN is available
AUR yay -S tsarr-bin AUR account + SSH key Yes, using Tsarr/tsarr-aur-ed25519-v2, once OP_SERVICE_ACCOUNT_TOKEN is available
Nix nix profile install github:robbeverhelst/tsarr?dir=packaging/nix None for the repo flake, GitHub + nixpkgs PR for nixpkgs inclusion Repo flake: yes. nixpkgs: no

What to do next

With the GitHub repos and 1Password items in place, the remaining practical order is:

  1. Add the ClawHub API token to op://Tsarr/clawhub/api-token.
  2. Make sure the Tsarr/tsarr-aur-ed25519-v2 public key is the one registered in your AUR account profile.
  3. Add your Chocolatey API key to op://Tsarr/tsarr-release-ci/ci/chocolatey-api-key.
  4. Make sure OP_SERVICE_ACCOUNT_TOKEN is available to this repo in GitHub Actions.
  5. Let the next release and skill sync publish ClawHub, Homebrew, Scoop, AUR, and Chocolatey automatically.
  6. Open a nixpkgs PR if you want tsarr available from the shared Nix package collection.

Manual inputs still required

These are the only pieces CI cannot create by itself:

  • ClawHub API token: add it to op://Tsarr/clawhub/api-token for non-interactive clawhub login --token.
  • AUR account settings: make sure the Tsarr/tsarr-aur-ed25519-v2 public key is registered in your AUR profile.
  • Chocolatey API key: add it to the tsarr-release-ci item in 1Password.
  • GitHub Actions service-account access: OP_SERVICE_ACCOUNT_TOKEN must be available to this repo.
  • nixpkgs merge: upstream review is manual even if you script PR creation.

ClawHub

The OpenClaw skill lives in skills/tsarr/.

Automation behavior:

  • PRs that touch the skill run a local structure/frontmatter validation workflow for skills/tsarr/.
  • Pushes to main that touch the skill run clawhub sync --all --bump patch to publish or update the tsarr skill on ClawHub.
  • The workflow requires OP_SERVICE_ACCOUNT_TOKEN, loads op://Tsarr/clawhub/api-token through 1Password, and logs in non-interactively with clawhub login --token.

End-user install commands:

openclaw clawhub install tsarr
# or
clawhub install tsarr

Homebrew

Homebrew uses a tap repo, not this main repo directly.

The required repo is robbeverhelst/homebrew-tsarr.

After the 1Password item and OP_SERVICE_ACCOUNT_TOKEN are available, the release workflow copies the updated formula into the tap and pushes it automatically on every release.

AUR

The AUR package name for this repo is tsarr-bin, because it installs the prebuilt binary from GitHub Releases.

One-time setup:

  1. Confirm tsarr-bin is available as a package name on AUR.
  2. Make sure the AUR profile uses op://Tsarr/tsarr-aur-ed25519-v2/public key.
  3. Clone the package repo if you want to seed it manually the first time:
git clone ssh://aur@aur.archlinux.org/tsarr-bin.git
cd tsarr-bin
  1. Copy the generated packaging/aur/PKGBUILD and generated packaging/aur/.SRCINFO into that repo.
  2. Add the maintainer comment expected by AUR before the first push.
  3. Commit and push:
git add PKGBUILD .SRCINFO
git commit -m "Initial import"
git push

After the CI key is installed, later releases update the AUR Git repo automatically.

Chocolatey

Chocolatey uses a .nupkg built from packaging/chocolatey/.

One-time setup:

  1. Sign in to Chocolatey and create an API key.
  2. Add that key to op://Tsarr/tsarr-release-ci/ci/chocolatey-api-key.

After that, the release workflow builds the generated package on windows-latest, loads the API key with op read, and pushes it automatically. The first submission will still go through Chocolatey moderation.

Scoop

Scoop needs a bucket repo or a PR to an existing bucket.

You have two reasonable options:

  • Use the repo-owned bucket at robbeverhelst/scoop-tsarr, which CI now updates automatically.
  • Submit the generated manifest to an existing Scoop bucket if you want wider discovery, but that upstream path is still manual.

If you use your own bucket, users install with:

scoop bucket add tsarr https://github.com/robbeverhelst/scoop-tsarr
scoop install tsarr

For the repo-owned bucket, CI keeps the manifest current automatically.

Nix

There are two different Nix paths here:

  • packaging/nix/flake.nix is the repo-hosted flake users can install directly.
  • nixpkgs inclusion is a separate upstream contribution and is not automated by this repo.

The release workflow regenerates the repo flake from the published release binaries and commits it back to main, so the checked-in flake stays aligned with the latest release.

If you want shared nixpkgs availability, use the package definition here as a starting point and open a PR to NixOS/nixpkgs. Expect that to be the slowest review path of the distribution channels.

Repo files involved