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
129 changes: 107 additions & 22 deletions .github/workflows/scient.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,27 @@ name: Scient Agent
# every pull request into it, and checks that each build keeps its state apart
# from a stock omp. The macOS builds are signed on Linux by upstream's
# scripts/ci-macos-sign.sh, ad hoc on every run so the signing path is always
# exercised, then checked on macOS. A `v*` tag signs them with the Developer ID,
# notarizes them and drafts a GitHub release with every binary and its
# checksum; a person publishes the draft. A manual run can sign and notarize
# without drafting a release, to qualify the signing secrets. Oh My Pi's own
# test suite runs on Linux against Scient's tree, as upstream's CI runs it.
# exercised, then checked on macOS. A manual run on main with `release` set
# builds scient.json's version, signs the macOS builds with the Developer ID,
# notarizes them and, once every job passed, drafts a GitHub release with every
# binary and its checksum; a person publishes the draft, which creates the tag.
# As in Scient Desktop's release, a version is used up only when it is
# published: after a failed or superseded run, run again with the same version.
# A manual run can also sign and notarize without drafting a release, to
# qualify the signing secrets. Oh My Pi's own test suite runs on Linux against
# Scient's tree, as upstream's CI runs it.

on:
push:
branches: ["main", "scient/**"]
tags: ["v*"]
pull_request:
branches: ["main"]
workflow_dispatch:
inputs:
release:
description: Release scient.json's version from main (it must come right after the latest published release)
type: boolean
default: false
developer-id:
description: Sign the macOS builds with the Developer ID and notarize them (no release is drafted)
type: boolean
Expand All @@ -28,20 +35,52 @@ permissions:

concurrency:
# A manual run never cancels, or is cancelled by, a push to the same branch.
group: scient-${{ github.ref }}-${{ github.event_name == 'workflow_dispatch' && 'manual' || 'auto' }}
cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
# A release run is never cancelled: a second one waits for it.
group: scient-${{ (github.event_name == 'workflow_dispatch' && inputs.release) && 'release' || format('{0}-{1}', github.ref, github.event_name == 'workflow_dispatch' && 'manual' || 'auto') }}
cancel-in-progress: ${{ !(github.event_name == 'workflow_dispatch' && inputs.release) }}

env:
# A release is a pushed product tag. A manual run never drafts one, even against a tag.
RELEASE: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
DEVELOPER_ID: ${{ (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) || inputs.developer-id == true }}
# A release is a manual run with `release` set; the release-version job refuses any branch but main.
RELEASE: ${{ github.event_name == 'workflow_dispatch' && inputs.release == true }}
DEVELOPER_ID: ${{ github.event_name == 'workflow_dispatch' && (inputs.release == true || inputs.developer-id == true) }}

defaults:
run:
# Windows runners default to PowerShell.
shell: bash

jobs:
# A release builds scient.json's version only if it comes right after the
# latest published release and is not tagged yet (scripts/scient/release-version.ts).
# The release job checks again before it drafts.
release-version:
name: Check the release version
# Job conditions cannot read workflow env, so this repeats RELEASE.
if: github.event_name == 'workflow_dispatch' && inputs.release
runs-on: ubuntu-24.04
timeout-minutes: 10
outputs:
version: ${{ steps.check.outputs.version }}
steps:
- name: Release from main only
run: |
if [ "$GITHUB_REF" != refs/heads/main ]; then
echo "::error::A release is built from main, not $GITHUB_REF."
exit 1
fi

- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.4

- id: check
name: Check the version
env:
GH_TOKEN: ${{ github.token }}
run: bun scripts/scient/release-version.ts

build:
name: Build and check (${{ matrix.id }})
runs-on: ${{ matrix.runner }}
Expand Down Expand Up @@ -132,11 +171,11 @@ jobs:
echo "BINARY=$binary" >> "$GITHUB_ENV"
"$binary" --version < /dev/null

- name: Check the release matches its tag
- name: Check the build reports scient.json's version
if: env.RELEASE == 'true'
run: |
version="$("$BINARY" --version < /dev/null)"
test "$version" = "scient-agent/${GITHUB_REF_NAME#v}"
test "$version" = "scient-agent/$(bun -e 'console.log((await Bun.file("scient.json").json()).version)')"

- name: Check state isolation
run: bun scripts/scient/isolation-check.ts "$BINARY"
Expand Down Expand Up @@ -364,11 +403,11 @@ jobs:
fi
"$binary" --version < /dev/null

- name: Check the release matches its tag
- name: Check the build reports scient.json's version
if: env.RELEASE == 'true'
run: |
version="$("$BINARY" --version < /dev/null)"
test "$version" = "scient-agent/${GITHUB_REF_NAME#v}"
test "$version" = "scient-agent/$(bun -e 'console.log((await Bun.file("scient.json").json()).version)')"

- name: Check state isolation
run: bun scripts/scient/isolation-check.ts "$BINARY"
Expand Down Expand Up @@ -418,30 +457,76 @@ jobs:
release:
name: Draft release
# Job conditions cannot read workflow env, so this repeats RELEASE.
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
needs: [build, verify-macos, compress, divergence, upstream-tests]
if: github.event_name == 'workflow_dispatch' && inputs.release
needs: [release-version, build, verify-macos, compress, divergence, upstream-tests]
runs-on: ubuntu-24.04
permissions:
contents: write
env:
VERSION: ${{ needs.release-version.outputs.version }}
TAG: v${{ needs.release-version.outputs.version }}
steps:
- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: 1.4.4

# The run takes an hour or more; a release may have been published meanwhile.
- name: Check the version is still next
env:
GH_TOKEN: ${{ github.token }}
run: bun scripts/scient/release-version.ts

- uses: actions/download-artifact@v4
with:
pattern: scient-agent-*
path: release
merge-multiple: true

# A draft that was never published holds no tag and does not use its
# version up: this run's draft replaces it. GitHub cannot delete only
# if still a draft, so each one is read again right before; SCIENT.md
# says not to publish a draft while a release run of its version runs.
- name: Replace an unpublished draft of this version
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
drafts="$(gh api --paginate "repos/$GITHUB_REPOSITORY/releases?per_page=100" \
--jq ".[] | select(.draft and .tag_name == \"$TAG\") | .id")"
for id in $drafts; do
if [ "$(gh api "repos/$GITHUB_REPOSITORY/releases/$id" --jq .draft)" != true ]; then
echo "::error::$TAG's draft $id was published during this run; nothing was replaced."
exit 1
fi
echo "Deleting the unpublished draft $id of $TAG."
gh api -X DELETE "repos/$GITHUB_REPOSITORY/releases/$id"
done

# Publishing the draft creates the tag on the commit built here; until
# then no tag exists, so the version is not used up.
- name: Create the draft release
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
ls -l release
gh release create "$GITHUB_REF_NAME" release/* \
gh release create "$TAG" release/* \
--repo "$GITHUB_REPOSITORY" \
--draft \
--title "Scient Agent ${GITHUB_REF_NAME#v}" \
--target "$GITHUB_SHA" \
--title "Scient Agent $VERSION" \
--notes "Built from ${GITHUB_SHA}."
if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" > /dev/null 2>&1; then
echo "::error::Drafting $TAG created its tag; the version would be used up before it is published."
exit 1
fi

# Scient Desktop downloads from Scient's own copy first and falls back to
# this release, so a GitHub outage doesn't block installs. Its catalog
# publishes a version only after every copy here matches the digest.
# publishes a version only after every copy here matches the digest. A
# run that replaces an unpublished draft overwrites that draft's copy.
- name: Copy the release to downloads.scientfactory.com
env:
AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
Expand All @@ -457,10 +542,10 @@ jobs:
for name in R2_ACCOUNT_ID AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY R2_BUCKET; do
if [ -z "${!name}" ]; then echo "::error::$name is not set; Scient's copy was not uploaded." >&2; exit 1; fi
done
aws s3 cp release/ "s3://$R2_BUCKET/scient-agent/$GITHUB_REF_NAME/" --recursive \
aws s3 cp release/ "s3://$R2_BUCKET/scient-agent/$TAG/" --recursive \
--endpoint-url "https://$R2_ACCOUNT_ID.r2.cloudflarestorage.com" \
--content-type application/octet-stream \
--cache-control "public, max-age=3600"
for file in release/*; do
echo "https://downloads.scientfactory.com/scient-agent/$GITHUB_REF_NAME/$(basename "$file")"
echo "https://downloads.scientfactory.com/scient-agent/$TAG/$(basename "$file")"
done
12 changes: 10 additions & 2 deletions SCIENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ The 18.8.4 alignment predates markers; its in-place changes were accepted with i

## Branches, releases and upstream updates

- `main` holds Scient Agent. Changes reach it through pull requests that keep their commits (rebase merge; history stays linear). A release is a `v<version>` tag on `main` that matches `scient.json`: `v0.1.0`, `v0.1.1`, ...
- `main` holds Scient Agent. Changes reach it through pull requests that keep their commits (rebase merge; history stays linear). A release is a published GitHub release of `scient.json`'s version, tagged `v<version>` on the `main` commit it was built from: `v0.1.0`, `v0.1.1`, ... A version is used up only when its release is published, so published versions follow each other with no gaps (see Release).
- Scient's commits come in three kinds: the scripts under `scripts/scient/`, generated commits (the output of one generator and nothing else, subject ending in `(generated)`, trailer `Scient-Generator: identity`, `wording` or `rpc`), and hand-written changes (trailer `Scient-Divergence: <ids>` in a replay). A pull request that changes what a script produces carries the output as its own generated commit.
- `upstream` is a fetch-only remote for Oh My Pi. `scient/18.4.8` is the branch the work started on, kept as it was.

Expand Down Expand Up @@ -929,6 +929,14 @@ The Intel macOS job restores Cargo dependency artifacts keyed by the compiler, R

The macOS builds are signed by upstream's `scripts/ci-macos-sign.sh`, unchanged, on a Linux runner (it uses a pinned `rcodesign`): ad hoc on every run, so the signing path is exercised by every pull request. A separate job then runs the signed bytes on their own macOS runner: checksum, `codesign --verify --strict`, `--version` and the isolation check. An unsigned macOS build is uploaded under an `unsigned-` name and can never reach a release.

Pushing a `v<version>` tag that matches `scient.json` signs the macOS builds with the Developer ID, notarizes them, refuses an ad-hoc signature, and drafts a GitHub release with every binary, its zstd copy (`<binary>.zst`) and the SHA-256 of each. A person publishes the draft. The same job copies them all to `downloads.scientfactory.com/scient-agent/v<version>/` (Cloudflare R2; secrets `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` and variable `R2_DOWNLOADS_BUCKET`). Scient Desktop downloads that copy first and falls back to the GitHub release, and its catalog publishes a version only after every copy matches the digest. Desktop prefers the zstd copy, about 40% of the binary's size, unpacks it and checks the binary's SHA-256; it falls back to the binary itself, and Desktops that predate the copies download only the binary. The `compress` job makes the copies on every run with `zstd -19 --long=27` and checks that each unpacks to its binary: Desktop allows a window of at most 2^27 bytes, and the check unpacks with the same limit. A manual run of the workflow with `developer-id` set signs and notarizes without drafting a release; use it to qualify the signing secrets before tagging. Not built yet: Linux with musl (Alpine). The Windows builds are not code-signed.
A release follows Scient Desktop's order: the version is checked first, the tag comes last.

1. A pull request sets `scient.json`'s version to the one right after the latest published release (next patch, minor or major), in a commit `release: Scient Agent <version>`.
2. Once it is on `main`, run the workflow manually on `main` with `release` set. Its first job (`scripts/scient/release-version.ts`) refuses a version that does not come right after the latest published release, or that a tag carries already. The run signs the macOS builds with the Developer ID, notarizes them and refuses an ad-hoc signature. Only when every job passed does it check the version again and draft a GitHub release with every binary, its zstd copy (`<binary>.zst`) and the SHA-256 of each, targeting the commit it built.
3. A person publishes the draft. Publishing creates the `v<version>` tag on that commit; a draft has no tag.

A version whose run failed, or whose draft was not published, is not used up. Fix `main` and run the release again with the same version: its draft replaces the unpublished one. Never move `scient.json` to a later version for a retry. A failed job can also be rerun in the same run. Do not publish a draft while a release run of the same version is running: that run deletes the old draft just before it drafts its own, and GitHub cannot limit a deletion to drafts. A `v<version>` tag pushed by hand on a version that was never published blocks it; the release run says so, and the tag is deleted before running again.

The release job copies the release files to `downloads.scientfactory.com/scient-agent/v<version>/` (Cloudflare R2; secrets `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` and variable `R2_DOWNLOADS_BUCKET`), overwriting the copy of a draft it replaces. Scient Desktop's catalog takes only published releases. Desktop downloads that copy first and falls back to the GitHub release, and its catalog publishes a version only after every copy matches the digest. Desktop prefers the zstd copy, about 40% of the binary's size, unpacks it and checks the binary's SHA-256; it falls back to the binary itself, and Desktops that predate the copies download only the binary. The `compress` job makes the copies on every run with `zstd -19 --long=27` and checks that each unpacks to its binary: Desktop allows a window of at most 2^27 bytes, and the check unpacks with the same limit. A manual run of the workflow with `developer-id` set signs and notarizes without drafting a release; use it to qualify the signing secrets before a release run. Not built yet: Linux with musl (Alpine). The Windows builds are not code-signed.

Signing uses the same five repository secrets, in the same form, as Scient Desktop's release: `CSC_LINK` (the Developer ID Application certificate as a base64 `.p12`), `CSC_KEY_PASSWORD`, `APPLE_API_KEY` (the App Store Connect `.p8` key's text), `APPLE_API_KEY_ID` and `APPLE_API_ISSUER`.
10 changes: 8 additions & 2 deletions scripts/scient/divergences.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
},
"SA-RELEASE": {
"status": "active",
"contract": "Only Scient's own workflow builds, signs and drafts releases; Oh My Pi's publishing and repository automation is removed, and so is its Nix packaging, which installs and configures a stock omp.",
"contract": "Only Scient's own workflow builds, signs and drafts releases, and only of the version right after the latest published release, whose tag publishing the draft creates; Oh My Pi's publishing and repository automation is removed, and so is its Nix packaging, which installs and configures a stock omp.",
"owned": [
"SCIENT.md",
".github/README.md",
Expand All @@ -37,6 +37,8 @@
"scripts/scient/lib/ledger.ts",
"scripts/scient/lib/markers.ts",
"scripts/scient/native-variant.ts",
"scripts/scient/release-version.ts",
"scripts/scient/release-version.test.ts",
"scripts/scient/upstream-tests.ts",
"scripts/scient/upstream-tests.test.ts"
],
Expand All @@ -54,7 +56,11 @@
"nix/nixos-module.nix",
"nix/package.nix"
],
"verification": ["bun scripts/scient/divergence-check.ts", "bun scripts/scient/isolation-check.ts <binary>"]
"verification": [
"bun scripts/scient/divergence-check.ts",
"bun scripts/scient/isolation-check.ts <binary>",
"bun test scripts/scient/release-version.test.ts"
]
},
"SA-PRODUCT": {
"status": "active",
Expand Down
31 changes: 31 additions & 0 deletions scripts/scient/release-version.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { describe, expect, it } from "bun:test";
import { nextVersions, releaseRefusal } from "./release-version";

describe("release version", () => {
it("follows the latest published release by one patch, minor or major step", () => {
expect(nextVersions("0.1.9")).toEqual(["0.1.10", "0.2.0", "1.0.0"]);
for (const version of ["0.1.9", "0.2.0", "1.0.0"]) {
expect(releaseRefusal(version, { latestPublished: "v0.1.8", tagExists: false })).toBeUndefined();
}
});

it("refuses to skip a number, repeat one or go back", () => {
for (const version of ["0.1.10", "0.3.0", "0.1.8", "0.1.7"]) {
expect(releaseRefusal(version, { latestPublished: "v0.1.8", tagExists: false })).toContain(
"next release is 0.1.9",
);
}
});

it("reuses a version whose earlier run failed or was never published, but never a tagged one", () => {
expect(releaseRefusal("0.1.9", { latestPublished: "v0.1.8", tagExists: false })).toBeUndefined();
expect(releaseRefusal("0.1.8", { latestPublished: "v0.1.8", tagExists: true })).toContain("tagged already");
// A tag on the next version with no published release was pushed by hand; the run says to delete it.
expect(releaseRefusal("0.1.9", { latestPublished: "v0.1.8", tagExists: true })).toContain("delete that tag");
});

it("allows any version before the first published release, and refuses one that is not x.y.z", () => {
expect(releaseRefusal("0.1.0", { latestPublished: null, tagExists: false })).toBeUndefined();
expect(releaseRefusal("0.1.9-beta", { latestPublished: "v0.1.8", tagExists: false })).toContain("not x.y.z");
});
});
Loading
Loading