Reference
CI file reference
Every key a workflow in .moru/workflows can use, with types, defaults and limits, the patterns it matches with, and the environment steps run in.
A workflow is a YAML file directly in .moru/workflows/, ending in .yml or .yaml.
The workflow’s name in required_ci, moru-runner ci run and the API is the file name
without the extension. For what CI does with it, see CI. This page
covers Moru’s own format; for workflows in .github/workflows/, see Running GitHub workflows.
A complete example#
# .moru/workflows/checks.yml
name: checks
on:
change: { targets: [main, 'release/*'] }
push:
branches: [main]
tags: ['v*']
manual:
inputs:
level: { type: choice, options: [quick, full], default: quick }
schedule:
- cron: '0 4 * * *'
paths: ['crates/**', 'ui/**', 'Cargo.*', '!**/*.md']
env:
CARGO_TERM_COLOR: always
jobs:
test:
name: test {matrix.toolchain}
runs-on: build
matrix:
toolchain: [stable, beta]
timeout: 30m
steps:
- name: unit tests
run: rustup run "$MORU_MATRIX_TOOLCHAIN" cargo test --workspace
ui:
cache:
key: pnpm-{hash:ui/pnpm-lock.yaml}
restore-keys: [pnpm-]
paths: [~/.local/share/pnpm/store]
artifacts:
ui-build: ui/build/
steps:
- uses: actions/setup-node@v4
with: { node-version-file: ui/.nvmrc }
- run: pnpm install --frozen-lockfile
working-directory: ui
- run: pnpm check && pnpm build
working-directory: ui
- name: size report
run: scripts/size-report.sh
continue-on-failure: true
version:
steps:
- run: echo "version=$(git describe --tags --always)" >> "$MORU_OUTPUT"
publish:
needs: [test, ui, version]
runs-on: { runner: mira-release-box }
when:
push: { tags: ['v*'] }
secrets: [REGISTRY_TOKEN]
env:
REGISTRY: registry.example.com
steps:
- run: scripts/publish.sh "$MORU_NEEDS_VERSION_VERSION"
shell: sh
notify:
needs: publish
when: { always: true }
steps:
- run: scripts/notify.sh Reading the file#
- Unknown keys are errors, reported with their line and column. A file with any error doesn’t run: its run is refused and shows every problem found.
trueandfalseare the only booleans.yes,noandonare strings, so theon:key works as written.- Numbers keep their text as written: a matrix value
3.10stays3.10, and007stays007. - YAML anchors, aliases and merge keys work. A key given twice is an error.
- Where a list is expected (
runs-on,needs,secrets, and every pattern list), a single string is a list of one.
A commit’s workflows are read with these limits:
| Limit | Value |
|---|---|
| Size of a workflow file | 256 KiB, UTF-8 |
| Workflow files per commit | 64, by name; the rest are ignored |
| Jobs a workflow defines | 256 |
| Jobs in one run, matrices expanded | 256 |
| Jobs one push, revision or start can queue | 1,024, over all its workflows |
A job’s timeout | 4 hours |
| A run’s stored plan | 1 MiB |
| A run’s job specs, expanded | about 16 MiB |
| Plans of one push, revision or start | 8 MiB, over all its workflows |
| Job specs of one push, revision or start | about 32 MiB, expanded |
A workflow past a run’s or a trigger’s limit is refused with a finding that says so;
files are counted in name order, so the later ones are refused. Two files with the same
name (checks.yml and checks.yaml) can’t both run: the second in name order is
refused. Files in subdirectories and symbolic links are ignored.
Workflow keys#
| Key | Type | Default | |
|---|---|---|---|
name | string | the file name | A name for people. It can’t hold a matrix placeholder. |
on | map | Required. When the workflow runs: see Triggers. | |
paths | list | no filter | Run only when a changed file matches. See paths. The same as paths on both change and push; set it here or there, not both. |
env | map | Variables for every step of every job. See Environment. | |
jobs | map | Required, at least one. See Job keys. | |
cancel-superseded | boolean | true | Whether a new run cancels the unfinished jobs of the run it replaces: a change’s earlier revision, or the previous push run on the same branch. |
Triggers#
on is a map of triggers, a list of trigger names (on: [change, manual]) or one name
(on: push). At least one is needed.
| Trigger | Keys | Runs |
|---|---|---|
change | targets: branch patterns; paths | For every new revision of a change. With targets, only for changes whose target branch matches. |
push | branches, tags: branch and tag patterns; paths | When a person pushes a branch or tag, or merges a change into a branch. Without either list, every branch and tag; with only branches, no tags; with only tags, no branches. |
manual | inputs: see Manual inputs | When a person with write access starts it on the CI tab or with the API, on a branch or tag. |
schedule | a list of cron lines, each with an optional timezone: see schedule | At the times the cron lines give, from the default branch’s workflow. |
call | inputs: see Call inputs | When a job of another workflow calls this file. See Calling a workflow. A file whose only trigger is call never runs on its own. |
Patterns match branch and tag names (main, release/*, v*), not full refs. A push
that deletes a ref runs nothing. One push starts runs for at most 10 branches, and for no
tags if it pushes more than 3.
Manual inputs#
inputs is a map of input names to their settings. At most 25 inputs.
| Key | Type | Default | |
|---|---|---|---|
type | string | string | string, boolean, choice or number. environment isn’t supported. |
description | string | Shown in the Run workflow dialog. | |
default | The value when none is given. It must be of the input’s type, and one of the options for a choice. | ||
required | boolean | false | A start must give a value, unless there’s a default. |
options | list | Required for a choice, and only for one. |
A step reads an input as MORU_INPUT_<NAME>, named as matrix keys are (see Environment). Without a value or a default, a string is "", a boolean false, a choice its first option, and a number has no variable. Two names that give
the same variable can’t both be used.
Call inputs#
A call trigger takes inputs with the same keys and checks as manual inputs. The calling job gives their values in with, and the
called jobs read them as MORU_INPUT_<NAME>. on: call or on: [call, push] declares
a file that can be called without inputs.
on:
call:
inputs:
level: { type: choice, options: [quick, full], default: quick }
version: { required: true } An input declared under both manual and call must have the same type and options in both, because a job reads it the same way however the run started.
schedule#
on:
schedule:
- cron: '*/30 * * * *'
- cron: '0 6 * * MON'
timezone: Europe/Berlin | Key | Type | Default | |
|---|---|---|---|
cron | string | Required. Five fields: minute (0–59), hour (0–23), day of the month (1–31), month (1–12 or JAN–DEC), day of the week (0–7, 0 and 7 are Sunday, or SUN–SAT). | |
timezone | string | UTC | An IANA time zone name, such as America/New_York. |
Each field takes *, numbers, lists (1,15), ranges (1-5) and steps (*/15, 10-50/20). L, W, #, ? and names like @daily aren’t accepted. A line given twice is an
error. When the day of the month and the day of the week are both restricted, a day that
matches either runs. A line that would run more often than every 5 minutes runs at most
every 5 minutes. See Schedules for time zones, daylight
saving time and who the runs are for.
paths#
A list of patterns matched against the paths of the files that changed,
from the repository’s root. The workflow runs if any changed file matches; a file
matches when the last pattern that matches it doesn’t start with !.
What changed is the diff from the change’s base to the revision, or from the branch’s
old commit to its new one. A renamed file counts under both names. paths isn’t checked
for a new branch (there’s nothing to compare it with), for tags or for manual starts.
Job keys#
Each key under jobs: is the job’s ID: letters, digits, - and _, starting with a
letter or _. required_ci and MORU_NEEDS_* use it. Two IDs that give the same MORU_NEEDS_ name, because they differ only in case or in - and _ (build-linux, build_linux, Build_Linux), can’t both be used.
| Key | Type | Default | |
|---|---|---|---|
name | string | the job’s ID | A name for people. May hold {matrix.<key>}. |
needs | string or list of IDs | Jobs that must finish first. Each must be a job in this workflow, and they can’t form a cycle. | |
when | map | every trigger | Run only for some triggers. See when. |
runs-on | string, list or map | any runner | Runner labels; the runner must have all of them. Or a map that names a runner: see runs-on. May hold {matrix.<key>}. |
matrix | map | One job per combination of values. See matrix. | |
env | map | Variables for every step of this job. | |
timeout | string | 60m | A whole number and a unit, s, m or h: 90s, 30m, 2h. More than zero, at most 4h. 1h30m isn’t accepted: write 90m. |
secrets | string or list | Names of secrets the job needs from its runner’s ci.toml: letters, digits and _, not starting with a digit. See CI secrets. | |
steps | list | Required, at least one, unless the job has uses. See Step keys. | |
cache | map | Directories to keep between runs on the runner. See cache. | |
artifacts | map | Files to upload for later jobs and for people. See artifacts. | |
container | string or map | An image to run the steps in. See container. | |
services | map | Containers to start next to the job, such as a database. See services. | |
uses | string | Call a workflow of this repository instead of running steps: ./.moru/workflows/<file>.yml. See Calling a workflow. | |
with | map | The called workflow’s inputs, for a job with uses. See Passing inputs. |
A job with uses may also have name, needs, when, matrix and with, and
nothing else. Its other keys belong in the called workflow’s jobs, and are errors next to uses.
Every runner has two labels of its own: its OS, linux or macos, and its CPU, x64 or arm64. runs-on: [linux] runs a job on any of the person’s Linux runners,
including one registered with a code from the Runners page. Other labels are the ones a
node admin gives a runner with moru-node create-runner-token --label. Leave runs-on out for a job any of the person’s runners can run.
runs-on#
runs-on takes a label, a list of labels, or a map:
runs-on: { runner: mira-deploy-box, labels: [linux] } | Key | Type | |
|---|---|---|
runner | string | The name of the runner that must run the job: lowercase letters, digits, ., - and _. A runner registered from the Runners page is named <handle>-<name>. |
labels | string or list | Labels that runner must also have. |
At least one of the two. A label equal to a runner’s name also matches that runner, but
so does any runner an admin gave that label; only runner picks one machine. See Named runners.
cache#
cache:
key: cargo-{matrix.os}-{hash:Cargo.lock}
restore-keys: [cargo-{matrix.os}-]
paths: [~/.cargo/registry, target] | Key | Type | |
|---|---|---|
key | string | Required. The entry’s key: at most 512 characters, no commas. {hash:<glob>} is replaced by a SHA-256 of the files the glob matches, as GitHub’s hashFiles works. |
paths | string or list | Required. What to keep. ~/ is the runner user’s home; relative paths are in the checkout; absolute paths and paths outside the checkout work. Globs work, and ! excludes. |
restore-keys | string or list | Prefixes to fall back on when no entry has key exactly: the newest entry whose key starts with the first one, else the second, and so on. |
key and restore-keys may hold {matrix.<key>}. The cache is restored before the
first step and saved after the last one, only when the job passed and key wasn’t an
exact match; an existing key is never overwritten. Runs for changes restore but don’t
save. Restoring or saving can fail without failing the job: it’s a warning in the log.
See Caches for scopes and limits.
artifacts#
artifacts:
dist: dist/
reports: [coverage/lcov.info, 'test-results/**/*.xml', '!test-results/tmp/**'] Each key is an artifact’s name, up to 255 bytes (fewer characters when they aren’t
ASCII), without /, \, :, ", <, >, |, * or ?. It may hold {matrix.<key>}. Each value is a path or a list of
paths and globs, ! excluding. Files and folders whose names start with . are left out.
After the last step, whatever the outcome, the runner zips each artifact, keeping paths
relative to the deepest folder all its paths share, and uploads it to the node. Nothing
found is a warning. An upload that fails fails the job, and so does a name the run
already has. A job that times out or is cancelled still uploads what its steps made so
far, for up to 45 seconds; it ends as it was stopped. A job finds the artifacts of the jobs it needs unpacked in $MORU_ARTIFACTS/<name>/. See Artifacts for limits.
container#
The job’s steps run inside this image, on a runner with docker or podman (see Containers). Either the image alone or a map:
container: 'rust:1.86' container:
image: 'ghcr.io/acme/build:{matrix.toolchain}'
env: { CARGO_HOME: .cargo }
volumes: ['/srv/fixtures:/fixtures:ro']
options: --cpus 2
credentials: { username: acme-ci, password-secret: GHCR_TOKEN } | Key | Type | |
|---|---|---|
image | string | Required. An image reference: not empty, no spaces, not starting with -. May hold {matrix.<key>}. ci lock doesn’t lock it: to fix the image, pin it (postgres:17@sha256:…). |
env | map | Variables set in the container, as env above. |
ports | list | Ports of the container to publish on the machine’s 127.0.0.1. See Ports. |
volumes | list | Extra mounts, as docker run -v takes them: /host/path:/path[:ro], or a named volume. |
options | string | More docker create options, split as a shell would. Some are refused: see options. |
credentials | map | A login for the image’s registry. See credentials. |
The job’s folder (checkout, temporary folder, command files) is mounted at the same path
as on the machine, and the runner’s fetched actions read-only. Steps run in the
container with docker exec; bash if the image has it, else sh -e.
services#
Each key is a service ID (letters, digits, - and _, starting with a letter or _),
which is also the service’s host name on the job’s network. Each value is a map with the
keys of container above, image required, plus:
| Key | Type | |
|---|---|---|
command | string | The container’s command, instead of the image’s. Split as a shell would. |
entrypoint | string | The container’s entrypoint, instead of the image’s. |
services:
postgres:
image: 'postgres:17'
env: { POSTGRES_PASSWORD: test }
ports: [5432]
options: --health-cmd pg_isready --health-interval 2s --health-retries 30
cache:
image: 'redis:7-alpine' Services start before the first step, and a service with a health check must be healthy before it. Steps reach a service through these variables:
| Variable | Without container: | With container: |
|---|---|---|
MORU_SERVICE_<ID>_HOST | 127.0.0.1 | the service’s ID |
MORU_SERVICE_<ID>_PORT_<n> | the port on 127.0.0.1 for TCP n | n |
MORU_SERVICE_<ID>_PORT_<n>_UDP | the same for UDP | n |
<ID> is named as matrix keys are: postgres-main gives MORU_SERVICE_POSTGRES_MAIN_HOST.
Two IDs that give the same name can’t both be used. A port variable is set only for a
port in ports.
Ports#
Each entry of ports is a container port, 5432 (the machine gets a free port), or <machine port>:<container port>, 8080:80. Add /udp for UDP (/tcp is the
default). Ports are always published on 127.0.0.1; an address or a range is refused.
A service can’t list the same container port twice for one protocol.
options#
options is split as a shell would split it and passed to docker create (or docker run). Anything goes except:
--network,--netand--entrypoint: the runner sets them (useentrypointon a service);-p,--publish,-Pand--publish-all: list ports inports:, which publishes them on127.0.0.1only;- a
--label(-l) starting withmoru.: the runner’s own labels; -e NAMEor--env NAMEwithout a value,--env-host,--env-merge,--env-fileand--label-file: they would read the runner’s own environment or files (set variables inenv:);--or a word that isn’t an option or an option’s value.
credentials#
| Key | Type | |
|---|---|---|
username | string | The registry user name. |
username-secret | string | Or a secret that holds it. One of the two is required. |
password-secret | string | Required. The secret that holds the password or token. |
The secrets credentials names are added to the job’s secrets, so a runner that can’t give them doesn’t
take the job. The runner logs in to the image’s registry for that pull only, with a
configuration of its own. Without credentials, the runner user’s own logins apply.
when#
| Key | Type | |
|---|---|---|
change | map | targets, as for the change trigger. |
push | map | branches and tags, as for the push trigger. |
always | boolean | Run once the jobs it needs have finished, even if one failed or was skipped. |
Without change or push, the job runs for every trigger of its workflow. With one or
both, it runs only for a revision or push they match, and never for a manual start. A
job whose when doesn’t match doesn’t run, and the jobs that need it are skipped unless
they set always: true. A required job skipped this way counts as passed (see Required jobs).
matrix#
Each key is a name (letters, digits, - and _, starting with a letter or _) with a
non-empty list of values. The job runs once per combination: { os: [linux, macos], node: [20, 22] } makes four jobs. The first key varies slowest.
- A value can’t be listed twice under one key.
- Two keys that give the same variable (
node-version,node_version) can’t both be used. {matrix.<key>}may appear in the job’sname,runs-on(runnerincluded), a cache’skeyandrestore-keys, artifact names, theimageof itscontainerandservices, and thewithvalues of a job that calls a workflow, and nowhere else. Steps read the value from$MORU_MATRIX_<KEY>. The key must be one of the job’s matrix keys.{input.<name>}may appear only in thewithvalues of a job that calls a workflow (see Passing inputs).- Values of keys the
namedoesn’t use are added to it in brackets, so every combination has its own name:test (linux, 20), ortest linux (20)forname: test {matrix.os}.
A job that needs a matrix job waits for all its combinations.
Step keys#
| Key | Type | Default | |
|---|---|---|---|
run | string | The script to run, not empty. A step has run or uses, not both. | |
uses | string | An action to run instead: owner/repo[/path]@ref, ./path or docker://<image>. See uses. | |
with | map | Inputs for a uses step, as plain strings. | |
name | string | run’s first line | A name for the log. |
env | map | Variables for this step. | |
working-directory | string | the checkout | A directory in the checkout, relative to its root. It must exist and stay inside the checkout: no absolute path, no .., no link out. |
shell | string | bash | bash runs bash -eo pipefail -c <run>; sh runs sh -e -c <run>. Not on a uses step. |
continue-on-failure | boolean | false | If the step fails, go on with the next one. The job can still succeed. |
A step’s script stops at the first command that fails, and the job stops at the first
step that fails. Steps run in their own process group with no input; when a step ends,
times out or is cancelled, whatever it left running is killed. A step that can’t start
(no bash on the runner, a bad working-directory) fails with exit code 127.
uses#
A uses step runs an action, as in a GitHub workflow:
- the actions Moru has built in, such as
actions/checkout,actions/setup-node,actions/cacheandactions/upload-artifact, run on the runner without being fetched; - other JavaScript and composite actions are fetched from GitHub at the commit
.moru/actions.lockgives, or the one the node looks up, and run with the machine’snode; - Docker actions, and
docker://<image>, run in a container on a runner withdockerorpodman(see Containers). For adocker://step,with: { args: …, entrypoint: … }sets the command and the entrypoint; ./pathis an action in the repository.
with values are plain text: there are no expressions to fill in. A uses step doesn’t
get the job’s secrets. The list of built-in actions, the actions that can’t run, and how
to lock them are in Running GitHub workflows.
Calling a workflow#
A job can call another workflow of the same repository instead of running steps. The
called file says it can be called with a call trigger:
# .moru/workflows/checks.yml
on:
call:
inputs:
level: { type: choice, options: [quick, full], default: quick }
env:
CARGO_TERM_COLOR: always
jobs:
lint:
steps:
- run: cargo clippy --workspace -- -D warnings
- run: echo "version=$(git describe --tags --always)" >> "$MORU_OUTPUT"
test:
needs: lint
matrix:
os: [linux, macos]
runs-on: '{matrix.os}'
steps:
- run: scripts/test.sh "$MORU_INPUT_LEVEL" # .moru/workflows/ci.yml
on:
change: {}
push: { branches: [main] }
manual:
inputs:
level: { type: choice, options: [quick, full], default: quick }
jobs:
checks:
uses: ./.moru/workflows/checks.yml
with: { level: '{input.level}' }
image:
needs: checks
steps:
- run: docker build -t "app:$MORU_NEEDS_CHECKS_VERSION" . uses is the path of a .yml or .yaml file directly in .moru/workflows/, starting
with ./. Files in subfolders, in .github/workflows/ and in other repositories can’t
be called. The called file is read at the same commit as the calling one, so a change
that edits checks.yml runs its own version of it.
Calling a file without a call trigger is an error. A file whose only trigger is call never runs on its own: the CI tab doesn’t list it, and moru-runner ci run lists
its jobs only under the workflows that call it. A file with call and other triggers
runs both ways. When a file is called, only its jobs, its env and its call inputs
count. Its other triggers, paths and cancel-superseded apply when it runs on its
own; whether the run happens at all is up to the calling workflow.
IDs, names and needs#
The calling job is replaced by the called file’s jobs. Their IDs are <caller>/<job>,
here checks/lint and checks/test, and each nested call adds a level: checks/unit/test. That’s how required jobs, moru-runner ci run and MORU_JOB name
them: ci/checks/lint. Requiring ci/checks matches no job, so it blocks the merge.
Their names are the calling job’s name and their own, checks / test, with matrix
values added as usual: checks / test (linux).
- A called job without
needsin its own file needs what the calling job needs. - A job that needs the calling job waits for every called job.
- A called job’s own
needsname jobs of its file by their IDs there:testneedslint.
when#
The calling job’s when applies to every called job, and so does the called job’s own:
a called job runs only when both match. always: true on the calling job reaches the
called jobs that take its needs, in place of their own always. The run’s trigger is
what both see, and MORU_TRIGGER is never call.
Matrix on the calling job#
A calling job can have a matrix: the workflow is then called once per combination.
Each called job gets the calling job’s matrix keys first, then its own, and runs once
per combination of both. A key in both, or two keys that give the same variable, is an
error. Steps read the calling job’s keys as MORU_MATRIX_<KEY> too. A run still has at
most 256 jobs, matrices expanded.
Passing inputs#
with gives the called file’s call inputs by name. A value is one string, number or
boolean, kept as text (true, 3). A name the called file doesn’t declare is an
error, and so is leaving out a required input that has no default. An input with leaves out gets its default, else "", false or the first option; a number without a
default gets no variable.
Two placeholders bring in the calling workflow’s values:
{input.<name>}: an input of the calling workflow, undermanualorcall. In a file that is itself being called, only itscallinputs have a value, so only those can be passed on.{matrix.<key>}: a key of the calling job’s matrix.
Other braces are text. Each value is checked against the input’s type when the workflow is read:
with value | Fits |
|---|---|
| Text | A value of the input’s type: true or false, a number, one of the options. |
{matrix.<key>} alone | An input every value of the key fits. |
{input.<name>} alone | An input of the same type, or a string. A choice passes to a choice whose options include all of its own. |
| Text mixed with placeholders | A string input. |
A push, change or scheduled run has no manual inputs, so there {input.<name>} reads
the calling workflow’s default for it, else "", false or the first option. A number
without a default has no value: as a whole value, the called input gets no variable;
inside other text, it’s empty.
Called jobs read only their own file’s inputs, as MORU_INPUT_<NAME>. The run’s inputs
don’t reach them unless the calling job passes them in with.
Outputs#
A job that needs the calling job reads every called job’s outputs as MORU_NEEDS_<CALLER>_<KEY>. Above, image reads the version that checks/lint writes as MORU_NEEDS_CHECKS_VERSION. Outputs of several called jobs are merged in the
order of their IDs, the later winning on a key.
Inside the called file, jobs read each other by their IDs there: test reads lint’s version as MORU_NEEDS_LINT_VERSION. A called job that took the calling job’s needs reads those jobs under the names the calling file gives them.
env and secrets#
A file’s env reaches only its own jobs. The calling workflow’s env doesn’t reach the
called jobs: pass values in with.
Secrets aren’t passed. A called job lists the secrets it needs in secrets:, as any job
does, and gets them by name from the runner’s ci.toml, scoped by the run’s
repository, ref and trigger. secrets next to uses is an error.
Limits#
| Limit | Value |
|---|---|
| Levels of calls | 10, the calling workflow included |
| Calls in one workflow, nested ones included | 256 |
| Calls by the workflows of one push, revision or start | 256 |
| Called files of one push, revision or start | 8 MiB |
| Jobs in a workflow, its calls replaced | 256 |
| Jobs in one run, matrices expanded | 256 |
A file can’t call itself, directly or through others. A problem in a called file
refuses the calling workflow. The finding is at the calling job’s uses, and names the
file, line and column of the problem: .moru/workflows/checks.yml:12:7: ….
Patterns#
targets, branches, tags and paths take lists of patterns with GitHub’s rules, so
a pattern means the same here as in a GitHub workflow:
| Pattern | Matches |
|---|---|
* | Any characters except /. |
** | Any characters, / included, even inside a name: **.js matches a/b/c.js. **/README.md also matches README.md. |
? | Zero or one of the character before it: *.jsx? matches page.js and page.jsx. |
+ | One or more of the character before it: v1.[0-9]+ matches v1.10. |
[...] | One character from the class: letters, digits and ranges such as a-z or 0-9. |
\ | The next character as it is: \* matches a *. |
! | At the start of an entry: exclude what it matches. |
There’s no wildcard for exactly one character. The last pattern in a list that matches
decides, so ["docs/**", "!docs/drafts/**"] matches docs/a.md but not docs/drafts/b.md. A list needs at least one pattern that doesn’t start with !.
Environment#
Each step runs with the runner’s environment, then these, later ones winning:
- the workflow’s
env, then the job’senv; MORU_MATRIX_<KEY>for each matrix key, andMORU_INPUT_<NAME>for each manual input (in a called job, each input of its own file);- the step’s
env; - each secret the job lists, as a variable of its name;
MORU_NEEDS_<JOB>_<KEY>for each output of each job it needs;MORU_SERVICE_<ID>_HOSTandMORU_SERVICE_<ID>_PORT_<n>for each of the job’s services;- the variables below, which nothing overrides.
| Variable | Value |
|---|---|
CI | true |
MORU_CI | 1 |
MORU_RUN_ID | The run’s ID (local in moru-runner ci run). |
MORU_JOB | The job’s ID (checks/lint for a called job). |
MORU_COMMIT | The commit being tested. |
MORU_REF | The pushed branch or tag, a change’s target branch, or the ref a manual run was started on, as a full ref (refs/heads/main). |
MORU_TRIGGER | change, push, manual or schedule. |
MORU_REPO | owner/name. |
MORU_OUTPUT | A file to write outputs to. See Outputs. |
TMPDIR | A temporary directory of the job’s own, removed afterwards. |
MORU_ARTIFACTS | Where the artifacts of the jobs it needs are unpacked, one folder per name. Set only when there are some. |
Steps also get GitHub’s command files, GITHUB_OUTPUT, GITHUB_ENV, GITHUB_PATH, GITHUB_STATE and GITHUB_STEP_SUMMARY, so actions work in native workflows. What a
step writes to GITHUB_ENV and GITHUB_PATH reaches the steps after it. Of the
commands a step prints, a native run step reads only ::add-mask::<value>, which hides
the value in everything logged after it; other :: lines are plain output. The other GITHUB_* and RUNNER_* variables are for GitHub workflows only.
In MORU_MATRIX_<KEY> and MORU_NEEDS_<JOB>_<KEY>, the names are upper-cased and every
character other than a letter or digit becomes _: matrix key node-version is MORU_MATRIX_NODE_VERSION.
Variable names in env are letters, digits and _, not starting with a digit. Values
are strings and can’t hold matrix placeholders.
In a job with a container:, steps get only these variables and the container’s own,
not the runner’s environment, and PATH is the image’s.
The runner removes from the steps’ environment its own token (MORU_RUNNER_TOKEN), MORU_TOKEN, the model credentials (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, CODEX_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_CLOUD_ACCESS_TOKEN) and every variable its ci.toml reads a secret from, so a
job sees only the secrets it lists. The token that fetched the commit is never in the
environment, the checkout’s git config or its remote URL.
Outputs#
A step passes values to later jobs by appending key=value lines to $MORU_OUTPUT:
echo "version=1.4.2" >> "$MORU_OUTPUT" - Keys are letters, digits,
-and_, starting with a letter or_. Other lines are skipped, with a note in the log naming the line number. - The runner reads the first 64 KiB and keeps 100 outputs. A key written twice keeps its last value.
- Secret values are replaced with
[redacted], and an output whose key holds a secret is dropped. - A job’s outputs over 128 KiB in all are dropped.
A job that needs version reads version’s version output as $MORU_NEEDS_VERSION_VERSION. When the needed job has a matrix, its combinations’
outputs are merged in matrix order, the last combination winning on a key. Outputs are
reported also when the job fails.
Logs and step markers#
Each step’s output goes to the log line by line, on stdout or stderr. The runner
adds its own lines on the runner stream, among them a marker before and after each
step:
::step 1 unit tests
::step-end 1 0 5321 ::step <n> <name> starts a group and ::step-end <n> <exit code> <milliseconds> ends
it. n is a running count from 1 of every group the job logs, an action’s pre and post parts included, so it can be ahead of a step’s place in the file. Messages about
a step, such as why a job failed, name the step by its place in the file. A step stopped
by a timeout ends with exit code 124, one stopped by a cancel with 130. Steps after the
one that stopped the job don’t run and get no markers. The run page groups the log by
these markers, read from the runner stream only, so a step printing ::step itself
doesn’t confuse it.