Skip to content

Commit 9e82e67

Browse files
committed
ci(golang): tag Go module releases with their WASI guests
The Go module embeds three WASI guests built from Rust, and they are gitignored on main. Go fetches a module version as the files committed at its tag, so tagging a main commit would give `go get` a module that builds and then fails at NewClient with ErrGuestNotBuilt. release-golang.yml is dispatched by hand with a version. It builds the guests and the deterministic test builds, runs the Go tests against them, builds the EQL SQL bundles, then commits the three guests on a release-only commit that no branch points at, tags it languages/golang/v<version> and pushes the tag alone. The GitHub release carries the EQL v4 install and uninstall SQL and the guests' SHA-256, and is marked a pre-release for a pre-release version. A last step asks proxy.golang.org for the version so a tag that does not resolve fails the run. It restores no cache, since it publishes binaries, and is registered with lint-no-workflow-caching and the EQL suite's publish-path exemption. Refs #1034
1 parent 3aaeddd commit 9e82e67

5 files changed

Lines changed: 184 additions & 1 deletion

File tree

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
name: Release (Go)
2+
3+
# Tags a release of the Go module (languages/golang) that `go get` can use.
4+
#
5+
# The module embeds three WASI guests built from Rust (encrypt/wasm,
6+
# encrypt/eql/wasm, auth/wasm). They are gitignored on main, and Go fetches a
7+
# module version as the files committed at its tag, so a tag on a main commit
8+
# would build and then fail at `NewClient` with ErrGuestNotBuilt. This
9+
# workflow builds the guests at the commit it runs on, commits them on a
10+
# release-only commit that no branch points at, tags that commit
11+
# `languages/golang/v<version>` (the prefix Go requires for a module in a
12+
# subdirectory) and pushes the tag alone. main stays free of binaries.
13+
#
14+
# The GitHub release it creates carries the EQL v4 SQL bundle the module's
15+
# EQL types are stored in, built from the same commit, so one release page
16+
# holds everything a user of that version installs. Run by hand:
17+
#
18+
# gh workflow run release-golang.yml -f version=0.1.0-alpha.1
19+
#
20+
# A version with a pre-release suffix is published as a GitHub pre-release.
21+
22+
on:
23+
workflow_dispatch:
24+
inputs:
25+
version:
26+
description: "Module version without the leading v, e.g. 0.1.0-alpha.1"
27+
required: true
28+
type: string
29+
30+
# The job that tags asks for write access itself; see
31+
# scripts/__tests__/workflow-publish-permissions.test.mjs.
32+
permissions:
33+
contents: read
34+
35+
concurrency:
36+
group: release-golang
37+
cancel-in-progress: false
38+
39+
jobs:
40+
release:
41+
runs-on: blacksmith-16vcpu-ubuntu-2204
42+
permissions:
43+
# Push the tag and create the release.
44+
contents: write
45+
env:
46+
VERSION: ${{ inputs.version }}
47+
# wasm:guest:test and the Go tests use the pinned test toolset.
48+
MISE_ENV: test
49+
steps:
50+
- name: Check the version
51+
run: |
52+
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
53+
echo "::error::version must be semver without a leading v, got '$VERSION'"
54+
exit 1
55+
fi
56+
57+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
58+
with:
59+
# The tag is pushed with the job's token.
60+
persist-credentials: true
61+
62+
- name: Refuse a tag that already exists
63+
run: |
64+
tag="languages/golang/v$VERSION"
65+
if git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null; then
66+
echo "::error::$tag already exists; a Go module version is immutable once fetched"
67+
exit 1
68+
fi
69+
70+
# No cache: this job publishes binaries, and a poisoned restore would
71+
# ship in them. scripts/lint-no-workflow-caching.mjs holds it.
72+
- uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4
73+
with:
74+
version: 2026.4.0
75+
install: true
76+
working_directory: .
77+
cache: false
78+
79+
- name: Add rustfmt and clippy to the pinned toolchain
80+
run: rustup component add rustfmt clippy
81+
82+
# The release builds, each with its import surface checked, and the
83+
# deterministic test builds the hermetic Go tests load.
84+
- name: Build the guests
85+
run: |
86+
mise run wasm:guest:build
87+
mise run wasm:guest:build:eql
88+
mise run wasm:auth-guest:build
89+
mise run wasm:guest:build:deterministic
90+
mise run wasm:guest:build:eql:deterministic
91+
92+
- name: Go tests against the guests being released
93+
run: mise run go:test
94+
95+
# eql_v4.version() reports `go-<version>`: the bundle is released with
96+
# this Go version, not as an @cipherstash/eql version. `--force`
97+
# because `--version` is not part of the build's cache key, so a cache
98+
# hit would re-serve whatever version an earlier build stamped; the grep
99+
# proves the stamp landed.
100+
- name: Build the EQL SQL bundles
101+
working-directory: packages/eql
102+
run: |
103+
mise run --force build --version "go-$VERSION"
104+
grep -q "'go-$VERSION'" release/cipherstash-encrypt-v4.sql \
105+
|| { echo "::error::the v4 bundle is not stamped go-$VERSION"; exit 1; }
106+
107+
- name: Commit the guests and tag the commit
108+
run: |
109+
set -euo pipefail
110+
tag="languages/golang/v$VERSION"
111+
guests=(
112+
languages/golang/encrypt/wasm/stack_encrypt_guest.wasm
113+
languages/golang/encrypt/eql/wasm/stack_encrypt_guest_eql.wasm
114+
languages/golang/auth/wasm/stack_auth_guest.wasm
115+
)
116+
: > guests.sha256
117+
for guest in "${guests[@]}"; do
118+
test -s "$guest" || { echo "::error::$guest was not built"; exit 1; }
119+
sha256sum "$guest" >> guests.sha256
120+
done
121+
cat guests.sha256
122+
git config user.name "github-actions[bot]"
123+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
124+
git checkout --detach
125+
# The guests are gitignored on main; -f adds them to this commit only.
126+
git add -f "${guests[@]}"
127+
git commit -m "release(golang): v$VERSION with its WASI guests" \
128+
-m "Built from $GITHUB_SHA by $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
129+
git tag -a "$tag" -m "Go module v$VERSION (built from $GITHUB_SHA)"
130+
git push origin "refs/tags/$tag"
131+
132+
- name: Create the GitHub release
133+
env:
134+
GH_TOKEN: ${{ github.token }}
135+
run: |
136+
set -euo pipefail
137+
tag="languages/golang/v$VERSION"
138+
cp packages/eql/release/cipherstash-encrypt-v4.sql eql-v4-install.sql
139+
cp packages/eql/release/cipherstash-encrypt-v4-uninstall.sql eql-v4-uninstall.sql
140+
{
141+
echo "Go module \`github.com/cipherstash/stack/languages/golang\` v$VERSION, built from $GITHUB_SHA."
142+
echo
143+
echo '```sh'
144+
echo "go get github.com/cipherstash/stack/languages/golang@v$VERSION"
145+
echo "go install github.com/cipherstash/stack/languages/golang/cmd/stashgen@v$VERSION"
146+
echo '```'
147+
echo
148+
echo "Values this version writes are stored in EQL v4 columns. Install EQL v4 into PostgreSQL with the attached \`eql-v4-install.sql\` (\`psql -f eql-v4-install.sql\`)."
149+
echo
150+
echo "SHA-256 of the embedded WASI guests:"
151+
echo '```'
152+
cat guests.sha256
153+
echo '```'
154+
} > notes.md
155+
prerelease=()
156+
if [[ "$VERSION" == *-* ]]; then prerelease=(--prerelease); fi
157+
gh release create "$tag" --verify-tag "${prerelease[@]}" \
158+
--title "Go v$VERSION" --notes-file notes.md \
159+
eql-v4-install.sql eql-v4-uninstall.sql guests.sha256
160+
161+
# The proxy fetches a version the first time it is asked for it; asking
162+
# here proves the tag resolves as a module before anyone depends on it.
163+
- name: Check that Go resolves the version
164+
env:
165+
GOPROXY: https://proxy.golang.org
166+
GOFLAGS: -mod=mod
167+
run: |
168+
set -euo pipefail
169+
for attempt in 1 2 3 4 5 6; do
170+
if go list -m "github.com/cipherstash/stack/languages/golang@v$VERSION"; then
171+
exit 0
172+
fi
173+
sleep 20
174+
done
175+
echo "::error::the Go proxy did not resolve v$VERSION"
176+
exit 1

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ Every npm package except EQL lives under `languages/typescript/`: packages in `l
9292
links are provenance only.
9393
- `packages/stack-auth`, `packages/stack-profile`, `packages/stack-kms`, `packages/stack-encrypt`, `packages/stack-encrypt-derive`, `packages/stack-guest-abi`: The Rust crates imported from `cipherstash/cipherstash-suite` with their history — `stack-auth` and `stack-profile` (published to crates.io, one version group), `stack-kms` (published to crates.io from 0.1.0, its own version group, re-exported by `stack-encrypt` as `stack_encrypt::kms`), `stack-encrypt` and `stack-encrypt-derive` (published to crates.io from 0.1.0, one version group; `eql-bindings`' `stack-encrypt` feature depends on them from the registry), and `stack-guest-abi` (`publish = false`). They are the members of the **root Cargo workspace**, with the three node binding crates below. See "Working on the Rust crates".
9494
- `languages/typescript/packages/auth`, `languages/typescript/packages/profile`, `languages/typescript/packages/stack-auth-wasm`: The node bindings of those crates. `@cipherstash/auth` (napi-rs v2) and its six `platforms/*` packages are published to npm from this repository by `release.yml` (`auth-artifacts`, `publish-auth`); a change to what it ships, the `stack-auth` crate included, needs an `@cipherstash/auth` changeset (`require-auth-npm-changeset.yml`). `@cipherstash/profile` and its platforms are private and never published; `@cipherstash/stack-auth-wasm` is private and builds the wasm that `@cipherstash/auth` ships. Their `build` and `test` scripts never invoke cargo; `build:native`, `build:debug` and `test:cargo` do.
95-
- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport` and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` builds the seeded TEST build the hermetic Go tests use; the `.wasm` files they embed are gitignored. The stack-encrypt guest has a second build with the EQL types (`mise run wasm:guest:build:eql`, cargo feature `eql`, linking `eql-bindings` by path; `wasm:guest:build:eql:deterministic` is its test build), embedded by `encrypt/eql` and registered on import, so a program whose generated code names an EQL type runs it (ADR-0007, amended). `encrypt/eql`'s types and `Types` table are generated from the EQL catalog by `eql-codegen` (`eql_gen.go`, written by `mise run types:generate` in `packages/eql` and drift-gated by `types:check` and `cargo test -p eql-codegen`). Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. There is no Go release process yet.
95+
- `languages/golang`: The Go module — the SDK `encrypt` with its generated-code support `encrypt/gensupport` and the policy packages `encrypt/policy` and `encrypt/policy/protosource`; the credential package `auth`; the generator `stashgen` and its command `cmd/stashgen`; and `internal` (the shared guest plumbing and the `record` wire model). A wazero host with no cgo. Its two WASI guests (`encrypt/guest`, `auth/guest`) are detached Cargo workspaces built by `mise run wasm:guest:build` and `mise run wasm:auth-guest:build`; `mise run wasm:guest:build:deterministic` builds the seeded TEST build the hermetic Go tests use; the `.wasm` files they embed are gitignored. The stack-encrypt guest has a second build with the EQL types (`mise run wasm:guest:build:eql`, cargo feature `eql`, linking `eql-bindings` by path; `wasm:guest:build:eql:deterministic` is its test build), embedded by `encrypt/eql` and registered on import, so a program whose generated code names an EQL type runs it (ADR-0007, amended). `encrypt/eql`'s types and `Types` table are generated from the EQL catalog by `eql-codegen` (`eql_gen.go`, written by `mise run types:generate` in `packages/eql` and drift-gated by `types:check` and `cargo test -p eql-codegen`). Generated `*_stash.go` files are committed and CI fails when `go generate ./...` changes one. Releases are cut by hand with `.github/workflows/release-golang.yml` (`gh workflow run release-golang.yml -f version=X.Y.Z[-pre]`): because the guests are gitignored on main and Go fetches a version as the files committed at its tag, the workflow builds them, commits them on a release-only commit no branch points at, tags it `languages/golang/vX.Y.Z` and pushes the tag alone, then attaches the EQL v4 SQL bundle to the GitHub release. Never tag a main commit by hand: `go get` would fetch a module with no guests.
9696
- `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README)
9797
- `languages/typescript/examples/*`: Working apps (basic, prisma, supabase-worker)
9898
- `docs/plans/*`: Internal design plans. User-facing documentation lives at https://cipherstash.com/docs (not in this repo).

‎scripts/__tests__/eql-suite-ci.test.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1770,6 +1770,7 @@ describe('every job that compiles Rust restores the shared cache', () => {
17701770
).toEqual([
17711771
'.github/workflows/_build-eql-docs.yml (publish-docs)',
17721772
'.github/workflows/_build-eql-sql.yml (build)',
1773+
'.github/workflows/release-golang.yml (release)',
17731774
'.github/workflows/release-postgres-eql-image.yml (build-sql)',
17741775
'.github/workflows/release.yml (prerelease-eql-npm)',
17751776
])

‎scripts/__tests__/lint-no-workflow-caching.test.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ const TARGET_WORKFLOWS = [
2828
'.github/workflows/release-plz.yml',
2929
'.github/workflows/release-postgres-eql-image.yml',
3030
'.github/workflows/tests-supply-chain.yml',
31+
// The Go module's release: it commits WASI guests built in the job onto
32+
// the tag `go get` fetches.
33+
'.github/workflows/release-golang.yml',
3134
]
3235

3336
const SCRIPT = resolve(

‎scripts/lint-no-workflow-caching.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@ const TARGETS = process.argv.slice(2).length
3535
'.github/workflows/release-plz.yml',
3636
'.github/workflows/release-postgres-eql-image.yml',
3737
'.github/workflows/tests-supply-chain.yml',
38+
// Commits the Go module's WASI guests on the tag `go get` fetches, so
39+
// a poisoned restore would ship in every Go program built from it.
40+
'.github/workflows/release-golang.yml',
3841
]
3942

4043
// `uses:` values that pull in the GitHub Actions cache directly.

0 commit comments

Comments
 (0)