Skip to content

Latest commit

 

History

History
133 lines (109 loc) · 7.18 KB

RELEASING.md

File metadata and controls

133 lines (109 loc) · 7.18 KB

Releasing

The Claude Code version lock

The plugin never trusts a version string it did not verify. release/claude-code.lock is the single source of truth for which Claude Code build the .plg installs:

CLAUDE_VERSION=2.1.308
CLAUDE_PLATFORM=linux-x64
CLAUDE_SHA256=<sha256 of the linux-x64 binary, from the signed manifest>
CLAUDE_URL=https://downloads.claude.ai/claude-code-releases/2.1.308/linux-x64/claude
CLAUDE_SIZE=292232560
MANIFEST_SHA256=<sha256 of manifest.json as verified>
VERIFIED_AT=<UTC timestamp>

scripts/claude-release produces it:

  1. resolve --channel stable reads https://downloads.claude.ai/claude-code-releases/stable.
  2. verify --version X downloads X/manifest.json and X/manifest.json.sig, imports keys/claude-code.asc into a throwaway GNUPGHOME, requires that the key's fingerprint is exactly 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE, runs gpg --verify and accepts only a VALIDSIG status line made by that key. Only then does it read platforms["linux-x64"].checksum and .size from the manifest. With --download it also fetches the binary and compares its sha256 and size.
  3. lock --version X [--download] writes the lock file.

Run it through the dev image so that the same gpg, curl and php are used everywhere:

./scripts/dev-env scripts/claude-release lock --version "$(./scripts/dev-env scripts/claude-release resolve --channel stable)" --download

The pinned fingerprint and the base URL are constants in the script. The only overrides are for the offline test suite and are accepted solely with CLAUDE_RELEASE_TEST_MODE=1, with a key file that lives under tests/.

release/tmux.lock pins the Slackware 15.0 tmux package the same way (URL, sha256, size). It was verified by hand against the Slackware signing key (see docs/SPIKE.md, section 12) and only changes with a new manual verification.

Automatic bump proposals

.github/workflows/claude-bump.yml runs daily. When the stable channel is newer than the lock, it runs lock --download, pushes a claude-bump/<version> branch and opens a pull request titled claude-code: OLD → NEW whose body carries the verification output. It never pushes to main. A maintainer reviews the diff (one lock file) and merges; a plugin release is a separate, tagged step.

The pull request is opened with the default GITHUB_TOKEN, which GitHub refuses (GitHub Actions is not permitted to create or approve pull requests) until "Allow GitHub Actions to create and approve pull requests" is enabled under Settings, Actions, General, Workflow permissions. It is off for a new repository; this turns it on:

gh api -X PUT repos/tabilzad/claude-code-unraid/actions/permissions/workflow \
  -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true

The workflow labels the PR claude-code-bump when that label exists. CI on a pull request opened with the default GITHUB_TOKEN is held until a maintainer approves it ("Approve and run" on the PR, or gh api -X POST repos/tabilzad/claude-code-unraid/actions/runs/<run id>/approve), because github-actions[bot] counts as an outside contributor. Configure a fine-grained personal access token with contents: write and pull-requests: write as the BUMP_TOKEN repository secret if CI should run on bump PRs without that step; with the secret in place the setting above is not needed either.

Packaging

  • scripts/build-txz builds dist/claude-code-unraid-<version>-noarch-1.txz from src/ (rooted at /) plus plugin/slack-desc. Modes are set by the build (directories 0755, files with a #! line 0755, everything else 0644), CR bytes are stripped, and the archive is laid out exactly like makepkg does it. The build is reproducible: owner 0, mtimes from SOURCE_DATE_EPOCH, single-threaded xz.
  • scripts/render-plg fills plugin/claude-code-unraid.plg.in from the build, the two lock files and the latest CHANGELOG.md sections, validating every value first.
  • scripts/lint-plg checks the rendered file (well-formed XML with entity expansion, SHA256 on the only URL element, no /mnt, attributes, CHANGES, entities, and that the pinned Claude and tmux values match the locks). make check renders a dev plg and lints it; make build builds and renders a dev version into dist/.
  • ./scripts/dev-env --root make e2e-install runs Lime Technology's real plugin manager against the rendered plg inside the container: fresh install from the flash cache, reboot with the cache, corrupt cache without network (plg lands in plugins-error), remove, and install from a <LOCAL> package.

Versioning

Unraid shows YYYY.MM.DD.N. The plugin manager compares versions with strcmp, so every field has a fixed width: the UTC date of the tag plus one sequence digit, the tag's position among the v* tags created that day (scripts/plugin-version --tag vX.Y.Z). More than nine releases a day is refused. Dev builds are 0000.00.00.0-dev (0000.00.00.0_dev in the package name, because Slackware splits package names on -). The semantic version is the tag and appears as pluginVersion in the plg and in CHANGES.

Cutting a release

  1. Merge the lock bump you want to ship, if any.
  2. Move the [Unreleased] entries in CHANGELOG.md under a ## [X.Y.Z] - YYYY-MM-DD heading and start a new empty [Unreleased] section. Commit.
  3. Run ./scripts/dev-env make check and ./scripts/dev-env --root make e2e-install.
  4. Tag: git tag -a vX.Y.Z -m "vX.Y.Z" and push the tag. Every tag becomes a full GitHub release, never a pre-release, so that releases/latest/download/claude-code-unraid.plg, the pluginURL that installed copies and Community Applications use, always resolves to the newest tag. The -beta.N suffix in the version and the Beta flag in the CA entry carry the beta status. For a build meant for testers only, run gh release edit vX.Y.Z --prerelease right after the workflow finishes: latest then skips it.
  5. .github/workflows/release.yml runs make check, builds the package with the tag's commit date as SOURCE_DATE_EPOCH, renders the plg with the release asset URL, re-runs lint-plg, writes SHA256SUMS, and creates the GitHub release with the plg, the package and the checksums. The plg's pluginURL points at releases/latest/download/claude-code-unraid.plg, which is how installed copies find updates.

Community Applications

ca/README.md describes the CA files (ca/claude-code-unraid.xml, ca_profile.xml, the icon) and the submission steps. The wrapper's PluginURL and the plg's pluginURL must stay identical; make lint-ca checks it. A release needs no resubmission: CA reads the plg at that URL.

Rotating the signing key

If Anthropic rotates its release signing key, download the new key from https://downloads.claude.ai/keys/claude-code.asc, confirm the new fingerprint from a second channel (Anthropic's documentation or security advisories), replace keys/claude-code.asc, update PINNED_FINGERPRINT in scripts/claude-release and the test in tests/bats/claude-release.bats, and describe the source of the fingerprint in the commit message. Nothing on the Unraid box changes: the box only ever checks sha256 values that CI pinned.