The roc-automation manual

A repository involves three Roc compilers. Each has one job, and they are never interchangeable.

A maintainer chooses the second and observes the third. The first is hidden: blueprint fetches it when needed, as described in Get blueprint.

Blueprint has a compiler of its own because Blueprint is itself written in Roc. It has to evaluate Blueprint.roc before any environment exists, so it cannot take its compiler from the environment that file describes: that would be a bootstrap problem. Each blueprint release therefore fixes the one compiler it was built with.

Three compilers is more than anyone wants, and the arrangement is accepted as temporary. It follows from Roc having only nightly builds. Once Roc 0.1 is released, Blueprint and most repository tooling are expected to settle on that release, which leaves two compilers to think about: the released one that tooling runs on, and the nightly that packages are tested against.

roc-stable exists so that repository tooling keeps working when a nightly breaks something. The package deliberately floats, because the question a maintainer needs answered is whether the package works with the compiler users will install today. "Stable" means only that the repository does not move the tag without review. There is no shared registry of stable versions, and repositories need not agree.

"Latest nightly" means the most recent release published by roc-lang/nightlies. This model treats that as the last good build and does not check upstream CI separately.

CI installs that compiler as roc with the official roc-lang/setup-roc action, which is also how it is named on a contributor’s machine. The Blueprint environment provides roc-stable and no roc, so the two names never collide.

ci.yml tests the working tree. release.yml tests and publishes artifacts. nightly.yml tests what users already have. Each can fail without the others being wrong: a new nightly can break ci.yml on an untouched pull request, and nightly.yml can fail while the default branch is green because the fix has not been released. The three workflows describes each in full.

Most repositories are the simplest kind, and the model is at its smallest for them. A repository is a pure Roc package when all of these hold:

Such a package is expected to work wherever Roc does. A difference between targets is a compiler defect to report upstream, not something the package’s own CI is there to find. It therefore tests on one runner.

Everything else applies unchanged: the two compilers, the Blueprint environment, the Roc scripts, the three workflows, and what a release contains.

The cost is stated here so that it is a decision and not an accident: a compiler defect that appears on one target only is not detected by this package’s CI.

A package leaves this profile as soon as it gains behaviour that can differ by target, for example when it starts a process, interprets file paths, or depends on the width of a pointer. It then adds a runner for each target it claims, and takes on the matrix and the aggregate job described in Continuous integration.

Anything two repositories need identically belongs in roc-automation, referenced by full commit SHA. A repository keeps only what knows its own package.

Shared actions is the reference for each action.

Each setting has one job:

The two files divide the work. Blueprint.roc states which release is the tooling compiler and which tools are needed, where a reviewer can read it. Blueprint.lock pins the overlay revision that supplies that release’s download URL and hash, the package source, and each locked bundle.

Nothing that blueprint generates is committed. Its generated Nix files stay in .blueprint/, which the repository’s .gitignore lists.

Blueprint needs Nix on the machine, so install Nix first. There are then two ways to get the blueprint command. Whichever you use, take the same roc-blueprint release as the platform URL in the repository’s Blueprint.roc header.

A contributor needs Nix, the blueprint command, and a current nightly installed as roc, the way Roc is normally installed. Nothing else has to be set up.

blueprint is the outer command. Run it from an ordinary shell: there is no nix develop step first and no nested shell.

Inside the environment roc-stable is the pinned compiler, and the contributor’s own roc remains visible for package work.

Every job that runs repository scripts sets up Blueprint first, then installs the latest nightly, then calls a task:

A matrix names only runners Blueprint supports: x86_64 and arm64 Linux, and Apple Silicon macOS. It cannot include an Intel macOS runner. A platform can still cross-compile a host for that target in the builder job, but no job runs the repository’s scripts there.

The job needs no cache account and no token for this. A Nix cache is an optimisation a repository may add; a cache that requires id-token: write widens a test job’s token and must be an explicit choice.

A change to Blueprint.lock changes the tools every build uses. Where a repository fingerprints native build inputs, Blueprint.lock is one of the fingerprinted files; see Keep rebuild selection narrow and complete.

A repository that publishes several packages or platforms gives each its own root directory, such as package/ and tzdb/package/, or platform-web/ and platform-gui/. Each root is bundled, versioned and released together with the others in one release; see Several bundles in one release.

The roc: "…​" header field appears in exactly one place: the scripts under scripts/, where it names the same release as roc-stable. Nothing else is pinned. The package, a platform, the examples and every other Roc application carry no roc field, and the repository has no .roc-version file and no .github/roc-nightly.json.

The rule for the package applies to platforms as much as packages. roc check exits with an error on a warning, and a dependency whose header pins a different nightly produces a version-mismatch warning. A pinned platform therefore fails every application that floats, and a package cannot float until every platform its examples use has dropped the field.

The check script enforces both halves. It fails when a roc field or .roc-version appears outside scripts/, and it fails when a script’s pin differs from the tooling compiler; see Keep the script pins in step.

Every Roc application in the repository depends on the working tree by relative path. Pull-request CI checks them with the latest nightly compiler. That covers examples/ and also anything outside it: fuzz targets, benchmarks, documentation examples, test cases, and a site generator.

The package is a relative path. Every other dependency, including the platform, is an immutable release URL with its content hash.

These are not what the nightly workflow tests. They change with every pull request and may use APIs that no release has. The nightly workflow runs the examples archive attached to the latest release. In the archive the same example names that release’s exact bundle URL, and nothing else differs:

The release workflow writes the second form when it builds the archive; the repository only ever contains the first. See The examples archive.

The single exception is scripts/. A script never depends on the repository’s own package by relative path, because a script must keep working while the package is broken.

An example that needs more than one file is a directory: examples/report/ holds main.roc, its sibling modules and any data files it reads. A local helper package that several examples share sits beside them and is referenced by relative path.

Each entry point under scripts/ is an executable Roc application:

Automation is not written in Python, bash or PowerShell. A script that exists only to wrap one command is deleted in favour of a Task that runs the command.

Generated data that is committed has a script that regenerates it and a check that fails when the committed copy is stale. Rendered documentation is published as a release asset and a Pages deployment, never committed.

A bundle holds what a user of the package needs and nothing else: the package’s Roc modules and any data files they import. Fuzz targets, benchmarks and test modules stay outside the package root, so that roc bundle on the root produces the release artifact with no exclusion list.

The audience of an example is a user of the package who is probably not familiar with it. It is not a contributor.

An example is not a test, a benchmark or a fixture. Those have their own directories and their own standards. Code that exists to cover an edge case, to measure something, or to feed another tool does not belong under examples/, however convenient it is to put it there.

Manage examples with the care their position deserves:

The repository and its releases are rarely in step. Pull requests land continuously; releases happen now and then. At most commits the package in the repository is ahead of the last release.

An example in the repository must work with the package at that same commit, so it may use an API that no release has yet. A user reading it beside the latest release could copy code that does not compile for them. An example published with a release has the opposite property: it works with that release and will never change.

One set of files cannot be both. The repository therefore keeps examples that follow the working tree, and each release publishes a frozen copy of them that names that release.

Every example names the package by relative path, as described in Roc applications in the repository. A pull request that changes the package and breaks an example fails on that pull request.

Committed examples are never rewritten after a release. No release follow-up pull request exists, and the default branch never names its own release URL.

An example that only compiles proves little. Record what each example prints, and compare it on every run. Examples are run by the same driver as the integration tests; see Integration tests.

Each release attaches an examples archive named <name>-examples-<version>.zip, where <name> is the repository, or the package when the repository publishes several. It contains:

Nothing else in an example changes. The archived examples differ from the repository’s at the tested commit only in the package dependency, and the check script verifies that.

A user who wants a starter downloads the archive for the release they are installing. The archive is also the fixed input to nightly compatibility, which is why it carries its own expected output: the default branch’s specification describes the default branch, not the release.

The archive that is tested is the archive that is published. Nothing is rebuilt between the test and the upload.

Run the test with an empty Roc package cache, so that the bundle is fetched and verified and not found from an earlier run.

A pull request runs the release steps with a placeholder version and publishes nothing. Roc rejects 0.0.0 in a package URL, so the placeholder is 0.0.1-dry-run.

An archive is immutable, so it is checked, tested, built and run, and never passed to roc fmt. A later formatter change would fail the nightly check for a reason that no patch release can fix.

The check task runs all of these, so a contributor runs the same set with blueprint run check before opening a pull request.

A long fuzzing campaign or a full benchmark run never runs on a pull request. They take too long, their results vary from run to run, and a pull request should not wait on them or fail because of noise. They run on a schedule or on request, as described in Fuzzing and Benchmarks.

What pull-request CI owes them is a smoke run. A benchmark that has not been built since the API it measures changed will not run on the night it is scheduled. A few seconds per target on every pull request keeps each of them building and running, so the scheduled job measures and searches instead of discovering that it is broken.

Build and run with --opt=dev unless there is a reason not to. It compiles quickly, which is what a test run spends most of its time on, and the checks in this chapter ask whether the program is correct, not how fast it is.

Use --opt=speed only where the optimised build is the thing under test: a benchmark’s measured run, a long fuzzing campaign, or a release artifact that ships optimised. A benchmark’s smoke run in pull-request CI uses --opt=dev like everything else.

Run roc test once, on the root: package/main.roc for a package, platform/main.roc for a platform. Roc runs the expect tests of every module the root imports, transitively, so there is no need to list files or to run the command per module. A module that the root does not reach is either dead code or missing from the package, and either is worth knowing.

A repository with several roots runs roc test once on each.

An integration test runs a built program and looks at what it does: its output, its exit code, the files it writes. Organise these around an external driver and a list of cases, not as one program per test.

The driver is a Roc script under scripts/, and the cases live under tests/. The expected-output specification for examples, described in Record expected output, is one such list of cases run by the same driver.

Sometimes a case is broken for a reason that cannot be fixed today: a compiler bug, a dependency that has not been released, a platform limitation. Deleting the case loses it, and leaving it failing blocks every pull request. Skip it, and make the skip impossible to forget.

The same applies outside the harness: an example, benchmark or fuzz target that is switched off says why, in a TODO with an issue link, at the place it is switched off.

A harness is read far more often than it is written, usually by someone waiting for it or trying to find out what failed. Its output is part of its job.

Memory behavior is a quality of Roc code in its own right, and it is invisible unless it is measured. A change that keeps a reference alive a little longer can turn an in-place update into a copy of a whole list, on every call. The result is still correct, every test still passes, and the package is now several times slower for its users.

Most packages and platforms should therefore test on a platform that counts allocations, and hold the counts with ratchets.

Allocation counts are deterministic for a given compiler, which makes them a far steadier signal than timing. They run in pull-request CI with everything else; wall-clock benchmarks do not.

Unit tests and integration cases check the inputs someone thought of. Most bugs live in the inputs nobody thought of: the empty list, the string that ends in a delimiter, the two values that are equal, the length one past a boundary. A property-based test closes that gap. You state a rule that must hold for every input, and a tool searches for an input that breaks it.

roc-fuzz is that tool for Roc. It is a platform: a fuzz target is a small Roc application that names what values to try, what code to run, and what must be true afterwards.

Run roc fmt --check in pull-request CI, over every Roc source the package compiler builds, and roc-stable fmt --check over the scripts, whose roc field another compiler’s formatter would rewrite. It fails the pull request that introduces unformatted code, which is the only moment at which fixing it is cheap.

Do not run it in nightly.yml. A new nightly can change the formatter, and a formatting difference says nothing about whether a release still works. The check would raise an alarm that no patch release answers. When a new formatter does change the output, the next pull request sees it, and reformatting is a small pull request of its own.

ci.yml tests the working tree.

What runs on every pull request lists what the check task covers.

A pure Roc package runs this as one job on ubuntu-latest, and that job’s name is the required status check.

A repository whose code can behave differently by target runs it as a matrix, one job per runner, and ends with a single aggregate job that requires every matrix job to have succeeded. The aggregate job’s name is the required status check, so the ruleset does not need editing when the matrix changes.

A platform adds the host-bindings check described in Host bindings. It runs here and nowhere else.

A pull request can fail because a new nightly arrived, with no fault in the change itself. Compare with the latest nightly.yml run and with the default branch before treating a failure as a regression in the pull request.

release.yml builds what a release would contain, tests those exact bytes, and publishes them once. A maintainer dispatches it from the default branch with a version. A pull request runs the same build and tests as a dry run and publishes nothing.

nightly.yml answers one question each day: does the release users download today still work with today’s compiler? A failure means the package or platform needs a patch release.

The archive is immutable, so a failure is never a reason to change it. The fix is a patch release that works with the new compiler.

docs.yml has two jobs.

The build job checks out the repository, builds the site, and uploads it as a Pages artifact. A repository with an AsciiDoc manual uses actions/build-docs, which also produces the PDF. A pull request runs this job, so a broken manual fails review, and the artifact can be downloaded to preview the change.

The deploy job runs only for the default branch. It has pages: write and id-token: write, uses the github-pages environment, checks out nothing, and deploys the artifact the build job produced.

Fuzz targets are written with roc-fuzz; see Property-based tests with roc-fuzz for why and how.

fuzz.yml runs each target for a fixed duration on a schedule. It restores and saves the corpus through the Actions cache, uploads any reproducer as a workflow artifact, and fails when a target fails. Fuzz targets are Roc applications that depend on the working tree, so the latest nightly builds them.

ci.yml gives every target a smoke run: it builds the target and replays the committed corpus, which is fast and deterministic. That keeps the targets building between scheduled runs. The scheduled run is the only place new inputs are searched for, and the only place a target is built with --opt=speed.

bench.yml measures on a schedule and on request, never on a pull request. ci.yml gives every benchmark a smoke run, one small iteration built with --opt=dev, so that a benchmark cannot fall behind the API it measures.

A measurement that depends on the compiler, such as an allocation count, is compared as a ratchet: the build fails when the value is worse than the recorded ceiling, and a maintainer lowers the ceiling when it improves. It is never compared for equality, because the compiler floats and an exact value would fail on a compiler that did better.

Platforms that consume prebuilt native inputs have a producer workflow and a publisher workflow. These are the only route by which native build inputs are released. Maintain a platform explains when a platform needs them, and Publish linker inputs from a pull request specifies both.

A host is compiled against bindings that roc glue generates from platform/main.roc: a Zig, Rust or C description of the types and entry points the Roc side expects. The compiler generates them, so a new nightly can change them when nothing in the repository changed.

The bindings are committed. The host build reads the committed file and never runs roc glue itself, so a host builds the same way on every runner and a reviewer sees every change to the interface as a diff.

A platform advertises a set of targets, and each workflow validates all of them. The usual shape is one builder job that cross-compiles for every target, followed by a matrix of runner jobs that execute the result on each one.

A repository that publishes more than one platform, such as a web platform and a native platform that share an engine, gives each its own root, its own bundle and its own examples archive, as in Several bundles in one release. Sharing an engine does not make two platform APIs or their application roots interchangeable. Give examples separate roots and package URLs even when they share application modules.

A template’s examples are the product: they are what a user copies. A template follows the model without exception. Its examples depend on the working tree by relative path, and each release’s examples archive is the starter a user downloads.

Platforms need native builds before Roc can link an application, and native builds are where CI time goes. A maintainer has a limited budget of runner minutes and of patience, and spends it well only by planning what gets built when, and by watching how that changes as the project grows. This section is about building each thing once, reusing it until it changes, and testing and publishing the same bytes.

All of these files can eventually reach a linker, but they have different owners and rebuild triggers. Name the categories explicitly in scripts, locks and docs.

A host edit can require new host archives while reusing the existing external linker inputs. Rebuild an engine archive only when its own inputs change; if a producer groups multiple outputs, document that granularity. A new nightly invalidates host outputs only when the compiler contributes to their build identity; a change to the generated bindings is handled as described in Host bindings.

For platforms that package macOS interfaces, review the required catalog before generating and validating .tbd files. That generation belongs inside the external linker-input cycle. When released separately, publish the generated files as immutable inputs. For a static host archive, these files normally serve Roc’s final link rather than host compilation. A producer that itself links executables or shared libraries may also consume linker interfaces. Record its actual SDK, headers, interfaces and native build tools in its identity; do not assume the host build and the linker inputs have no dependencies.

For a platform with a separate host step and an independent linker-input release, the flow is:

An unresolved symbol during the application link is evidence to investigate. Confirm the library, symbol and supported target before changing the catalog; missing project symbols, mismatched archives and ABI errors can produce similar failures. Do not invent an export or expand the catalog automatically to make a test pass. Producer validation can catch mistakes earlier, but a successful host build alone does not establish that Roc can link the final application.

Commit reviewed lock data with each dependency selection. Include the artifact name, target, exact release location, cryptographic digest such as SHA-256, byte size, and expected archive contents or extraction boundaries. Record available source revision and producer build-input fingerprint separately from the archive digest. The fingerprint answers whether a build can be reused; the digest identifies the exact bytes a consumer accepts. Neither a version label nor a fingerprint alone verifies a downloaded archive.

Recompute freshness fingerprints where the repository owns or vendors the producer inputs, such as its own host source. For external binaries, consumers verify the reviewed selection, digest, target and inventory; they need not fetch upstream source or install its toolchain to recompute the producer’s fingerprint. Recorded producer metadata remains a claim subject to the chosen provenance policy.

Final Roc bundles have a compiler-defined content identity: preserve the hash that roc bundle puts in the filename, and use one filename in both localhost and published URLs. Roc uses its base58-encoded BLAKE3 hash to verify the downloaded bundle. An additional SHA-256 in release metadata is useful but cannot replace that URL hash. See the Roc bundle implementation and download contract. Application users consuming that bundle need no separate native-input fetcher.

Consumers should resolve the locked artifact from a local cache, a mirror or the recorded release URL, check size and digest before extraction, and reject a mismatch, including on cache hits. Extract into fresh staging with bounded member counts and expanded sizes. Accept only declared regular files and directories with unique, portable paths; reject escapes, path collisions, links and special files. Validate the complete inventory before making the staged result available, and do not trust an old extracted tree solely because its cached archive verified. Keep licenses and required runtime files in the declared inventory. Fail clearly when a required artifact is unavailable or stale; an ordinary consumer must not silently rebuild it or pick a newer release.

The reviewed lock is the trust anchor. A checksum downloaded beside an archive from the same mutable location does not independently authorize its contents. A matching digest establishes equality with reviewed bytes, not their safety, source origin or correctness. Review the initial artifact selection and subsequent lock changes as dependency changes.

Hash verification is local and should work without a GitHub API call, token, attestation service or network connection when the selected bytes are already available. Downloading a missing artifact still requires a source of those bytes. This reduces service dependencies; it does not make uncached downloads offline. Apply the same principle to other downloaded inputs, including build tools where practical, while keeping the required trust policy explicit.

An attestation can bind an artifact digest to claims about its producer, workflow, source revision and build. Publish it for users who want to verify that provenance. Such verification must check the expected signer/workflow identity, source and subject digest under a stated policy, not merely that some signature exists. Keep ordinary locked consumption independent of that service check unless the consumer explicitly adopts a stricter provenance policy. Verification required by an adopted policy must fail visibly rather than silently downgrade to hashes. Provenance does not inherently require an online check on every run: GitHub supports offline verification using previously obtained attestation bundles and trusted roots. Define how that verification material is obtained and updated when adopting such a policy.

Describe only the evidence that was actually produced. A packaging workflow that downloads and bundles an archive can attest to that assembly; its attestation does not establish how the downloaded archive was compiled. Preserve the original producer evidence and identify the selected dependencies in the package manifest. A source revision in a lock is a recorded claim until supported by the producer’s evidence. Attestations do not by themselves prove reproducible builds, complete test coverage, or absence of defects.

Publish each dependency release under a unique, immutable identity with the exact validated archives, lock data, licenses and available provenance. Do not replace assets or move tags. Where the hosting service supports enforced release immutability, enable it and verify the resulting state; a naming convention alone does not enforce immutability. Hash checks remain necessary even with immutable hosting. On GitHub, stage an immutable release as a draft, attach all assets, verify the complete inventory and tag commit, then publish. An interrupted draft may resume after existing assets match the recorded candidate. A complete published release needs only verification and any remaining follow-up; an incomplete published immutable release cannot accept missing assets and needs a new release identity. Changed candidate bytes also need a new identity. Preserve the original evidence and revalidate starters whenever their final URLs change.

Use the smallest lifecycle that corresponds to the changed ownership boundary:

For a stale linker-input lock, stage the material change in a same-repository pull request first. An unprivileged producer run at that head can build, test and attest a candidate without publishing. Then dispatch the trusted publisher from the default branch with the pull-request number. It reruns the producer at the exact head, verifies the candidate, publishes the immutable linker-input release, and adds a signed lock-only commit to the pull request. Revalidate the updated pull request against the released lock before merging. A platform bundle is a separate, later release that uses the selected lock. Publish linker inputs from a pull request defines the admission and review checks.

An input fingerprint mismatch must be explicit. For a host, the read-only host job simply builds it, because host source commonly changes with the pull request. For a locked linker-input release, routine validation fails with instructions to run the producer and publisher cycle. It must not bootstrap a replacement as a side effect of a cache miss. An implicit rebuild would substitute unreviewed bytes for the dependency the lock selects, make results depend on whichever runner missed its cache, and hide that the declared dependency is stale.

Routine consumers need only the lock schema, a downloader/cache, digest and archive validation, and the selected extracted files. They do not need a native SDK, linker-input generator, publication token, attestation lookup, or knowledge of how the archives were produced. Keep producer jobs in their own workflow and path scope; do not call them from general CI merely to populate a cache.

Every cache read is untrusted until the archived bytes match the locked size and SHA-256. A cache miss downloads the exact locked release asset. A download failure fails the job. A digest mismatch removes or ignores the bad entry and fails closed; it never selects another release. Extraction and manifest checks happen after the archive hash succeeds and before files become visible to the build.

Derive cache keys from the locked content identity rather than a branch, workflow run, or mutable release label. This prevents unrelated revisions from sharing a slot merely because their human-readable names match and makes identical reviewed bytes reusable across PRs. Still rehash a cache hit: cache keys select storage but do not authenticate its contents, and a poisoned, truncated, or incorrectly restored entry can otherwise bypass the download-time check.

Use merge commits for pull requests whose evidence names exact commits. A merge commit keeps the attested producer commit and the publisher’s signed lock-only commit reachable under their original identities. Squashing manufactures a different commit and discards that correspondence. A maintainer may still tidy an ordinary development branch before review; the automation must not depend on history being rewritten after it has bound evidence to a SHA.

Keep the authorities distinct:

This split is what makes running candidate build code acceptable: a compromise of that job cannot write a release or a branch. The publisher has powerful credentials, so it accepts only inert declared files and never executes the pull request. Least-privilege permissions reduce what is possible if the pinned action or the hosting account is compromised; they do not make unreviewed code safe to run in that job.

A shared action is tried from a reviewed roc-automation pull request by pinning the caller to that pull request’s full commit SHA. A branch name or abbreviated SHA is never pinned. If review changes the shared implementation, pin the new commit and repeat the trial.

Producers computing reuse identities must include every input that can affect an output: relevant source paths and contents, generated inputs, dependency locks, build recipes, tool versions, target configuration and build flags. Record file paths and modes as needed to distinguish renames, deletions and symlinks. Validate the permitted source-file kinds. Include relevant environment and SDK identities; an unpinned runner image or ambient library can change output without a source edit. Where the toolchain comes from Blueprint, Blueprint.lock is one of those inputs, so a lock update that changes the toolchain makes the selected outputs stale. Use a versioned fingerprint recipe and compare the same input definitions. A whole-commit identity, together with the non-source inputs above, is a conservative starting point, but causes needless rebuilds for unrelated edits. Narrow the source selection only after testing the input inventory. Include the source revision separately for traceability.

Treat workflow triggers and fingerprints as different controls. Path filters decide when to run a producer audit; fingerprints decide whether the selected published outputs still correspond to current inputs. A test-harness edit may justify rerunning an audit without requiring a new dependency release. Trace shared scripts and generated inputs transitively so a narrow filter cannot hide a real build change. For repository-owned inputs, record the published fingerprint in lock data or a digest-bound manifest so a shallow checkout can compare current inputs without fetching an old producer commit. A stale host blocks reuse; PR validation may explicitly build a new candidate in a read-only job without publishing it.

For a narrowed fingerprint, require meaningful checks for both directions: a relevant source, tool pin or build-option change invalidates reuse, while an unrelated example or documentation change preserves it. Check archive digest rejection and target/path confinement. Exercise final linking against reused artifacts; a selector test alone does not

Once the linker inputs are locked and the host job has built or restored the host, the rest of the release needs only the latest nightly to bundle and link applications, the artifact verification step, and the runtime dependencies of its tests. It downloads and hash-verifies the locked linker inputs. SDK generators belong in the linker-input producer; a stale lock sends the maintainer back to that cycle.

Bundle once, then pass those exact archives to the target runners. Each runner serves the applicable bundles on a loopback address and runs the archived examples against them, as in Build and test the exact archive. Validate every advertised target before publication. Check package size limits and target contents early, so that publication does not discover that a bundle cannot carry its advertised hosts.

Keep preparation, validation and publication connected by recorded artifact digests and the exact source SHA. Record archive digests, selected dependency identities, the source revision and the compiler versions in the release notes. The remaining steps are those of every release; see The order of a release.

The unprivileged producer workflow builds and tests every supported target from the PR branch. It uploads one flat Actions artifact containing top-level regular files only:

The manifest is canonical JSON with this envelope:

Use the platform’s complete supported target set rather than publishing a partial replacement under the same contract. The input fingerprint covers every source, recipe, tool pin, generated input, target option, and other value that can affect the archives. It determines whether the selected release is current for the working tree; each asset SHA-256 identifies the exact bytes.

The producer must have no release, repository-write, or pull-request-write permission. Generate GitHub build-provenance attestations for the manifest and each target archive. Producer jobs may compile and execute PR code because they do not possess publication authority.

The platform owns a small workflow_dispatch publisher workflow on its default branch. That workflow uses the actions/publish-build-inputs composite action from roc-automation at one reviewed full commit SHA and supplies only:

Give that job actions: write, attestations: read, contents: write, and pull-requests: read; set all other permissions to none. A typical caller is:

The composite action obtains its controller implementation from that exact roc-automation revision. Its privileged job does not check out the platform PR, execute platform scripts, import candidate modules, or source files from the candidate artifact.

The controller requires a manual dispatch on the live default-branch commit. It resolves the open PR, dispatches the named producer workflow at the exact current PR head, captures the resulting run, and rejects a run whose repository, event, workflow, ref, SHA, or conclusion differs. It validates the artifact’s complete file set, bounded extraction, manifest schema, target set, byte sizes, and hashes. It then verifies every attestation against the expected repository, producer workflow, source ref, and source SHA.

The release tag is the configured prefix followed by -sha256- and the SHA-256 of the exact manifest bytes. The controller creates a draft, uploads the manifest, generated lock, and declared target archives, verifies their complete names and sizes, re-downloads every release asset into a clean directory, verifies its SHA-256 against the candidate, then publishes. Existing mismatched tags or releases are rejected; an interrupted draft can be resumed only when every published byte matches the candidate. Enable immutable releases in the platform repository.

actions/publish-build-inputs is the single supported linker-input publication contract. Keeping one path matters because archive admission, draft recovery, attestation verification, immutable publication, and lock adoption are one trust boundary; parallel publishers would duplicate security-sensitive policy and could silently diverge.

Finally, the controller creates one lease-guarded, GitHub-signed commit on the PR branch. It modifies only the configured lock path and verifies the resulting signature, file set, parent, and live PR head. Any competing branch update stops publication adoption rather than being overwritten.

The signature establishes the commit creator and integrity; the lock-only shape limits what that privileged identity can change. Neither protection substitutes for the other. The lease prevents the publisher from attaching a valid lock to a newer, unverified PR head or overwriting maintainer work that arrived during the release operation.

The optional producer-run action input selects an existing successful producer run instead of dispatching another build. The run must be a completed successful manual dispatch of the configured workflow, from the same repository, branch, and exact current PR head. Recovery repeats candidate inventory, content, and attestation verification; it does not reuse a prior admission decision.

Expose producer-run as an optional string in the trusted default-branch caller and pass it through to the action. Leave it empty for a new build. A moved PR head requires a new matching producer run.

Draft recovery searches all release-list pages. New drafts use the release ID returned by creation, without requiring immediate visibility in tag or release list projections. Asset downloads use their numeric IDs, so a draft needs no published Git tag. Every recovered asset is downloaded and hashed before the same release ID is published and checked for immutability. Unexpected or partial asset sets fail without replacement or deletion.

The generated lock records the manifest identity, source identity, input fingerprint, release, repository, and every target archive’s filename, SHA-256, and size. Publication and lock creation are one admission transaction, but the lock is not adopted until the updated PR passes its required checks and is merged.

Review the PR as a dependency change:

Do not rebuild, copy, retag, or promote the release after merge. The merged lock permanently selects the PR-built bytes. If source or build inputs change again, produce a new candidate and content-derived release. Byte-identical recovery may reuse the same content identity; changed bytes require a new identity.

Keeping the PR-built release is what preserves the chain from source SHA through producer tests and attestations to the reviewed lock. Rebuilding on the default branch would create different bytes with different evidence even if the source appeared equivalent, while promotion would add ceremony without strengthening a content-derived identity. Permanent releases consume storage, but avoid ambiguity about which candidate was actually admitted and support later audit or rollback.

Fork pull requests cannot receive the signed lock commit. Move an accepted change to a same-repository branch before publication. Do not grant a fork or PR workflow write credentials as a workaround.

Ordinary pull requests, nightly compatibility runs, local builds, and platform release assembly read the committed lock. They restore or download each selected archive, recompute size and SHA-256 even on a cache hit, validate the archive and manifest, and install it through fresh staging. They do not call the attestation service and do not fall back to a source build when the cache is empty.

A cache key is an optimization derived from the reviewed content identity. The lock, not the cache key or release name, authorizes bytes. A missing archive is a download/cache failure; a stale input fingerprint is a request for an intentional new linker-input release. See Separate admission from routine use for the distinction between admission evidence and routine integrity checks.

A lock update moves the overlay revision, the package source and tool versions. It never changes which release is roc-stable, because that tag is written in Blueprint.roc. It does not change the blueprint binary or the platform URL.

Where the repository fingerprints native build inputs, a lock change can make those inputs stale. ci.yml reports that, and the fix is a new linker-input release in the same pull request; see Choose the correct maintainer path.

This is a maintainer’s decision for each repository. Repositories need not agree.

A release’s blueprint binary must be used with that release’s platform URL. actions/setup-blueprint reads the release from that URL, so the URL is the only place to change:

No workflow file names the Blueprint version or a checksum.

Contributors then download the binary from the same release.

See Upgrade the bindings.

Protect the default branch with a ruleset:

Verify the rules with a real pull request: a failing check must block the merge, and a check name that no job produces must be noticed before it is relied on. If a required name identifies both a check run and a commit status, GitHub requires both.

Platform repositories that publish linker inputs allow merge commits. The publisher binds its evidence to exact commit SHAs, and a squash would replace them; see Preserve reviewed history and authority.

Keep a weekly github-actions entry in Dependabot. Shared actions are pinned by full SHA, and Dependabot proposes each new one as a pull request. Review it like any other dependency update, and never replace a full SHA with a branch or tag.

Enable private vulnerability reporting and keep SECURITY.md accurate. Project-practice evidence lists what else a public project should be able to show.

The check-settings task of roc-automation reads a repository’s settings from GitHub and reports each line of this chapter as passing or failing. Run it from a checkout of roc-automation and name the repository:

Three answers only a maintainer can give are flags:

Each failing line is followed by its fix: the settings page to change, or the gh api command that changes it. A setting that GitHub would not show is reported as unknown, never as passing. The task exits with an error while any line fails or is unknown.

Record a link for each item in the final pull request.

A claim about the repository is only as good as the check behind it.

Installs Nix and the blueprint binary that Blueprint.roc names, so that blueprint run <task> works in the next step. It builds nothing.

The call takes no inputs. The action reads the roc-blueprint release from the platform URL in the checked-out Blueprint.roc, and it records the reviewed SHA-256 of every binary of each release it installs. Blueprint.roc is therefore the one place a repository names its Blueprint release, and a workflow cannot disagree with it.

Outputs are blueprint-path, the absolute path of the installed binary, system, the release system name chosen for the runner, and version, the release that was installed.

The recorded checksums live in actions/setup-blueprint/releases.json, one entry for each roc-blueprint release, copied from that release’s blueprint.sha256 file. A new roc-blueprint release is reviewed once, in the pull request that adds its entry there, and reaches a repository when that repository moves its reference to the action. The reference is a full commit SHA, so the recorded checksums are pinned by the same review as the action’s code.

A release the referenced revision does not record fails the step, unless the caller supplies a sha256-<system> input for the runner. Use those inputs to install a release ahead of the action, such as a release candidate. A system for which no binary is released also fails.

The action downloads the binary for the runner’s system into a private temporary file, compares its SHA-256 with the reviewed value, and only then makes it executable and puts it on PATH. A mismatch fails the step and installs nothing. It takes no token and needs no cache account. The blueprint binary states what the checksum does and does not establish.

The package compiler is installed by the official roc-lang/setup-roc action, not by an action in this repository. Reference it by full commit SHA like any other.

It installs the compiler on PATH as roc. With nightly-tag empty it installs the latest release of roc-lang/nightlies; with a tag it installs that release.

A workflow with more than one job resolves the latest tag once, in its first job, and passes it to every job through nightly-tag, so that one run uses one compiler:

actions/nightly-report and actions/publish-release are Roc scripts in roc-automation, scripts/nightly_report.roc and scripts/publish_release.roc, written as Write automation as Roc scripts describes. Each runs from source in the calling job, from the action’s own copy of roc-automation at the referenced commit. The action:

roc-automation’s Blueprint.lock at the referenced commit pins what the task starts: roc-stable, which runs the script, the platform the script is built on, the gh CLI, which makes every request to GitHub, and coreutils. The full SHA in the uses: line therefore fixes the script and everything under it. Nothing comes from the calling repository: its Blueprint.roc is not read, and the binary is installed in a directory of the action’s own and is not put on PATH, so a blueprint the job set up earlier is left as it was.

The script is given the action’s inputs and the token in its environment, never as arguments. gh reads the token from GH_TOKEN and sends requests to the GitHub host it is configured for, which is GitHub.com unless the job sets GH_HOST.

These actions need a runner Blueprint supports, which is x86-64 or arm64 Linux or Apple Silicon macOS, and python3 for the installer, which GitHub’s hosted runners provide. On a runner with an empty Nix store, installing Nix and downloading the environment is most of the job’s time: the environment is about a gigabyte once unpacked, so allow a minute or two. The script itself finishes in seconds.

Keeps the one tracking issue of a nightly compatibility workflow. It checks out nothing from the calling repository and runs none of its code.

Outputs are action, which is opened, commented, closed or none, and issue-number, the issue that action concerned. issue-number is empty when action is none.

The tracking issue is the open issue whose title equals title exactly and whose author is a bot account. The action never comments on, closes or reopens any other issue. An issue with the same title that a person opened is ignored, as are a pull request and a closed issue.

The issue body and every comment name the release and the nightly and link to the workflow run. Tags are limited to 100 letters, digits and ., _, +, /, - characters, and a title to 256 characters with no control, format or private-use characters. A malformed input, or an empty token, fails the step before any request is made.

The action reads the open issues a page at a time. A listing it cannot read in full, or a record in it that is not an issue record, fails the step: it never opens an issue while it cannot tell whether one exists.

The calling job needs issues: write and no other permission. It has no checkout step, and it passes the action only the step outcome and the two tags, never text produced by the examples. Reporting states what the calling workflow must provide, and Actions that run a Roc script what the action needs of the runner.

Renders a repository’s docs/*.adoc sources as an HTML site and a PDF manual with a shared theme, Roc syntax highlighting and Mermaid diagrams. It can also place compiler-generated API documentation under site/api.

Outputs are site-directory and pdf-path, both absolute paths.

The action needs Docker and Python on the runner, which GitHub’s Ubuntu runners provide. A replacement theme directory must contain docs.css, docs-theme.yml, mermaid-config.json and fonts/. Write for the shared renderer lists what the renderer expects of the sources.

Publishes one release from files an earlier job built and tested. It stages them in a draft, reads every asset back and compares it with the tested file, and only then publishes. It checks out nothing from the calling repository and runs none of its code.

The job names the release environment, holds contents: write and nothing else, and has no checkout step. Its only inputs are the artifact the build job uploaded and the test jobs verified. What the assets are, how they are built and tested, and any attestation of them stay in the repository’s earlier jobs.

Outputs are release-url, the URL of the published release, and digests, the path of a listing of the published assets in the format sha256sum writes and sha256sum --check reads.

The tag is the bare version, without a v. A repository that publishes a second, independently versioned package gives that package’s releases a name with the tag input, such as kit-0.1.0. The tag must end with the version, so the two cannot disagree.

The action does the following, in this order, and stops at the first failure.

Nothing is public before the publish step. With immutable releases enabled, publishing a draft is the moment its tag and assets become permanent, which is why every check comes before it. A failure after the draft exists leaves the draft unpublished and the tag uncreated; the error names the draft. Recover an interrupted publication says what to do with it.

The action does not adopt an existing draft, replace an asset, or add to a published release. Once it has created the draft, every request names that draft by its numeric identifier, never by tag. It publishes the notes file as written and does not ask GitHub to generate notes: release notes are authored, as Write the release notes describes.

A glob in assets is a path relative to the workspace. Within one path segment matches any run of characters and ? any one character, and neither matches the dot at the start of a name. . segments are ignored. Nothing else is a pattern: *, [, a backslash, a .. segment and an absolute path are each an error, so a glob names only paths under the workspace.

Every request is a gh api call. gh adds the token to requests for the GitHub host and does not repeat it when GitHub redirects an asset download to the storage host that serves the bytes. A repository without immutable releases fails the last step, after the release is published; Releases lists the setting. Actions that run a Roc script states what the action needs of the runner.

Publishes native linker inputs built on a same-repository pull request as an immutable, content-addressed release, and commits only the resulting lock to that pull request. The job that holds release credentials never checks out or runs the pull request’s code.

Publish linker inputs from a pull request specifies the producer, the caller workflow and its permissions, recovery, and review.

An attestation answers who or which workflow produced an artifact and from which source context. A content hash answers whether the bytes being consumed are the exact bytes that were reviewed. These checks belong at different stages:

The reviewed hash is the trust anchor for ordinary builds after adoption. Attestation does not replace content verification, and repeating the same remote attestation lookup does not strengthen the identity of already pinned bytes. Admission asks whether the producer identity and source are acceptable; routine use asks whether storage returned those admitted bytes. Keeping those questions separate avoids turning every build into an online provenance-policy decision while still detecting corrupted or substituted downloads and cache entries.

Routine CI and local builds must not call a remote signing, transparency, or attestation service when a reviewed content hash is available. This avoids making builds depend on service availability, rate limits, authentication, or a network response for evidence already evaluated during adoption.

A routine consumer should:

If the digest does not match, fail without extracting, executing, or installing the artifact. Do not fall back to a floating URL, a newly discovered release, or a remote attestation lookup.

Use an attestation service during release publication, explicit lock adoption, security investigation, periodic provenance audit, or manual verification by a downstream user. Export attestation bundles with releases when practical so that provenance can be checked offline and retained independently of the service.

If policy requires provenance verification on every run despite a reviewed content hash, make that exceptional network dependency explicit and separate it from the ordinary validation path. Document its availability and credential requirements and do not describe it as content-integrity verification.

Before adopting a released artifact, record evidence that:

After adoption, a pull request that changes any URL or digest is a supply-chain change and receives the same review as a dependency update.

A same-repository pull-request release is admissible when a trusted default-branch publisher binds it to the exact branch SHA and producer workflow, verifies its attestations, and commits only the resulting content lock. Merging that reviewed lock is the adoption event. Routine consumers then use the same local hash checks as for any other release; they do not query provenance again.

The publish job accepts only a manual dispatch on the default branch, uses the event commit throughout, and consumes the artifacts of its own run. It never checks out the repository, so a script changed in the tested commit cannot run with release credentials.

The nightly compatibility workflow has no contents, pull-request, actions or status write access in any job. It cannot commit, merge, dispatch or publish. Its report job runs actions/nightly-report at a full commit SHA and checks out nothing. It receives only the outcome of the examples step, the nightly tag and the release tag from the test job, never text produced by the examples under test. It edits a single tracking issue, identified by its exact title and a bot author. Every workflow in a repository shares the GitHub Actions bot identity, so that test excludes issues opened by people and does not prove which workflow opened the issue.

No workflow in the model opens a pull request, approves one, or merges one. Every change to the repository is a maintainer’s pull request under the repository’s own rules.

Blueprint.roc names the release tag used for repository tooling, and Blueprint.lock pins the overlay by revision and content digest. Changing the tooling compiler is therefore a reviewed source change. Nix verifies the compiler archive against the hash the pinned overlay revision records for that tag. This is content integrity under a reviewed hash, as in Released artifact verification; it is not provenance for the upstream compiler build.

Bundles listed under RocPackages are locked the same way. A bundle a script names and the environment does not list is downloaded by Roc, which checks it against the content hash in its URL.

The package compiler is the latest published nightly and is not pinned. It is installed by the official roc-lang/setup-roc action, referenced by full commit SHA, from a roc-lang/nightlies release over HTTPS. That action does not check a nightly download against a digest, so the compiler’s integrity rests on GitHub’s release hosting and the action’s pinned revision. This is accepted because the nightly only ever runs in jobs that hold no write access. A workflow resolves the moving release once and passes the tag to every job. Release notes record the version used.

actions/setup-blueprint installs Nix, through an action referenced by full commit SHA, and downloads the prebuilt blueprint binary from a roc-blueprint release. It builds nothing. Before the binary runs, the action checks it against a reviewed SHA-256 and fails on a mismatch. Routine CI verifies that reviewed hash locally and does not call an attestation service. The hash establishes which bytes run; it is not provenance for the roc-blueprint build.

The reviewed hashes are recorded in the action, one set for each roc-blueprint release, and are reviewed in the pull request that adds them. A caller references the action by full commit SHA, so the hashes it trusts are fixed by the same reference as the code that checks them. A caller may supply a hash of its own for its runner, which then takes the place of the recorded one.

A release’s binary must be used with that release’s platform URL in Blueprint.roc, so the action takes the release from that URL. The file is candidate content in a pull request, and that is safe: the version it names can only choose among releases whose hashes are already reviewed. A version the action does not record, with no hash from the caller, fails the step.

The action accepts only a release version, from its version input or from Blueprint.roc, and builds the download URL itself, under the roc-blueprint releases of this project, so neither can redirect the download. The binary is written to a private temporary file and becomes executable and visible on PATH only after its hash matches. A mismatch, a release with no reviewed hash for the runner, or a system with no released binary fails the step and installs nothing.

The binary evaluates Blueprint.roc with a Roc compiler of its own. It uses a roc on PATH only when that is exactly the nightly the binary was built with. Otherwise it fetches that nightly through Nix from a roc-overlay revision pinned inside the binary, and Nix verifies the archive against the hash that revision records. The ROC environment variable overrides this selection.

The action takes no token as an input. The Nix installer it runs reads the job’s default token and configures Nix to present it to GitHub when it fetches from there. A cache that requires id-token: write widens a test job’s token and must be an explicit caller choice, never a default.

The build job of docs.yml runs repository sources through actions/build-docs with contents: read. The deploy job holds pages: write and id-token: write, runs only for the default branch, checks out nothing, and deploys the artifact the build job uploaded. A pull request can build the site and cannot deploy it.

The pull-request linker-input publisher is a separate controller action for inert, fully declared files produced by a caller’s unprivileged build jobs. A privileged consumer workflow invokes the controller at an exact reviewed SHA. Caller source is never checked out, imported, sourced, or executed in its privileged job. Publication requires manual dispatch on the caller’s live default-branch commit. The controller validates the complete regular-file set and content identities, verifies the producer’s attestations, refuses mismatched existing tags/releases, re-downloads and hashes the complete draft asset inventory, and requires immutable-release enforcement after publication. See Trusted publisher contract for the caller contract.

Consumers use reviewed content hashes as the runtime identity of released binary inputs. Routine CI verifies downloaded and cached bytes locally before extraction or execution. It must not depend on a remote signing, transparency, or attestation service when a reviewed hash is available. Provenance attestations are verified when a new release or lock is adopted, during an explicit audit, or by a downstream verifier. See Verify released artifacts for the complete admission and consumption policy.

roc-automation also contains actions/nightly, the reusable update-roc-nightly.yml and check-config.yml workflows, and actions/check-release. They are not part of the model this manual describes. This section is the trust reference for that code: read it before changing their behavior or permissions.

Consumers pin both reusable workflows to a reviewed full SHA. Each shared workflow pins the controller action and checkout action to full SHAs. The controller source runs from github.action_path; configuration and git operations use the caller’s GITHUB_WORKSPACE. Consumer Python files are never imported by the controller.

The scheduled/manual caller must run on the default branch. Prepare records that trusted checkout’s commit and creates one pin-only commit on automation/roc-nightly. It refuses an existing branch tip with other changed files and uses an exact git lease. GitHub’s commit API signs the pin commit, and the controller verifies that GitHub reports the signature as verified.

The caller grants a permission ceiling. Actual jobs reduce it:

The controller uses GH_TOKEN from github.token, DEFAULT_BRANCH, and GitHub’s standard repository/workspace/run environment. Prepare additionally accepts FORCE for an explicit retry. Its outputs are changed, sha, and nightly. Validate accepts CANDIDATE_SHA and emits JSON runs with workflow, ID, URL, and conclusion, plus passed, which is true only when every configured run succeeds. Report accepts that SHA, NIGHTLY_TAG, TEST_RESULT, TEST_PASSED, and VALIDATION_RUNS.

Validation dispatches workflows on the candidate branch with nightly_validation: true. GitHub API version 2026-03-10 returns their exact run IDs. The controller verifies run commit, branch, and event, waits for all results, and refuses stale branch heads. A normally completed failed run becomes a handled, non-passing candidate: it is reported without failing the controller itself. Missing, cancelled, skipped, timed-out, or mismatched evidence fails the controller. None of these states becomes a passing report. Previous success is cleared before a new candidate is prepared. A timeout links to runs for diagnosis.

A workflow dispatch executes project code under that validation workflow’s own permissions. Each consumer must keep test jobs read-only and guard every release or deployment job. This is a required review boundary, not something the controller can infer from a green workflow result. PR review and branch protection remain maintainer responsibilities; this automation grants no bypass or self-approval.

No credentials are persisted by checkout. Authenticated git pushes receive a short-lived token in the child process environment, never command-line arguments. By default the action merges only its validated pin-only PR. It never approves PRs, bypasses repository rules, publishes releases, or deploys sites. The merge policy is described below.

Choose the page’s dominant purpose before writing it. The four Diátaxis forms provide a useful test:

A page can link to another form, but should not interrupt a tutorial with an exhaustive option catalogue or turn reference material into a narrated lesson. Use one topic for one subject or reader question. Split a page when its sections serve different audiences or outcomes.

The manual’s reading order may still follow a natural journey: context, first success, goal-oriented guides, reference, contributor material, then appendices. The four forms are an editing discipline rather than required top-level folders.

Record these answers in the issue, pull request, or draft notes:

Lead with the outcome. Keep prerequisites close to the first step. Use complete, copyable examples and explain the observable result. Link to detailed reference or background when it would distract from the page’s purpose.

Name the primary audience and assume only the knowledge that audience normally has. A package user may understand Roc while knowing nothing about the native engine, protocol, algorithm, or build system behind the package. Introduce a concept in ordinary language before using its specialist name.

For an unfamiliar tool, answer these questions before presenting its API:

Use progressive disclosure. Keep implementation names, escape hatches, internal architecture, and contributor concerns in explicitly advanced or internal material until a user task requires them. Do not use the introduction as a feature inventory.

Before publication, ask a reviewer who did not design the feature to read from the primary audience’s perspective. Have them list unanswered questions, undefined terms, assumed experience, and places where they could copy commands without understanding the purpose. Resolve adoption and first-use gaps before polishing expert reference material.

Use a Mermaid diagram when relationships, state changes, trust boundaries, data flow, or a multi-stage process would take several paragraphs to reconstruct. A diagram should make one point and sit beside the prose that explains its meaning. Prefer stable concepts over incidental implementation details so it remains useful as the code changes.

In AsciiDoc sources built by actions/build-docs, embed Mermaid source so the same diagram is rendered into the HTML site and PDF:

Give every diagram a descriptive title or nearby textual explanation. Do not put information only in color, and make labels meaningful when printed in grayscale. Keep the Mermaid source readable because it is also the maintainable form of the diagram.

Use syntax-highlighted source blocks for commands, configuration, source code, schemas, reports, and output. Name the language explicitly and keep examples focused enough to scan:

Prefer examples that CI compiles or exercises. When a snippet is intentionally incomplete, say what was omitted. Separate commands from their output, label both, and never rely on highlighting alone to communicate an error or required change.

A manual built by actions/build-docs is a book with one entrypoint and one file per chapter. The renderer produces the whole book as index.html, a separate HTML page for every chapter, and a PDF. A few rules keep all three outputs correct.

Build the manual in a pull request, and deploy it from the default branch, as described in Documentation site.

A project has more than one kind of reader: someone deciding whether to use the package, someone using it for the first time, an experienced user looking up a detail, a contributor, a maintainer cutting a release, a person verifying a download. Their needs differ, and they should all be served by one unified document, the manual, and not by notes scattered across the repository.

A README is the front door, and it faces users. It answers three questions and then hands over to the manual: what is this, what does it look like, and where do I go next.

A README must never become a dumping ground. Build instructions, contributor setup, design notes, troubleshooting and release procedure all belong in the manual. When something seems to need adding to the README, add it to the manual and link to it. A README that has grown past a screen or two has usually started doing the manual’s job, and the two then drift apart.

The same holds for the other root files. CONTRIBUTING.md is a short pointer to the contributing chapter. SECURITY.md states how to report a vulnerability. Neither carries guidance that is not also in the manual.

Review the documentation as a connected entry path, not only as individual pages. A user should be able to find:

All of these live in the manual, as one document. The files that hosting services and tools expect at the repository root, such as README.md, CONTRIBUTING.md, SECURITY.md and LICENSE, stay there and stay short; see Keep the README short.

Documentation is evidence of a declared process, not proof that the process is followed. For every operational claim, identify how it is checked:

Prefer generated reference material only when generation is complete, readable, and checked. Handwritten explanations and examples still need review when the interface changes.

Before merging documentation:

Project-practice evidence supplies the companion checklist for repository and operational evidence. The Diátaxis framework and DITA topic guidance are the sources for the content-shape principles used here.

For each project, maintain an evidence inventory. It is an internal review aid; the public documentation should explain what readers need without discussing a badge application.

At minimum, review this inventory:

Cover the public project experience expands the documentation row into an authoring and review process. Verify that the configured reporting channel works. Review repository permissions and branch rules against actual successful checks, including signed commits where required.

Gold requires at least half of proposed modifications to be reviewed by another person before release. No workflow in this model approves or merges a change, so every tooling change is a maintainer’s pull request and counts or fails to count on its own review. Do not manufacture bot approvals.

OpenSSF Scorecard is a separate measurement. Its automated checks are not the Best Practices badge, and it scores review independently. Revisit practice evidence and response history periodically.

Sources: passing, gold, Scorecard Code-Review.

Use issues for bug reports and design discussion, and pull requests for changes. Explain the affected behavior, the change, and how it was validated. Report vulnerabilities privately, as SECURITY.md describes. Commits are signed, and changes reach the default branch through pull requests.

The sources are the AsciiDoc files under docs/. Write for the shared renderer lists the conventions they follow.

Build the site and PDF locally with Docker:

The output is written to .docs-out/. The Documentation workflow runs the same build on every pull request and deploys from the default branch.

The manual describes the model as it should be practised. A repository or tool that does not yet follow it is recorded in a GitHub issue, not in the manual. Record a change in the release notes under docs/releases/, in the file for the version it will ship in. docs/releases.adoc includes each of those files.

Read the trust model first. It is normative: a change to an action’s behavior or permissions keeps those boundaries and arrives with regression tests for them.

actions/nightly-report and actions/publish-release are Roc scripts, scripts/nightly_report.roc and scripts/publish_release.roc, and their tests are expect tests that blueprint run check runs; Change an action that is a Roc script says how they are built and tested. The other actions are Python. Python 3.10 or later and the standard library are sufficient for their tests:

The repository’s own automation is Roc scripts under scripts/, written as Write automation as Roc scripts describes. With blueprint installed as Get blueprint describes:

It runs the expect tests of the modules under scripts/src/, checks each script with roc-stable, checks their formatting, and holds every script’s roc field to the release Blueprint.roc names. CI runs the same task.

scripts/check_settings.roc must stay read-only. Its one request function states the GET method, and what it decides from GitHub’s answers is pure logic in scripts/src/Settings.roc. A change to a check arrives with expect tests for the passing and the failing answer, and a setting that cannot be read is reported as unknown. CI does not run it against a repository, because that needs administration access; see Confirm the settings.

The scripts behind the shared actions are also built as static Linux executables, so that a calling job can run one without Nix or a compiler.

It writes dist/<tool>-<system> for x86_64-linux and aarch64-linux. Both are built on one machine, and two builds of the same commit give the same bytes.

The Release tools workflow publishes them under the tag tools-<version>. It follows The order of a release:

A pull request runs the first two steps as a dry run. Before dispatching a release, commit its notes as docs/releases/tools-<version>.md.

Repositories reference an action by full commit SHA and adopt a new one through a Dependabot or maintainer pull request. Nothing updates them automatically.

For a change to an action that a reusable workflow in this repository calls, commit the action and its tests first, then update the workflow to that exact commit. This gives the nested action an immutable revision without a self-referential commit hash.

Use a unique version tag for a published release, record any assigned vulnerability identifiers for fixes, and never move an existing tag.

This version applies what the first repository to adopt the model found. It removes repeated values from every workflow, adds two shared actions for steps that each repository had written differently, and says what the model asks of the simplest kind of repository.

This version adds the actions/setup-blueprint shared action and settles how the nightly compiler is installed.

Initial version of the roc-automation manual.

It describes an opinionated approach for managing Roc packages and platforms: the tooling environment, repository layout, examples, testing, the pull-request, release and nightly workflows, platforms and their native build inputs, and the trust model behind the shared actions.