Docs
Docs menu

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 with bash (or sh). If your repository has make, just or mise tasks, call them, and a step does the same thing in your terminal as in CI. A step can also use an action with uses: (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, schedule and manual, and call for 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 happenedThe run is for
An agent submits a revisionthe person who started the attempt
A person proposes a branch or pushes a revision, or applies suggestionsthat person
A person pushes a branch or a tagthe person who pushed
A change is mergedthe person who merged it
A person starts a workflow on the CI tabthat person
A schedule comes duethe person Scheduled runs use names (see Schedules)
A person re-runs a runthe 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 * MON runs 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:

JobMORU_SERVICE_<ID>_HOSTMORU_SERVICE_<ID>_PORT_<port>
without a container:127.0.0.1the port on this machine
with a container:the service’s IDthe 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_OUTPUT and the command files mean the same on both sides (GitHub mounts them under /__w instead). The runner’s copies of fetched actions are mounted read-only. Nothing else of the machine is mounted unless your volumes or options ask for it.
  • Tools come from the image. A native step runs with the image’s bash, or with sh -e when the image has none (the log says so once). A GitHub step without shell runs with sh, as on GitHub. shell: bash or shell: python needs it in the image, and the step says so if it’s missing. JavaScript actions run with the image’s own node: 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. PATH is the image’s, with what steps add to GITHUB_PATH in front. HOME is the image’s own. The container’s own env is 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’s env: 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 byRestored by
a run for a changethat change’s runs
a push, schedule or manual run on a branchruns on that branch, and runs for changes that target it
a run on the default branchevery 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:

LimitValue
One artifact500 MiB
All of a run’s artifacts1 GiB, and 500 artifacts
Kept30 days; retention-days in a GitHub workflow can shorten it
Free disk the node keeps2 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-named runner 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 its triggers in ci.toml list schedule.
  • Scope the secrets too. In ci.toml, give deploy secrets only to the refs and triggers you deploy from, such as refs/heads/main and push.
  • 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.

Command menu
Search for a page, repository, change or request, or run a command