release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- release-and-publish
- description
- Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
- when_to_use
- NpmRegistry, PackagePublish, NpmExecutor, npm publish from CI, GitHub Packages vs npm registry, ReleaseAgeGate, VersioningStrategy, ReleaseTag, TrackingTag, macOS npm cache EACCES
02 资源文件 3
- 参考文档references/publish-pipeline.md19.3 KB
- 参考文档references/tags-and-gates.md3.6 KB
- 参考文档references/versioning-strategies.md5.6 KB
03 SKILL.md 正文
Release and publish
Cutting and publishing a release from Effect v4 spans three packages:
@effected/npm reads and writes to a registry, @effected/workspaces
decides what versions and tags a release needs, @effected/github cuts the
tag and the release. General Effect v4 rules — service shapes, layer
composition, Schema.Class, testing idioms — live in
effect-v4-services-layers, effect-v4-schema, effect-v4-testing,
effected-packages; this skill states only what these packages do for a
release pipeline.
What you have
| Construct | Import | Reach for it when |
|---|---|---|
NpmRegistry |
import { NpmRegistry } from "@effected/npm" |
Reading a package's published versions, dist-tags or publish times |
PackagePublish |
@effected/npm |
Setting up auth, packing a tarball, or publishing it |
NpmExecutor |
@effected/npm |
Choosing between the ambient npm and a pinned dlx-fetched one |
classifyRegistry |
@effected/npm |
Deciding whether a registry is public npm, GitHub Packages, JSR or custom |
ReleaseAgeGate |
@effected/pnpm |
Holding a version back until it has aged past a minimum |
VersioningStrategy, ReleaseTag |
import { VersioningStrategy } from "@effected/workspaces" |
Classifying a workspace's release shape and formatting its tags |
TrackingTag |
@effected/workspaces |
Deriving the floating v1/v1.2 GitHub Actions distribution aliases |
PublishabilityDetector |
@effected/workspaces |
Wiring or overriding which packages publish, and to where |
GitTag, GitHubRelease |
import { GitTag, GitHubRelease } from "@effected/github" |
Cutting the actual git tag and GitHub release — see github-api |
Standards
- Treat the registry as a per-call argument, never a layer-baked one. A
single program can legitimately probe two registries for one package —
don't collapse
NpmRegistryto a fixed registry at construction. - Route a 404 through
Option.none(), never through stderr-wording matching. Absence is decided on response status structurally, so it survives an npm version bump that reworded its error text. - Compare
integrityas the typed brand it is, not a bare string. A string-equals comparison between an SRI hash and something that merely looks like one is a defect waiting on a format change. - Send the auth token to a caller-supplied npmrc path, never argv.
Masking the token in a CI log is the caller's job —
PackagePublishhas no opinion about log output and noActionOutputsedge to have one. - Never swap
pack's two digests.integritycompares against the registry's own SRI hash;sha256Hex— read back off the packed tarball, not derived from npm's report — is the attestation subject. They are both strings; getting them backwards is silent. - Let
dlxfail typed when there's no project-local launcher — never let it silently fall back to the ambient npm. A silent fallback would reintroduce exactly the OIDC-publishing failure the pinned version exists to avoid. - Match a registry's subdomain with a leading dot. A bare suffix match
would classify a look-alike hostname as the public registry, and that
classification gates both token-sending and
--provenance. - Clamp a release-age gate only through
ReleaseAgeGate.combine, never in isolation.combineis the single authority: strictest age wins, exclude sets union — route every contribution through it, even a lone one, so the clamping logic stays in one place. - Give
PublishabilityDetectorno ambient default. Every composite that decides workspace versioning requires it explicitly inR— ship named policies (.layerNpm,.layerNone) rather than letting a merge silently pick a default no type error would catch. - Prefer
GitTag.upsert/GitHubRelease.createover a hand-rolled exists-then-create sequence when cutting a release — seegithub-api.
Footguns
- GitHub's macOS runner images ship a partly root-owned npm cache, and
npm packhard-fails against it with an unrecoverable permission error. This is deterministic on every macOS run until the cache is redirected — not a flaky retry candidate. The redirect must be visible at the publish call site — an explicit cache-directory option passed alongside the pack/publish call itself — never an invisible environment variable set once, far from the call it protects. Seereferences/publish-pipeline.md. - The scoped/unscoped
vprefix asymmetry inReleaseTagis deliberate, reproducing production byte for byte — don't "normalize" it to look more consistent. - Tracking tags (
v1,v1.2) derive nothing for a prerelease by default — re-pointingowner/repo@v1at a beta with no signal would ship it to every consumer depending on the newest stable 1.x. ReleaseAgeGate's glob dialect is pnpm's*-crosses-/matcher, not@effected/glob's minimatch dialect — routing exclude patterns through the wrong engine silently changes which packages a gate exempts.- A lane prerelease publishes under
latestunless--tagis passed. Under pnpm-native release planning a lane buildsX.Y.Z-<lane>.N, but a prerelease segment does not choose a dist-tag. Pass the tag at the publish call (the lane's name is the natural one) or every consumer onlatestreceives it; the planner (@effected/changesets) plans versions and never picks a tag. NpmRegistry.layerTest()with no overrides dies loudly by design on the first read — reach forNpmRegistry.layerSeeded({ registries: {} })when a test wants a real, working empty registry instead. Every read of it answersOption.none(), as a 404 does, includingversions,distTagsandpublishTimes.
Additional resources
- references/publish-pipeline.md — the
full
NpmRegistry/PackagePublish/NpmExecutorsurface, registry classification, and the macOS npm-cache hazard in detail. Load when: reading the registry, packing/publishing a tarball, or debugging a publish step that only fails on macOS. - references/versioning-strategies.md —
VersioningStrategy,ReleaseTagformatting,TrackingTagderivation, andPublishabilityDetector's no-ambient-default rule. Load when: classifying a workspace's release shape or formatting/deriving tags. - references/tags-and-gates.md — the
ReleaseAgeGateclamping and exclude-matching rules, plus theGitTag/GitHubReleasecall sequence for cutting a release. Load when: gating a resolver against too-young releases, or cutting the tag and release once a version is chosen.
Elsewhere
@effected/commands'RunandLocalExecin full (the combinatorsPackagePublishruns through, the argv-prefix table) →running-commands-and-tools.GitBranch/GitTag/GitHubRelease's full member catalogue,GitHubErrorclassification, pagination, retry policy →github-api.- GitHub App authentication and token lifecycle →
github-app-tokens. - Sigstore signing and CycloneDX SBOM generation over
PackedTarball'ssha256Hex→supply-chain-attestation. Action.run'sActionServicesand why a publish layer'sRcollapses to justLocalExecinside an action →actions-runtime.- The scripted-spawner and seeded-registry test harnesses this surface is
built to be testable against →
testing-actions.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.
github-app-tokens
Use when a GitHub credential needs to come into existence, live somewhere, and die — constructing a client from a plain token or a GitHub App, or wiring GitHubToken's provision/read/clientLayer/dispose lifecycle across an Action's pre/main/post phases.