Using Moru
CI
Workflows in .moru/workflows or .github/workflows run on every new revision, push, schedule or manual start, on the runner of the person the run is for. Required jobs gate merging.
CI runs the commands in a repository’s workflow files when something happens: a change gets a new revision, someone pushes a branch or a tag, a schedule comes due, or a person starts a workflow by hand. Each job runs on a runner, the same program that runs agents. A repository can require jobs to pass before a change merges.
The node never runs a job itself and never holds a CI secret. A run belongs to one person, and its jobs run only on that person’s runners.
Workflows#
A workflow is a YAML file in .moru/workflows/, one file per workflow. Its name is the
file’s name without .yml (or .yaml): .moru/workflows/checks.yml is the workflow checks.
# .moru/workflows/checks.yml
on:
change: { targets: [main] }
push: { branches: [main] }
manual: {}
jobs:
test:
steps:
- run: cargo test --workspace
lint:
steps:
- run: cargo clippy --workspace -- -D warnings A job runs on any of the person’s runners unless it says otherwise. runs-on: [linux] keeps it on Linux runners; macos, x64 and arm64 work the same way, and every runner
has its OS and CPU as labels without anyone setting them.
The syntax is close to GitHub Actions, with three differences:
- Steps are commands. Each step runs one
run:script withbash(orsh). If your repository hasmake,justormisetasks, call them, and a step does the same thing in your terminal as in CI. A step can also use an action withuses:(see Actions). - No expression language. There’s no
${{ }}. A job’s condition is a small structured match (when:), and steps read everything else from environment variables. - Triggers are Moru’s:
change,push,scheduleandmanual, andcallfor a workflow that other workflows call (see Reusable workflows).
The CI file reference lists every key. A run uses the workflow files at the commit it tests, so a change can change its own CI.
A repository with no file in .moru/workflows/ runs the workflows in .github/workflows/ instead, as they are, translated into the same jobs. A repository
imported from GitHub keeps its CI that way. See Running GitHub workflows.
A file with a mistake doesn’t run. Its run is refused and lists each problem with its line and column. An unknown key is refused the same way rather than ignored. A workflow that calls a broken file is refused too, with the place of the problem in the called file.
A broken file gets one refused run per version of the file, the first time a revision or push carries it, whether or not its triggers would have matched (they may be what’s broken). Pushing the same file again doesn’t add another. Starting a broken workflow by hand always records a refused run, so you see why at once.
When a workflow runs, and for whom#
Every run is delegated to one person. Its jobs run only on that person’s runners, and the node gives each job a token that can fetch the repository and nothing else.
| What happened | The run is for |
|---|---|
| An agent submits a revision | the person who started the attempt |
| A person proposes a branch or pushes a revision, or applies suggestions | that person |
| A person pushes a branch or a tag | the person who pushed |
| A change is merged | the person who merged it |
| A person starts a workflow on the CI tab | that person |
| A schedule comes due | the person Scheduled runs use names (see Schedules) |
| A person re-runs a run | the person who re-ran it |
So an agent’s work is tested on the runners of the person who started it, with the same tools the agent had, and your push is tested on your runner. If the person has no runner online that can take a job, the job waits, and the run page says whose runner it’s waiting for.
Some CI features need a recent runner. A job that uses one is given only to a runner
new enough to run it; older runners don’t take it, so nothing it asks for is skipped.
If every runner the person has online is older, the job waits, and the run page says
which version it needs, such as “Needs moru-runner 2026.12.0 or later”. Updating the
runner is enough. GitHub workflows, and native jobs with uses: steps, cache, artifacts, runner:, container or services, need moru-runner 2026.11.8 or later.
A change trigger runs on every new revision. With targets, only for changes
targeting one of those branches. A push trigger runs when a branch or tag moves, for
the branches and tags it lists. Deleting a branch runs nothing, and neither do pushes to refs/for/..., which propose a change and so run the change trigger instead. A manual trigger lets people with write access start the workflow from the CI tab,
on any branch or tag, with inputs if it declares some. A schedule trigger runs the default branch’s workflow at the times its cron lines give (see Schedules).
paths: skips a run when none of the files the revision or push changed match. It
doesn’t apply to new branches (there’s nothing to compare with), tags, schedules or
manual starts. Set it once for the workflow, or on change and push separately.
Pushes Moru makes itself don’t start runs: a repository that follows GitHub fetching new commits, or the branch a change tracks moving when someone applies suggestions (the change’s new revision runs instead).
A new revision cancels the unfinished jobs of the change’s earlier revisions, and a new
push cancels the unfinished jobs of the previous push run of the same workflow on that
branch. A scheduled run cancels the unfinished one before it from the same cron line. A
workflow can turn this off with cancel-superseded: false. Manual runs are never
cancelled this way.
If the person a run is for loses write access to the repository, their queued and running CI jobs are cancelled.
Manual inputs#
A manual trigger can declare inputs. Run workflow on the CI tab asks for them, and
the API takes them by name:
on:
manual:
inputs:
target:
type: choice
options: [staging, production]
required: true
dry-run:
type: boolean
default: true An input’s type is string (the default), boolean, choice (with its options) or number. A step reads each one as MORU_INPUT_<NAME>, upper-cased with every other
character turned into _: $MORU_INPUT_DRY_RUN. An input left out takes its default.
Without one, a string is empty, a boolean false, a choice its first option, and a
number has no variable at all.
A start with an unknown input, a required one missing or a value of the wrong kind is refused, with each problem named. A workflow has at most 25 inputs, and their values together at most 65,535 bytes. A re-run uses the same inputs again.
Inputs aren’t secret. Anyone who can see the run sees them on its page, so don’t pass tokens or passwords as inputs: put them in secrets.
Schedules#
A schedule trigger runs a workflow at set times. Each entry is a cron line, with an
optional time zone:
on:
schedule:
- cron: '0 4 * * *' # 04:00 UTC every day
- cron: '30 7 * * MON-FRI'
timezone: Europe/Zurich # 07:30 in Zurich on weekdays A cron line has five fields: minute, hour, day of the month, month and day of the week.
Each field takes numbers, *, lists (1,15), ranges (1-5) and steps (*/15); months
and days also take names (JAN, MON). Extensions such as L, W, #, ? and @daily aren’t accepted. Without timezone, times are UTC; a timezone is an IANA name
such as America/New_York.
- Every 5 minutes at most. A cron line that comes due more often runs at most every 5 minutes, as on GitHub, and the CI tab notes it.
- Daylight saving time. A time the clocks skip, such as 02:30 on the night they go
forward, runs at the next time that exists (03:00). A fixed time in the hour that
happens twice when they go back runs once, the first time. Lines with steps
(
*/30 * * * *) run in both copies of that hour. - Day of the month and day of the week. When both are set, a day matching either one
runs, as in POSIX cron:
0 0 1 * MONruns on the 1st and on every Monday. GitHub doesn’t say which rule it uses. - Missed times aren’t caught up. If the node is down when a schedule comes due, that run doesn’t happen later.
Schedules come from the workflows on the default branch, at its latest commit, and run on the repository’s node. The CI tab lists each schedule with its next run. A repository runs at most 50 schedules; past that, the CI tab says which ones don’t run. A repository being moved to another node, or in the trash, runs none.
A schedule has no author, so its runs are for the person a repository admin chooses under Scheduled runs use, in the repository’s settings, under CI (or moru-node repo-policy --schedule-as <handle>). The runs go to that person’s runners, and
use that person’s secrets where ci.toml gives them to schedule runs. Until someone is
chosen:
- a repository owned by a person runs its schedules as that person;
- an organization’s repository runs no schedules, and its CI tab says so.
The person must be able to write to the repository. If they lose write access, the schedules stop, the CI tab says why, and the repository’s admins get one Stopped schedules notification. Choose someone else, or give the person write access again, to start them.
Jobs and steps#
A job runs its steps in order, in a fresh checkout of the commit, and stops at the first
step that fails, unless that step has continue-on-failure: true. Jobs that needs other jobs wait for them and are skipped if one of them fails, unless they set when: { always: true }. A matrix turns one job into one job per combination of
values.
A job gets 60 minutes unless it sets timeout (at most 4 hours). A job that runs past
it is stopped and ends timed out.
Where a job runs#
A job checks out in a folder named after its repository, <work-dir>/<owner>/<name> on
the runner, and every job of that repository uses the same one, as on GitHub. So a job
can run what an earlier job built there, such as a test archive whose binaries hold
absolute paths into the checkout. The folder is emptied before each job and removed
after it: files don’t carry over, artifacts and caches do.
Because they share the folder, a runner runs one job of a repository at a time; with --max-jobs above 1, its other slots take other repositories’ jobs and agent jobs. A
repository’s jobs run side by side only on several runners. For a build from one
machine to run on another, start their runners with the same --work-dir (see The work directory).
Steps run as the runner’s OS user, on the runner’s machine, with its tools and network and no sandbox, the same as agents do. Read Where to run a runner before you let a runner take CI jobs, and before you give one a secret.
Reusable workflows#
Jobs that several workflows share can live in one file that the others call. The
called file has a call trigger, with inputs if it needs some:
# .moru/workflows/checks.yml
on:
call:
inputs:
level: { type: choice, options: [quick, full], default: quick }
jobs:
lint:
steps:
- run: cargo clippy --workspace -- -D warnings
test:
steps:
- run: scripts/test.sh "$MORU_INPUT_LEVEL" A job calls it with uses: and passes its inputs in with::
# .moru/workflows/release.yml
on:
push: { tags: ['v*'] }
jobs:
checks:
uses: ./.moru/workflows/checks.yml
with: { level: full }
publish:
needs: checks
steps:
- run: scripts/publish.sh The calling job turns into the called file’s jobs, checks/lint and checks/test, and publish waits for both. A required job inside a called file is named the same way: release/checks/lint. A file whose only trigger is call never runs on its own.
Only files in the same repository’s .moru/workflows/ can be called, at the same
commit. Secrets aren’t passed along: each called job lists its own and gets them from
the runner. See Calling a workflow for
how needs, when, matrices, inputs, outputs and env work across a call.
Actions#
A native step can use an action instead of a run: script, with with: values as plain
strings:
steps:
- uses: actions/setup-node@v4
with: { node-version-file: .nvmrc }
- run: npm ci && npm test Actions work as in GitHub workflows: a few common
ones are built into the runner, JavaScript and composite actions are fetched and run
with the machine’s node, and Docker actions, or an image named with uses: docker://…, run in a container. Lock them with moru-runner ci lock.
A uses: step never gets the job’s secrets. Only the job’s own run: steps have them in
their environment, so an action someone else wrote can’t read them. If an action needs a
token, call the tool from a run: step instead.
Containers#
A job can start containers next to it (services:), run its steps inside an image
(container:), and use Docker actions. The runner does all of it with the docker or podman command on its machine:
jobs:
test:
container: 'rust:1.86'
services:
postgres:
image: 'postgres:17'
env: { POSTGRES_PASSWORD: test }
ports: [5432]
options: --health-cmd pg_isready --health-interval 2s --health-retries 30
steps:
- run: cargo test --workspace The CI file reference lists the keys. GitHub
workflows use GitHub’s own container: and services: keys, which work the same way.
A container gives a job its own tools; it doesn’t isolate the job. Each runner belongs
to one person and runs only that person’s jobs, on their machine, and a job’s options can mount what they like, the Docker socket included.
The runner’s own environment stays out of containers. The docker or podman command
it runs gets only what the engine needs (PATH, HOME, DOCKER_*, CONTAINER_HOST, XDG_*, proxy and locale variables and a few more), not your ci.toml secrets, the
runner’s token or model API keys. For the same reason options can’t pass a variable
without a value (-e NAME), and can’t use --env-host, --env-merge, --env-file or --label-file. A credential helper that reads other variables of yours won’t see them
either; give it a config file instead.
Which runners take container jobs#
A job with container:, services: or a docker:// step goes only to a runner that
says it can run containers. A runner says so while its engine answers: at start it looks
for docker, then podman, on its PATH (or the one --container-cli names), and asks
it for its version. The engine must run Linux containers. Docker Desktop, OrbStack,
colima and podman machine on a Mac all do, so a Mac runner takes container jobs as well
as a Linux one. The runner asks again every 5 minutes, and before it asks for work after
a failed check, so starting Docker Desktop later is enough; there’s no need to restart
the runner. Its log says which engine it found, or why containers are off.
If none of the person’s runners can run containers, the job waits, and the run page says
“Waiting for mira’s runner (needs: containers)“. --container-cli none turns
containers off on a runner. See Containers on a CI runner.
Other Docker actions are different: one named owner/repo@ref, a ./path one in the
repository, and any used inside a composite action. The node can’t tell they’re Docker
actions until the runner has fetched them, so such a job can go to a runner without an
engine. The step then fails with ”uses: … runs in a container, which needs a container
engine (docker or podman), and this runner has none”, followed by what to do. If a
job needs such an action, give it runs-on labels that only your runners with an engine
have, use the action’s image as docker://, or run the job in a container:.
Services#
Each service starts before the job’s first step, on a network of the job’s own, with its
service ID as its host name. The runner pulls the image, starts the container with the env, volumes, options, command and entrypoint you gave, and, when the image or options have a health check, waits until it reports healthy. A service that turns
unhealthy, or is still starting after its check’s own time plus a minute, fails the job
before its steps, and its last 100 log lines go into the job’s log. In a GitHub workflow,
a service whose image comes out empty ('') isn’t started; the job still goes to a
runner with containers, since the node doesn’t evaluate the expression. A native
workflow refuses an empty image.
Steps find a service through variables:
| Job | MORU_SERVICE_<ID>_HOST | MORU_SERVICE_<ID>_PORT_<port> |
|---|---|---|
without a container: | 127.0.0.1 | the port on this machine |
with a container: | the service’s ID | the container’s own port |
<ID> is the service’s ID in upper case, with - turned into _; a UDP port’s variable
ends in _UDP. So $MORU_SERVICE_POSTGRES_HOST:$MORU_SERVICE_POSTGRES_PORT_5432 reaches
the database either way. A service that lists no ports has only the _HOST variable,
and only a job container can reach it.
Ports are published on 127.0.0.1 only, each on a free port unless you give one
(8080:80). GitHub publishes them on every interface; on a laptop that would put a test
database on the local network. -p and --publish in options are refused for the
same reason.
When the job ends, the services’ last 1,000 log lines each go into its log, under Stop services (Stop containers in a job with container:), and the runner
removes the containers and the network.
The job’s container#
With container:, the runner starts the image with the job’s network, then runs each
step inside it with docker exec. Actions that run on their own (actions/checkout,
caches, artifacts, dorny/paths-filter) still run on the runner’s machine; the setup
actions, jdx/mise-action and dtolnay/rust-toolchain check and run the container’s
tools.
- Same paths. The checkout and the job’s own folder are mounted at the same paths
inside the container as on the machine, so
$GITHUB_WORKSPACE,$TMPDIR,$MORU_OUTPUTand the command files mean the same on both sides (GitHub mounts them under/__winstead). The runner’s copies of fetched actions are mounted read-only. Nothing else of the machine is mounted unless yourvolumesoroptionsask for it. - Tools come from the image. A native step runs with the image’s
bash, or withsh -ewhen the image has none (the log says so once). A GitHub step withoutshellruns withsh, as on GitHub.shell: bashorshell: pythonneeds it in the image, and the step says so if it’s missing. JavaScript actions run with the image’s ownnode: an image without one, or with one older than the action needs, fails the step and names the version it needs. - Environment. Steps get the job’s variables, not the runner’s environment.
PATHis the image’s, with what steps add toGITHUB_PATHin front.HOMEis the image’s own. The container’s ownenvis set on the container, so every process in it sees it, actions’ steps included: a secret you put there reaches actions, as a secret in the job’senv:does on the machine. - An empty image.
container: ''(a GitHub expression that comes out empty) runs the job on the machine, with a line in the log saying so. The job still needs a runner with containers: the node doesn’t know the image will be empty.
At the end, the runner stops the container and gives the job’s files back to its own
user before it removes them: a container running as root writes files its user can’t
delete otherwise. It does this with a throwaway container of the same image that runs find and chown over the job’s folders, changing only files the container’s user
wrote. An image without sh, find or chown can’t do it, and the log has a warning.
A volume you mount inside the job’s folder isn’t covered.
An image whose USER isn’t root can’t write the runner’s own folders as they are. When
the container’s user is neither root nor the folders’ owner, the runner opens the job’s
temporary folder and command files to every user on the machine, as GitHub does, and
says so in the log. The folders above them stay private to the runner’s user, and the
checkout keeps its permissions, so on rootful Docker on Linux
such an image can read the checkout but not write to it.
Docker actions#
A step can run an image (uses: docker://alpine:3.20) or a Docker action, one whose action.yml says runs.using: docker. The runner pulls the image, or builds the action’s Dockerfile (once per action commit, kept until the runner removes its copy of the
action; a ./path action in the repository is built for each job and removed after
it), and
runs it as GitHub does: the checkout at /github/workspace, the command files under /github/file_commands, HOME at /github/home, the action’s inputs as INPUT_*, on
the job’s network. pre-entrypoint and post-entrypoint run in containers of their own.
In a job with a container:, the action’s container runs next to it. Like any action, a
Docker action gets none of the job’s secrets.
Images#
The runner pulls every image at the start of each job, as GitHub does, so a moved tag is picked up. If a pull fails and the image is already on the machine, it uses that one and says so in the log, so a laptop without a network still runs its jobs.
A job’s run page lists the images it used, with their digests, and a change’s signed CI results carry the same list. The digests are what the runner reported after pulling; for an image built from a Dockerfile, the digest is its image ID. Each container runs the image by that ID, not by its tag, so a tag that moves during the job doesn’t change what runs.
moru-runner ci lock records the digest of each docker:// image, and the runner then
refuses an image whose digest changed: a tag moved since the lock fails the step (see Locking actions). ci run prints a line
for each image the lock doesn’t cover. The lock doesn’t cover the images of container: and services:, nor the FROM images a Docker action’s Dockerfile builds on; to fix
a container: or service image, pin it by digest (postgres:17@sha256:…).
Registries that need a login#
Give a service or a container credentials. The password comes from a secret on the
runner, which counts towards the job’s secrets:
services:
feed:
image: 'ghcr.io/acme/feed-mock:2'
credentials: { username: acme-ci, password-secret: GHCR_TOKEN } The runner logs in with a configuration of its own for that one pull, so the login
doesn’t land in your ~/.docker. Without credentials, the runner user’s own logins
apply.
What’s left behind#
The runner labels every container, network and image it makes with its own ID and the
job’s, and removes them when the job ends, however it ends: passed, failed, cancelled or
timed out. If the runner itself is killed, it removes what’s left the next time it
starts. A local run (moru-runner ci run) cleans up the same way; see Run a job on your machine.
On a Mac#
Docker Desktop, colima and podman machine run containers in a Linux VM that sees only
the folders shared with it. The runner checks that the job’s container can see the job’s
folder, and if it can’t, the job fails and names the folder to share: Docker Desktop’s Settings → Resources → File sharing, colima’s mounts, or podman machine’s volumes.
Keep the runner’s --cache-dir and --work-dir (and, for local runs, your checkout) in a
shared folder, such as one in your home directory. OrbStack shares everything.
RUNNER_OS stays macOS for a GitHub workflow on a Mac, even inside a Linux container.
GitHub runs containers only on Linux, so a workflow that tests runner.os may pick the
wrong branch: runs-on: [linux] keeps such a job on Linux runners.
Caches#
A job can keep directories between runs, such as a package manager’s download cache:
jobs:
ui:
cache:
key: pnpm-{hash:ui/pnpm-lock.yaml}
restore-keys: [pnpm-]
paths: [~/.local/share/pnpm/store]
steps:
- run: pnpm install --frozen-lockfile Before the steps, the runner restores the entry whose key matches key, or failing that
the newest entry whose key starts with one of the restore-keys. After the steps, if
the job passed and key didn’t match exactly, it saves the paths under key. An entry
is never overwritten, so a new entry needs a new key. {hash:<glob>} in a key is a hash
of the files the pattern matches, so the key changes when they do. In a GitHub workflow, actions/cache does the same.
In a job with a container:, caches are restored and saved on the runner’s machine, not
inside the container. A path starting with ~ is the runner user’s home on the machine,
which the container doesn’t see. Keep a container job’s cached paths inside the
checkout, and point the tool at them (CARGO_HOME, npm_config_cache).
Caches stay on the runner, in its cache directory under ci-cache/. They aren’t shared
with other runners, even the same person’s. Entries not used for 7 days are removed, and
beyond the size the runner’s ci.toml sets ([cache] max_size, 10 GiB by default) the
least recently used go first. See CI caches.
Scopes. An entry a run saves can be restored only by some runs:
| Saved by | Restored by |
|---|---|
| a run for a change | that change’s runs |
| a push, schedule or manual run on a branch | runs on that branch, and runs for changes that target it |
| a run on the default branch | every run of the repository |
A run looks in its own scope first, then the branch’s, then the default branch’s. Runs
for changes only restore by default; they don’t save. In a GitHub workflow, cache-mode: write lets them save into their change’s scope.
Artifacts#
A job can upload files for later jobs of the same run and for people to download:
jobs:
build:
artifacts:
dist: dist/
reports: [coverage/lcov.info, 'test-results/**/*.xml']
steps:
- run: make dist
smoke:
needs: build
steps:
- run: scripts/smoke.sh "$MORU_ARTIFACTS/dist" Each artifact is a zip of the paths listed, made after the steps, whether the job passed
or failed. A job that needs jobs with artifacts finds them unpacked in $MORU_ARTIFACTS/<name>/. In a GitHub workflow, actions/upload-artifact and actions/download-artifact do the same. Uploading a name the run already has fails
(unless a GitHub workflow says overwrite: true), so a matrix job puts {matrix.<key>} in its artifacts’ names.
Links in the paths are followed while they stay inside the checkout or the job’s temporary folder. A link whose target is outside them is left out, with a warning naming it, so a link committed to the repository can’t upload files from the runner’s machine.
Artifacts live on the repository’s node:
| Limit | Value |
|---|---|
| One artifact | 500 MiB |
| All of a run’s artifacts | 1 GiB, and 500 artifacts |
| Kept | 30 days; retention-days in a GitHub workflow can shorten it |
| Free disk the node keeps | 2 GiB: uploads that would go below it are refused |
The run’s page lists its artifacts with their size and when they expire, and anyone who can see the run’s logs can download them: on a public repository, anyone who can read it; on a private one, people with write access. Artifacts aren’t in the node’s backups, and when a repository moves to another node they stay behind, as CI logs do. Deleting a repository deletes them when it leaves the trash.
The CI tab#
The repository’s CI tab lists runs, newest first, with their state, trigger, commit
and who they’re for. Filter them by state, branch or change. Beside the list are the
workflows on the default branch, which folder they’re read from, and for each one whether
it runs as is, runs with notes, or is refused and why, its schedules with their next run,
and the actions it uses. Run workflow starts one with a manual trigger.
A run’s page shows its jobs as a graph, in the order needs gives them, and each job’s
steps with their logs. People with write access can Cancel a run that’s under way
and Re-run one that has ended; to re-run a run that’s under way, cancel it first. A
re-run is a new run of the same workflow at the same commit, for the person who re-ran
it. A refused run can’t be re-run: fix the file instead. A change’s run can be re-run
only for its latest revision before it merges, and a push or scheduled run only while its
branch still points at that commit; otherwise start the workflow by hand.
The run page also shows a run’s number and attempt, its notes, the inputs it was started with, a scheduled run’s cron, Unlocked actions when the node looked actions up, and its artifacts for people who may download them.
The change page shows each revision’s CI results, with links to their runs, and marks the jobs the repository requires.
Who sees what#
Anyone who can read the repository sees its runs, their jobs and their states.
On a public repository, anyone who can read it, visitors who aren’t signed in included, also sees the jobs’ logs, their steps’ outputs, why a job failed and the run’s artifacts. On a private one, those are for people with write access only. Agents’ job logs are for people with write access whatever the visibility, and so is which runner ran a CI job and whose it is.
The runner replaces each secret’s value with [redacted] before a log line or an output
leaves the machine (see Secrets), but only the value as it is: a step that
prints a secret encoded, split or changed in any other way still shows it. On a public
repository, treat a CI log as public.
Required jobs#
A repository can require CI jobs to pass before a change merges. Each is named <workflow>/<job>: the workflow’s file name without .yml and the job’s key under jobs:, such as checks/test; a job of a called workflow has
the calling job in between, ci/checks/test. A repository admin sets them in the repository’s
settings, under Merging, or a node admin runs:
moru-node repo-policy acme/timetable --required-ci checks/test,checks/lint --required-ci "" removes them all. The setting moves with the repository.
A required job counts as passed only when all of these hold:
- it passed on the change’s latest revision, in that revision’s latest run of the workflow; a pass on an earlier revision doesn’t count;
- every matrix combination of the job passed;
- it ran on a runner whose owner had write access to the repository when the runner took the job; a result from anyone else’s runner is shown, marked as not counted;
- the node’s signed record of the result verifies, and its signer is trusted.
Until then, merging is refused with the reason, such as “r2 hasn’t passed the required CI job checks/test (os=macos): it is still queued (acme/timetable requires checks/test)“.
A required job that doesn’t run for a revision by design counts as passed, as on
GitHub. That’s a job whose when: doesn’t match the change, a job that needs one of
those (unless it sets always: true), and every job of a workflow the revision doesn’t
trigger, because of its on: targets or its paths:. The node works this out from the
revision’s own workflow file and the files it changes, so the answer is the same on
every node. The change’s Checks show such a job as not run, with a note that it counts
as passed.
A required job still blocks the merge when it was skipped because a job it needs failed, timed out or was cancelled, when it hasn’t run yet, when its workflow file was refused, and when the workflow has no job of that name.
In a GitHub workflow, a job whose if is false doesn’t run
by design either, by the same rule: it counts as passed when the jobs it needs succeeded,
and blocks when it was skipped after one of them failed or was cancelled, whatever its if says. A job inside a reusable workflow is named with the calling job in between: checks/ci/test. Matrix combinations dropped because they’d run on Windows aren’t
counted.
Required jobs are matched by name, and a change runs its own workflow files. So a
change can rewrite a required job, even to run: "true", and it passes. GitHub works
the same way. Read the diff of .moru/workflows/ when you review a change.
For each revision, the node signs a record of each job’s result and stores it in the
change, next to the agent’s attestation, so the results travel with the repository and
can be checked offline: moru-node verify lists them. Runs for pushes and manual starts
are kept on the node only. See Provenance.
Secrets#
Secrets live on the runner, in its ci.toml, never on the node. A job lists the
secrets it needs:
jobs:
publish:
when: { push: { branches: [main] } }
secrets: [REGISTRY_TOKEN]
steps:
- run: scripts/publish.sh The runner’s owner says which repositories, refs and triggers each secret is for. A
runner that can’t give a job every secret it lists doesn’t take the job, and the run
page says which secret is missing on whose runner. By default a secret is given to push
and manual runs. It goes to a change’s runs only if its triggers list change, since a
change’s code hasn’t been reviewed yet, and to scheduled runs only if they list schedule, since no one starts those.
The step gets the secret as an environment variable of the same name, and the runner
replaces its value with [redacted] in logs and outputs. The node learns the secrets’
names, never their values. See CI secrets for ci.toml’s format. Steps that use an action (uses:) don’t get the job’s secrets (see Actions). A GitHub workflow reads its secrets as secrets.NAME (see Secrets in GitHub workflows).
Named runners#
A job can ask for one runner by its name:
jobs:
deploy:
runs-on: { runner: mira-deploy-box, labels: [linux] }
when: { push: { branches: [main] } }
secrets: [DEPLOY_KEY]
steps:
- run: scripts/deploy.sh Only the runner called mira-deploy-box takes the job, and only if it also has every
label in labels. A runner registered with a code from the Runners page is named with its
owner’s handle in front: moru-runner register --name deploy-box by mira makes mira-deploy-box, and that full name is what runner: must say. Since a run goes only to
the runners of the person it’s for, runner: names one of that person’s runners.
In a GitHub workflow, a runs-on label equal to a runner’s name asks for that runner: runs-on: [self-hosted, mira-deploy-box]. A label in a native runs-on list works the
same way. But runner names and the labels a node admin gives runners share one namespace,
so a runner an admin labelled mira-deploy-box also matches a label. When only that one
machine may run the job, use runner:, which no label matches. Runners can’t be named linux, macos, x64 or arm64, the labels every runner has.
Deploy runners#
A change runs its own workflow file, so a change can name your deploy runner too. A
runner started with --only-named refuses that:
moru-runner run --only-named --cache-dir /var/lib/moru-deploy It takes only CI jobs that name it, by runner: or by a label, and only from pushes and
manual starts, never from a change’s runs. Scheduled runs need --schedules as well. It
takes no agent jobs. A change run that names it waits, and its run page says why. Code no one has reviewed never runs
there, so it’s the place for deploy secrets, and for caches that later runs must be able
to trust.
Keep these in mind:
- Run only the
--only-namedrunner on that machine and user. A second, ordinary runner under the same user would take change runs there, and their code could read what the deploy runner holds. - Who a run is for still decides. Pushes run as the person who pushed, so another writer’s push never reaches your runner. But if you re-run a run, or start a workflow by hand on someone else’s branch, it runs as you, on your runners, with their code. Read what you start. The run page asks before it re-runs someone else’s run.
- Schedules run what the default branch holds. Anyone who can change the default
branch decides what scheduled runs execute, and no one starts them. Schedules reach a
deploy runner only if it was started with
--schedules, and a secret only if itstriggersinci.tomllistschedule. - Scope the secrets too. In
ci.toml, give deploy secrets only to the refs and triggers you deploy from, such asrefs/heads/mainandpush. - Use
runner:, not a label, so a runner an admin labelled with the same name can’t take the job.
Run a job on your machine#
moru-runner ci run runs a workflow’s jobs in your checkout, without a node:
moru-runner ci run # list the workflows and jobs
moru-runner ci run checks # every job of checks.yml, in needs order
moru-runner ci run checks/test # one job
moru-runner ci run checks/test --matrix os=linux It reads the workflow from your working tree (.moru/workflows/, else .github/workflows/), runs the steps there as you, uncommitted changes included, and
exits with the first failing job’s exit code. It ignores runs-on: every job runs on
your machine (it says so once). Secrets come from ci.toml only with --secrets, and a manual run’s inputs from --input name=value. Actions, caches and
artifacts work too: they’re kept in your user cache directory, not in the checkout, and
the run prints where its artifacts went. What a local run caches is kept apart from what
runners restore, since it may hold uncommitted work. --offline runs only locked actions
that are already cached. See moru-runner ci run.
Jobs with container:, services: or Docker actions use your docker or podman.
Everything a local run starts is removed when the job ends, also when you press Ctrl-C
(which can take up to 75 seconds). A second Ctrl-C quits at once and leaves the
containers; the next moru-runner ci run that uses containers removes them. --offline pulls no image, though with docker, building a Docker action’s Dockerfile may still fetch its base image (podman builds with --pull=never).
Notifications and webhooks#
When a run fails, or is refused because its workflow has errors, the person it was for gets a CI failures notification. A manual start that’s refused isn’t notified: the person who started it sees why at once.
When scheduled runs stop because the person they run as can no longer write to the repository, its admins get a Stopped schedules notification, once, until that changes.
Webhooks can subscribe to ci.run.queued, ci.run.started and ci.run.finished, or to ci.* for every CI event. See Webhooks.
Agents read the results of their own revisions, and reviewers those of the candidates
they review, with the get_ci_results tool. See MCP.