Skip to content

DISTRIBUTION.md

Latest commit

 

History

History
68 lines (44 loc) · 2.96 KB

DISTRIBUTION.md

File metadata and controls

68 lines (44 loc) · 2.96 KB
Raw

Distribution

Delivery Model

Every merge to main should already be releasable.

GitHub Actions owns releases for this repo and the workflow runs on GitHub-hosted Ubuntu runners.

The pipeline runs these release steps on main:

  1. vp install
  2. vp run verify
  3. vp run lint:package
  4. compatibility matrix for Node, Chromium, Firefox, WebKit, and Bun
  5. run semantic-release through the release action

The workflow uses .releaserc.json as the release source of truth. The release action is SHA-pinned and every extra_plugins entry is version-pinned, so the secret-bearing release job does not fetch unversioned semantic-release plugins.

The release lane:

  • reads commit history on main
  • calculates the next version
  • publishes @putdotio/sdk to npm
  • creates the GitHub release
  • commits the released package.json version back to main

Release Environment

The release job declares the protected GitHub Environment named release.

Environment entries:

  • secrets: PUTIO_RELEASE_BOT_PRIVATE_KEY
  • variables: PUTIO_RELEASE_BOT_CLIENT_ID
  • approval: none; releases are continuous after the main gate passes
  • refs: release branch/tag policy constrains what can publish
  • deployment records: disabled with deployment: false because this is package publishing, not an app deploy

The npm package uses Trusted Publishing from GitHub Actions. On npm, configure owner putdotio, repository putio-sdk-typescript, workflow ci.yml, and Environment named release for the package.

During the @semantic-release/npm publish step, npm detects the GitHub OIDC identity, mints short-lived publish credentials, and publishes provenance for the release job. The package repository metadata points at putdotio/putio-sdk-typescript so npm can match the OIDC publisher identity.

Release GitHub writes use putio-releaser through PUTIO_RELEASE_BOT_CLIENT_ID and PUTIO_RELEASE_BOT_PRIVATE_KEY.

The workflow keeps dependency caches only on secretless verify jobs. The secret-bearing release job runs a fresh vp install with package-manager caching disabled before publishing to npm.

The release-bot remote is configured only after dependencies are installed.

Public-repo branch policy may still allow trusted put.io team members to push directly to main, but it should block outsiders, force-pushes, and branch deletes where GitHub plan support allows. Release tag policy restricts v* tag creation, update, and deletion to putio-releaser and org admins.

Local Checks

Before changing distribution wiring, validate the repo-local guardrails the workflow depends on:

vp install
vp run verify
vp run lint:package
vp run test:compat

Keep release plugins version-pinned in the workflow when updating .releaserc.json.

Versioning Notes

  • This repo keeps the historical release line from the archived putio-js package.
  • The standalone @putdotio/sdk line starts at v9.0.0.
  • Conventional commits drive automated version selection through .releaserc.json.