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
64 changes: 57 additions & 7 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# One workflow owns every npm publish, so each package trusts exactly this file
# (npm trusted publishing pins the workflow filename and the npm-publish
# environment). scripts/release-plan.mjs maps the triggering event to a mode:
# dry-run (PR), nightly (schedule or dispatch on main), or stable (a vX.Y.Z tag on
# dry-run (PR), nightly (main-owned schedule or dispatch), or stable (a vX.Y.Z tag on
# main). The tag ruleset, which only admins can bypass, is the stable release's
# approval: a tag publishes without another review.
on:
Expand All @@ -21,15 +21,24 @@
# A nightly ships main's HEAD once its CI passes. CI that fails, is cancelled,
# or outlasts the Plan job's wait skips that day.
- cron: '23 1 * * *'
# The workflow stays on main; the planner resolves 0.22 to its exact source SHA.
- cron: '53 1 * * *'
# On main: publish a nightly now. On a vX.Y.Z tag: retry that stable release.
workflow_dispatch:
inputs:
source_branch:
description: 'Nightly source (run on main; stable tag retries require main)'
type: choice
options: [main, '0.22']
default: main

permissions: {}

concurrency:
group: >-
${{ github.event_name == 'pull_request' && format('release-pr-{0}', github.ref)
|| startsWith(github.ref, 'refs/tags/') && format('release-{0}', github.ref)
|| (github.event.schedule == '53 1 * * *' || inputs.source_branch == '0.22') && 'release-nightly-0.22'
|| 'release-nightly' }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Expand All @@ -48,11 +57,13 @@
dist_tag: ${{ steps.plan.outputs.dist_tag }}
commit: ${{ steps.plan.outputs.commit }}
previous_tag: ${{ steps.plan.outputs.previous_tag }}
nightly_tag: ${{ steps.plan.outputs.nightly_tag }}
steps:
- name: Checkout
uses: useblacksmith/checkout@2b9fe87d796feea153b455ec2f3125b471a7b0e7 # v1.8.2
with:
persist-credentials: false
ref: ${{ github.workflow_sha }}

- name: Setup Node.js
uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
Expand All @@ -69,38 +80,49 @@
name: Build ${{ needs.plan.outputs.version }}
needs: plan
if: contains(fromJSON('["dry-run", "nightly", "stable"]'), needs.plan.outputs.mode)
runs-on: blacksmith-6vcpu-macos-26
runs-on: macos-26
timeout-minutes: 120
permissions:
contents: read
cache-mode: none
env:
VERSION: ${{ needs.plan.outputs.version }}
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
Comment thread
thymikee marked this conversation as resolved.
Resolved
with:
persist-credentials: false
ref: ${{ needs.plan.outputs.commit }}

- name: Checkout version stamping entrypoint
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
ref: ${{ github.workflow_sha }}
path: .release-tools
sparse-checkout: scripts/release-version.mjs
sparse-checkout-cone-mode: false

# No dependency cache: published bytes come from a clean install.
- name: Setup toolchain
Comment thread
thymikee marked this conversation as resolved.
Resolved
uses: ./.github/actions/setup-node-pnpm
with:
cache-store: 'false'

# Exports AGENT_DEVICE_ANDROID_BUILD_TOOLS, which the helper build requires on CI.
- name: Setup Android SDK
uses: ./.github/actions/setup-android-sdk

- name: Stamp release version
run: node scripts/release-version.mjs stamp "$VERSION"
run: node .release-tools/scripts/release-version.mjs stamp "$VERSION"

- name: Build and verify every public package
run: pnpm release:prepare

Check failure on line 120 in .github/workflows/release.yml

View check run for this annotation

apex-sentinel-staging / Apex Sentinel

major: 0.22 build executes the 0.22 branch's own actions and scripts inside the main-owned trusted run

A push to `0.22` controls code that runs in the main-owned build job and lands in published tarballs: the build job checks out the `0.22` SHA at the workspace root and loads `./.github/actions/setup-node-pnpm`, `./.github/actions/setup-android-sdk`, and `pnpm release:prepare` from that untrusted checkout, while the stamp step invokes `scripts/release-workspace.mjs` and `sync-mcp-metadata.mjs` from the source commit. Only the planner, publisher, and stamping entrypoint are pinned to `github.workflow_sha`; the deployment-branch policy (main + `v*`) and `refs/tags/v*` ruleset never gate the build job, so the guarantee is weaker than CONTRIBUTING states. The precondition is push access to `0.22`, a maintenance branch typically carrying weaker protection than main.

- name: Upload packages
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
with:
name: npm-packages
name: npm-packages-${{ needs.plan.outputs.commit }}
path: .tmp/release/*.tgz
include-hidden-files: true
if-no-files-found: error
Expand All @@ -117,11 +139,15 @@
permissions:
contents: read
id-token: write
attestations: write
outputs:
source_attestation: ${{ steps.source-attestation.outputs.attestation-url }}
steps:
- name: Checkout publisher
uses: useblacksmith/checkout@2b9fe87d796feea153b455ec2f3125b471a7b0e7 # v1.8.2
with:
persist-credentials: false
ref: ${{ github.workflow_sha }}
sparse-checkout: scripts/release-publish.mjs
sparse-checkout-cone-mode: false

Expand All @@ -135,9 +161,28 @@
- name: Download packages
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: npm-packages
name: npm-packages-${{ needs.plan.outputs.commit }}
path: ${{ runner.temp }}/npm-packages

- name: Bind the internal nightly source to the package bytes
id: source-attestation
if: needs.plan.outputs.dist_tag == 'nightly-0.22'
uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
with:
subject-path: ${{ runner.temp }}/npm-packages/*.tgz
create-storage-record: 'false'

Check failure on line 173 in .github/workflows/release.yml

View check run for this annotation

apex-sentinel-staging / Apex Sentinel

major: create-storage-record: 'false' discards the nightly source attestation; it is never stored or verifiable

With `create-storage-record: 'false'`, `gh attestation verify` reports no attestations for the nightly tarball and the summary line prints nothing after "binds build commit …:", because `actions/attest` signs a bundle locally in the runner temp directory which the job discards, leaving `attestation-url` empty.
Comment thread
thymikee marked this conversation as resolved.
Resolved
predicate-type: https://agent-device.dev/attestations/release-source/v1
predicate: |
{
"source": {
"repository": "${{ github.server_url }}/${{ github.repository }}",
"ref": "refs/heads/0.22",
"commit": "${{ needs.plan.outputs.commit }}"
},
"workflowCommit": "${{ github.workflow_sha }}",
"version": "${{ needs.plan.outputs.version }}"
}

- name: Publish
env:
VERSION: ${{ needs.plan.outputs.version }}
Expand All @@ -156,11 +201,16 @@
- name: Tag the published commit
env:
GH_TOKEN: ${{ github.token }}
TAG: nightly/v${{ needs.plan.outputs.version }}
TAG: ${{ needs.plan.outputs.nightly_tag }}
DIST_TAG: ${{ needs.plan.outputs.dist_tag }}
COMMIT: ${{ needs.plan.outputs.commit }}
SOURCE_ATTESTATION: ${{ needs.publish.outputs.source_attestation }}
run: |
gh api "repos/$GITHUB_REPOSITORY/git/refs" -f "ref=refs/tags/$TAG" -f "sha=$COMMIT"
echo "Published $TAG from $COMMIT: npm install agent-device@nightly" >> "$GITHUB_STEP_SUMMARY"
echo "Published $TAG from $COMMIT: npm install agent-device@$DIST_TAG" >> "$GITHUB_STEP_SUMMARY"
if [ "$DIST_TAG" = 'nightly-0.22' ]; then
echo "npm provenance identifies the main workflow commit $GITHUB_SHA; the signed source-to-package attestation binds build commit $COMMIT: $SOURCE_ATTESTATION" >> "$GITHUB_STEP_SUMMARY"
fi

github-release:
name: Draft GitHub release
Expand Down
50 changes: 48 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,13 +98,18 @@ exception is the empty `0.0.0` placeholder a maintainer publishes by hand to onb
described below. A local `npm publish` from the repository root refuses to run.

The core and every public workspace package release together at one version. Private packages
stay unpublished. There are three channels:
stay unpublished. The workflow supports these release modes:

- **Nightly** (`npm install -g agent-device@nightly`): once a day, at 01:23 UTC, the workflow
checks `main`. It publishes `X.Y.Z-nightly.<YYYYMMDD>.<run>` under the `nightly` dist-tag when
`main`'s HEAD has changed since the last nightly and its CI passed, waiting up to 20 minutes for
CI that is still running. If that CI fails, is cancelled, or is still running after the wait, no
nightly ships that day. A published nightly is tagged `nightly/v<nightly version>`. To publish one now, run **Release** on `main`.
- **0.22 nightly** (`nightly-0.22`): at 01:53 UTC, the workflow on `main` resolves `0.22`'s
HEAD, reads its `0.22.X-dev` version, and requires successful push CI on that exact commit.
It builds that SHA as `0.22.X-nightly-0-22.<YYYYMMDD>.<run>` and tags it under
`nightly-0.22/v<version>`. Deduplication and concurrency are separate from `main`'s nightly.
To publish manually after activation, run **Release** on `main` with `source_branch: 0.22`.
- **Stable** (`latest`): a repository admin publishes a GitHub release with a new `vX.Y.Z` tag
targeting `main`. Use the version `main` builds towards (its `X.Y.Z-dev`), or a later one, and
write the notes or generate them in the release form. The tag starts a **Release** run. It waits
Expand Down Expand Up @@ -155,7 +160,8 @@ granting npm trust:
unattended.
2. **Tag ruleset** (Settings → Rules → Rulesets → New tag ruleset): active, targeting
`refs/tags/v*` with no exclusions, restricting creations, updates, and deletions, with only the
Repository admin role allowed to bypass. Nightly tags live under `nightly/` and stay outside it.
Repository admin role allowed to bypass. Nightly tags live under `nightly/` or `nightly-0.22/`
and stay outside it.
3. **Actions** (Settings → Actions → General): workflow permissions set to read repository contents,
and "Allow GitHub Actions to create and approve pull requests" turned off.
4. **Releases** (Settings → General): leave release immutability off, because the run attaches its
Expand Down Expand Up @@ -186,6 +192,46 @@ release. To plan a minor or major release, commit the new `-dev` version to `mai
the repository's tool surface per version string: a released number left on `main` while `main`
keeps changing is indistinguishable from a republished ("rug-pull") version.

### Activate the 0.22 nightly channel

The `nightly-0.22` channel is unavailable until these changes are reviewed and merged and its
first publish succeeds. This channel is for internal testing. Keep its routing in release
automation and contributor instructions, without changing the CLI updater or public installation
guide. Merge the `0.22` prerequisite first: enable CI pushes on `0.22` and stamp `0.22.0-dev`
with the existing version script. Require successful push CI at the resulting `0.22` HEAD.
Then merge this release
configuration into `main`. Its next 01:53 UTC schedule can publish that source; merging the
configuration activates the schedule. Do not dispatch it before the independent review.

Keep the existing `release.yml` trusted publisher and `npm-publish` policies (`main` and `v*`).
The planner and publisher use the workflow commit; the build uses the planned source commit.
The version-stamping entrypoint uses the workflow commit and calls the source commit's workspace
and MCP metadata helpers. The publisher verifies each package's name and version before publishing.
For `nightly-0.22`, npm provenance identifies the `main` workflow commit, not the `0.22` build
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
commit. Before publishing any internal nightly package, the publisher signs a separate
source-to-artifact attestation over every downloaded tarball. Its predicate records the planned
`0.22` source commit, repository, version, and trusted workflow commit. A signing failure stops
the job before npm publication. The nightly summary links the signed attestation.

Select the expected Release run and obtain its workflow commit from GitHub, independently of
the attestation predicate. Verify the downloaded tarball against that exact main-owned signer:

```bash
WORKFLOW_SHA="$(gh run view "$RELEASE_RUN_ID" --repo callstack/agent-device --json headSha --jq .headSha)"
gh attestation verify "$TARBALL" --repo callstack/agent-device \
--signer-workflow callstack/agent-device/.github/workflows/release.yml \
--source-ref refs/heads/main --signer-digest "$WORKFLOW_SHA" \
--predicate-type https://agent-device.dev/attestations/release-source/v1 --format json
```

These flags verify the certificate's workflow identity, main ref, and workflow commit.
Do not take the expected signer SHA from `predicate.workflowCommit`, which the signer supplies.
Compare `verificationResult.statement.predicate.source.commit` with the planned source SHA
and the `nightly-0.22/v<version>` source tag. The signature verifies the binding between that
source and the package digest; npm's own provenance still identifies the main workflow commit.
Do not grant the `0.22` branch deployment access. Private optional plugins remain unpublished;
this channel does not replace their placeholder, trusted-publisher, or native validation prerequisites.

### Released-surface baselines roll forward on publish

Compatibility gates baseline against the last **released tag**, not against `main`, so publishing is
Expand Down
Loading
Loading