Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@
# Stage B (publish): runs only on workflow_dispatch with publish=true AND the
# protected `npm-release` environment's approval. Downloads Stage A's exact
# artifacts, verifies checksums / tag / declared versions, refuses to overwrite
# any existing version, publishes in dependency order with provenance, verifies
# via `npm view` + a clean registry install, and only then creates the GitHub
# any existing version, publishes in dependency order with provenance under the
# `latest` dist-tag, verifies via `npm view` (version + dist-tag) + a clean
# registry install, and only then creates the GitHub
# prerelease.
#
# Auth: npm trusted publishing (GitHub Actions OIDC) — configured on
Expand Down Expand Up @@ -187,7 +188,9 @@ jobs:
fi
done
echo "no target version exists — safe to publish"
- name: Publish in dependency order (--access public --tag alpha --provenance)
# --tag latest even for prereleases: OIDC trusted publishing cannot run
# dist-tag mutations, so the publish itself must set the tag installs use.
- name: Publish in dependency order (--access public --tag latest --provenance)
run: |
set -euo pipefail
VERSION="${RELEASE_TAG#v}"
Expand All @@ -198,34 +201,34 @@ jobs:
# of a file path and tries git ls-remote (run 29307312478).
t="./release-artifacts/git-agentic-sentinel-$p-$VERSION.tgz"
echo "publishing @git-agentic/sentinel-$p@$VERSION"
if ! npm publish "$t" --access public --tag alpha --provenance; then
if ! npm publish "$t" --access public --tag latest --provenance; then
echo "::error::publish of @git-agentic/sentinel-$p failed. Already published (immutable): ${published:-none}. Do NOT unpublish; fix forward."; exit 1
fi
published="$published @git-agentic/sentinel-$p"
echo "- @git-agentic/sentinel-$p@$VERSION published" >> "$GITHUB_STEP_SUMMARY"
done
- name: Verify every published package via npm view
# Hard cap: the loop's deadline is checked between polls, and a hung
# `npm view` could otherwise outlast it.
timeout-minutes: 12
run: |
set -euo pipefail
VERSION="${RELEASE_TAG#v}"
# The registry can take minutes to show a fresh publish (run
# 44750832298 gave up after 75 s although every package was out).
# One shared 10-minute deadline covers all seven packages.
deadline=$(( $(date +%s) + 600 ))
for p in core proxy sandbox mcp steward cli action; do
for i in 1 2 3 4 5; do
got="$(npm view "@git-agentic/sentinel-$p@$VERSION" version 2>/dev/null || true)"
[ "$got" = "$VERSION" ] && break
while :; do
got="$(npm view "@git-agentic/sentinel-$p@$VERSION" version --prefer-online 2>/dev/null || true)"
latest="$(npm view "@git-agentic/sentinel-$p" dist-tags.latest --prefer-online 2>/dev/null || true)"
[ "$got" = "$VERSION" ] && [ "$latest" = "$VERSION" ] && break
if [ "$(date +%s)" -ge "$deadline" ]; then
echo "::error::@git-agentic/sentinel-$p: version ${got:-missing}, dist-tag latest ${latest:-missing}; expected $VERSION after 10 minutes"; exit 1
fi
sleep 15
done
[ "$got" = "$VERSION" ] || { echo "::error::@git-agentic/sentinel-$p@$VERSION not visible after publish"; exit 1; }
tag_alpha="$(npm view "@git-agentic/sentinel-$p" dist-tags.alpha)"
[ "$tag_alpha" = "$VERSION" ] || { echo "::error::@git-agentic/sentinel-$p dist-tag alpha is $tag_alpha, expected $VERSION"; exit 1; }
# npm auto-creates `latest` on a package's first publish (even with
# --tag alpha) and never moves it. OIDC trusted publishing cannot
# run dist-tag mutations, so drift is surfaced here, not fixed here.
tag_latest="$(npm view "@git-agentic/sentinel-$p" dist-tags.latest 2>/dev/null || true)"
if [ -n "$tag_latest" ] && [ "$tag_latest" != "$VERSION" ]; then
echo "::warning::@git-agentic/sentinel-$p dist-tag latest is $tag_latest (stale). Until a stable release exists, retarget it: npm dist-tag add @git-agentic/sentinel-$p@$VERSION latest"
echo "- ⚠ sentinel-$p latest→$tag_latest is stale; run: \`npm dist-tag add @git-agentic/sentinel-$p@$VERSION latest\`" >> "$GITHUB_STEP_SUMMARY"
fi
echo "@git-agentic/sentinel-$p@$VERSION visible, dist-tag alpha OK"
echo "@git-agentic/sentinel-$p@$VERSION visible, dist-tag latest OK"
done

verify-registry-install:
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,10 @@ macOS Seatbelt enforcement is exercised on maintainers' machines) — but this
has not yet been hardened by production use, and APIs may change without
notice. The complete phase-by-phase build log lives in
[docs/adr/](./docs/adr/) (one ADR per phase). **Published as an alpha
preview**: all seven packages ship under the `alpha`
dist-tag (`npm install -g @git-agentic/sentinel-cli@alpha @git-agentic/sentinel-proxy@alpha`) — see
preview**: every release, alphas included, is published as the `latest`
dist-tag (`npm install -g @git-agentic/sentinel-cli @git-agentic/sentinel-proxy`;
until `0.1.0-alpha.4` ships, `latest` still names `0.1.0-alpha.2` for most
packages, so append `@0.1.0-alpha.3` to get the current release) — see
the [release notes](./docs/releases/) and
[release process](./docs/release-process.md); building from source
(Quickstart below) remains fully supported. Threat model:
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sandbox for the npm ecosystem. We treat reports against it accordingly.
## Supported versions

Sentinel is pre-1.0. Only the tip of `main` and the most recent published
prerelease (`@git-agentic/sentinel-*@alpha`) are supported;
prerelease (the `latest` dist-tag of `@git-agentic/sentinel-*`) are supported;
there are no maintained release branches. Prereleases are snapshots of
`main` — fixes ship as the next prerelease, never as patches to an old one.

Expand Down
37 changes: 17 additions & 20 deletions docs/release-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,14 @@ failure without unpublishing anything already released.

## Prerelease versioning

- Pre-1.0 releases use `0.1.0-alpha.N` (then `-beta.N`, `-rc.N`) with the
npm dist-tag matching the prerelease channel (`alpha`, `beta`, `rc`).
- **The `latest` dist-tag, pre-stable:** npm force-creates `latest` on a
package's first publish (even with `--tag alpha`) and never moves it; it
also cannot be deleted. Until a stable release exists, `latest` is
therefore kept pointing at the **newest prerelease** — retargeted manually
after each release (`npm dist-tag add @git-agentic/sentinel-<p>@<version>
latest`, one per package; needs an interactive npm login — OIDC trusted
publishing covers publish only, not dist-tag mutations). Stage B warns in
the run summary when `latest` is stale. Once `0.1.0` stable ships with
`--tag latest`, this manual step disappears.
- Pre-1.0 releases use `0.1.0-alpha.N` (then `-beta.N`, `-rc.N`).
- **Every release is published with `--tag latest`**, prereleases included.
OIDC trusted publishing covers `npm publish` only, not `npm dist-tag`, and
a manual retarget needs one browser 2FA approval per package. So the
publish itself sets the tag that a plain `npm install` resolves, and no
release needs a manual dist-tag step.
- The `alpha` dist-tag is no longer moved. It stays on `0.1.0-alpha.3`, the
last release published with `--tag alpha`; install without a tag.
- All seven packages version in lockstep — one release version across the
workspace, even for packages with no changes. Lockstep keeps the internal
dependency pins trivially correct and the support matrix one-dimensional.
Expand Down Expand Up @@ -77,8 +74,9 @@ jobs): requires `publish=true` on the dispatch **and** approval of the protected
artifacts, verifies checksums, verifies the tag points at the tested commit,
verifies every tarball declares the release version, refuses to run if any
target version already exists, publishes in dependency order with
`--access public --tag alpha --provenance`, and verifies each package via
`npm view` (version + dist-tag). The `verify-registry-install` job then installs
`--access public --tag latest --provenance`, and verifies each package via
`npm view` (version + `latest` dist-tag), waiting up to 10 minutes in total for
the registry to show them. The `verify-registry-install` job then installs
the published packages from the public registry in a clean project. Only after
that does the `github-release` job create the GitHub prerelease with the
artifacts attached.
Expand Down Expand Up @@ -124,7 +122,8 @@ exact commit + workflow run.
1. **Deprecate immediately**: `npm deprecate @git-agentic/sentinel-<p>@<version>
"SECURITY: compromised — do not install"` for every affected package.
2. Point the dist-tag at the last known-good version (`npm dist-tag add
@git-agentic/sentinel-<p>@<good> alpha`).
@git-agentic/sentinel-<p>@<good> latest`; interactive login, one 2FA
approval per package).
3. Request npm unpublish/security takedown through npm support if within
policy; do not rely on it.
4. Rotate every credential the pipeline touched (npm token, corpus/policy
Expand All @@ -145,11 +144,9 @@ path.

1. Land fixes on `main`; bump all workspaces + internal pins +
`ENGINE_VERSION`/CLI/MCP versions to `0.1.0` (no prerelease suffix).
2. Run the same two-stage pipeline with tag `v0.1.0`, publishing with
`--tag latest` (the workflow's dist-tag is the one alpha-specific knob to
change — everything else is identical).
3. Keep `alpha` pointing at the last alpha until `latest` exists, then move
`alpha` forward to `0.1.0` as well so `@alpha` installs never resolve
older than stable.
2. Run the same two-stage pipeline with tag `v0.1.0`. It already publishes
with `--tag latest`, so nothing in the workflow changes.
3. Once stable releases exist, publish later prereleases under a channel tag
(`--tag next` or `--tag beta`) so they stop replacing stable on `latest`.
4. The GitHub release loses the `--prerelease` flag; SECURITY.md's supported
versions section starts naming the stable line.
2 changes: 1 addition & 1 deletion packages/action/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ idempotent PR comment body — no separately-running proxy needed.
> without notice. Not production-ready.

```bash
npm install @git-agentic/sentinel-action@alpha
npm install @git-agentic/sentinel-action
```

This package is the engine behind the composite GitHub Action defined at the
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ authoring/signing, and signed audit attestations.
> without notice. Not production-ready.

```bash
npm install -g @git-agentic/sentinel-cli@alpha
npm install -g @git-agentic/sentinel-cli

sentinel --version
sentinel audit is-odd 3.0.1 # requires a running @git-agentic/sentinel-proxy
Expand Down
2 changes: 1 addition & 1 deletion packages/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ that can only ever *enrich* — never set — a score.
> without notice. Not production-ready.

```bash
npm install @git-agentic/sentinel-core@alpha
npm install @git-agentic/sentinel-core
```

```ts
Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ only write tool *requests* approval; it can never grant one.
> without notice. Not production-ready.

```bash
npm install -g @git-agentic/sentinel-mcp@alpha
npm install -g @git-agentic/sentinel-mcp
```

MCP client configuration:
Expand Down
2 changes: 1 addition & 1 deletion packages/proxy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ npm compatibility surface (packuments, dist-tags, unpublish-as-retraction).
> without notice. Not production-ready.

```bash
npm install -g @git-agentic/sentinel-proxy@alpha
npm install -g @git-agentic/sentinel-proxy
sentinel-proxy # starts the proxy on 127.0.0.1:4873
```

Expand Down
2 changes: 1 addition & 1 deletion packages/sandbox/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ with a fail-closed contract on any other platform.
> without notice. Not production-ready.

```bash
npm install @git-agentic/sentinel-sandbox@alpha
npm install @git-agentic/sentinel-sandbox
```

## Platform behavior in this alpha
Expand Down
2 changes: 1 addition & 1 deletion packages/steward/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ retraction-corpus releases that Sentinel proxies consume offline.
> without notice. Not production-ready.

```bash
npm install -g @git-agentic/sentinel-steward@alpha
npm install -g @git-agentic/sentinel-steward
```

All four variables are required:
Expand Down
Loading