magus v0.4.2 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

Running under CI

Nothing about a target changes on a build server. The same ci target runs the same ops against the same declared inputs, and the same cache key decides whether any of it has to run at all. That is the point: a pipeline you cannot reproduce locally is a pipeline you debug through the web UI.

Four things do change, and each has a page.

The pipeline verb

ci is an ordinary target you compose in your magusfile, not a mode magus enters. It strips the write-granting charms before it dispatches, so a pipeline cannot mutate the tree even when someone asks it to. See CI.

The checkout

A build server starts from nothing, and how you clone decides what magus can compute. magus affected needs a base to diff against, so a shallow clone that omits it silently degrades to running everything. See CI checkout.

The shared cache

Local caching helps one machine. A remote cache provider lets runners replay artifacts another machine already built, under a trust model that refuses unsigned entries.

The provider spell

magus knows no vendor's log syntax. A CI provider teaches it one: fold markers around a failure, and annotations that surface on a pull request. Wire it with magus\ci.provider(<spell>).

For a worked example on one system, see GitHub Actions.

ConceptsPages in this section. GitHub ActionsWiring magus into GitHub Actions - the three actions magus publishes, how much belongs in YAML and how little, a workflow that shards by affected project, remote caching over the Actions cache service, and the annotations and pull request advice that come with it. Cache modelHow magus computes a content-addressed cache key from a target's declared inputs, replays outputs on a hit without rerunning the body, and stores it all as plain files under .magus. Workspace providersLet a spell supply the workspace's project set by asking the tool that already owns it - nx, gradle, pnpm, cargo - so a repo needs no magusfile per project.
cici-provideraffectedremote-cacheshardingannotations
Last updated (9edeede5)
Glossary

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. See targets.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Charm

An execution modifier attached with : (lint:rw) that changes how a target runs, not which one; the built-in rw flips a check-only target to mutate in place, and ci always strips it. See charms.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. See cache.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

Remote cache

A CI-only backend that shares content-addressed artifacts across runners: a cold machine replays a build another runner already did instead of rebuilding. Every remote artifact must be signed by a trusted key. See remote.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.