Docs
Docs menu

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.
  • true and false are the only booleans. yes, no and on are strings, so the on: key works as written.
  • Numbers keep their text as written: a matrix value 3.10 stays 3.10, and 007 stays 007.
  • 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:

LimitValue
Size of a workflow file256 KiB, UTF-8
Workflow files per commit64, by name; the rest are ignored
Jobs a workflow defines256
Jobs in one run, matrices expanded256
Jobs one push, revision or start can queue1,024, over all its workflows
A job’s timeout4 hours
A run’s stored plan1 MiB
A run’s job specs, expandedabout 16 MiB
Plans of one push, revision or start8 MiB, over all its workflows
Job specs of one push, revision or startabout 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#

KeyTypeDefault
namestringthe file nameA name for people. It can’t hold a matrix placeholder.
onmapRequired. When the workflow runs: see Triggers.
pathslistno filterRun only when a changed file matches. See paths. The same as paths on both change and push; set it here or there, not both.
envmapVariables for every step of every job. See Environment.
jobsmapRequired, at least one. See Job keys.
cancel-supersededbooleantrueWhether 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.

TriggerKeysRuns
changetargets: branch patterns; pathsFor every new revision of a change. With targets, only for changes whose target branch matches.
pushbranches, tags: branch and tag patterns; pathsWhen 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.
manualinputs: see Manual inputsWhen a person with write access starts it on the CI tab or with the API, on a branch or tag.
schedulea list of cron lines, each with an optional timezone: see scheduleAt the times the cron lines give, from the default branch’s workflow.
callinputs: see Call inputsWhen 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.

KeyTypeDefault
typestringstringstring, boolean, choice or number. environment isn’t supported.
descriptionstringShown in the Run workflow dialog.
defaultThe value when none is given. It must be of the input’s type, and one of the options for a choice.
requiredbooleanfalseA start must give a value, unless there’s a default.
optionslistRequired 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
KeyTypeDefault
cronstringRequired. 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).
timezonestringUTCAn 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.

KeyTypeDefault
namestringthe job’s IDA name for people. May hold {matrix.<key>}.
needsstring or list of IDsJobs that must finish first. Each must be a job in this workflow, and they can’t form a cycle.
whenmapevery triggerRun only for some triggers. See when.
runs-onstring, list or mapany runnerRunner labels; the runner must have all of them. Or a map that names a runner: see runs-on. May hold {matrix.<key>}.
matrixmapOne job per combination of values. See matrix.
envmapVariables for every step of this job.
timeoutstring60mA whole number and a unit, s, m or h: 90s, 30m, 2h. More than zero, at most 4h. 1h30m isn’t accepted: write 90m.
secretsstring or listNames of secrets the job needs from its runner’s ci.toml: letters, digits and _, not starting with a digit. See CI secrets.
stepslistRequired, at least one, unless the job has uses. See Step keys.
cachemapDirectories to keep between runs on the runner. See cache.
artifactsmapFiles to upload for later jobs and for people. See artifacts.
containerstring or mapAn image to run the steps in. See container.
servicesmapContainers to start next to the job, such as a database. See services.
usesstringCall a workflow of this repository instead of running steps: ./.moru/workflows/<file>.yml. See Calling a workflow.
withmapThe 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] }
KeyType
runnerstringThe name of the runner that must run the job: lowercase letters, digits, ., - and _. A runner registered from the Runners page is named <handle>-<name>.
labelsstring or listLabels 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]
KeyType
keystringRequired. 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.
pathsstring or listRequired. 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-keysstring or listPrefixes 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 }
KeyType
imagestringRequired. 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:…).
envmapVariables set in the container, as env above.
portslistPorts of the container to publish on the machine’s 127.0.0.1. See Ports.
volumeslistExtra mounts, as docker run -v takes them: /host/path:/path[:ro], or a named volume.
optionsstringMore docker create options, split as a shell would. Some are refused: see options.
credentialsmapA 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:

KeyType
commandstringThe container’s command, instead of the image’s. Split as a shell would.
entrypointstringThe 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:

VariableWithout container:With container:
MORU_SERVICE_<ID>_HOST127.0.0.1the service’s ID
MORU_SERVICE_<ID>_PORT_<n>the port on 127.0.0.1 for TCP nn
MORU_SERVICE_<ID>_PORT_<n>_UDPthe same for UDPn

<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, --net and --entrypoint: the runner sets them (use entrypoint on a service);
  • -p, --publish, -P and --publish-all: list ports in ports:, which publishes them on 127.0.0.1 only;
  • a --label (-l) starting with moru.: the runner’s own labels;
  • -e NAME or --env NAME without a value, --env-host, --env-merge, --env-file and --label-file: they would read the runner’s own environment or files (set variables in env:);
  • -- or a word that isn’t an option or an option’s value.

credentials#

KeyType
usernamestringThe registry user name.
username-secretstringOr a secret that holds it. One of the two is required.
password-secretstringRequired. 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#

KeyType
changemaptargets, as for the change trigger.
pushmapbranches and tags, as for the push trigger.
alwaysbooleanRun 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’s name, runs-on (runner included), a cache’s key and restore-keys, artifact names, the image of its container and services, and the with values 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 the with values of a job that calls a workflow (see Passing inputs).
  • Values of keys the name doesn’t use are added to it in brackets, so every combination has its own name: test (linux, 20), or test linux (20) for name: test {matrix.os}.

A job that needs a matrix job waits for all its combinations.

Step keys#

KeyTypeDefault
runstringThe script to run, not empty. A step has run or uses, not both.
usesstringAn action to run instead: owner/repo[/path]@ref, ./path or docker://<image>. See uses.
withmapInputs for a uses step, as plain strings.
namestringrun’s first lineA name for the log.
envmapVariables for this step.
working-directorystringthe checkoutA directory in the checkout, relative to its root. It must exist and stay inside the checkout: no absolute path, no .., no link out.
shellstringbashbash runs bash -eo pipefail -c <run>; sh runs sh -e -c <run>. Not on a uses step.
continue-on-failurebooleanfalseIf 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/cache and actions/upload-artifact, run on the runner without being fetched;
  • other JavaScript and composite actions are fetched from GitHub at the commit .moru/actions.lock gives, or the one the node looks up, and run with the machine’s node;
  • Docker actions, and docker://<image>, run in a container on a runner with docker or podman (see Containers). For a docker:// step, with: { args: …, entrypoint: … } sets the command and the entrypoint;
  • ./path is 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 needs in 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 needs name jobs of its file by their IDs there: test needs lint.

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, under manual or call. In a file that is itself being called, only its call inputs 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 valueFits
TextA value of the input’s type: true or false, a number, one of the options.
{matrix.<key>} aloneAn input every value of the key fits.
{input.<name>} aloneAn input of the same type, or a string. A choice passes to a choice whose options include all of its own.
Text mixed with placeholdersA 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#

LimitValue
Levels of calls10, the calling workflow included
Calls in one workflow, nested ones included256
Calls by the workflows of one push, revision or start256
Called files of one push, revision or start8 MiB
Jobs in a workflow, its calls replaced256
Jobs in one run, matrices expanded256

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:

PatternMatches
*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:

  1. the workflow’s env, then the job’s env;
  2. MORU_MATRIX_<KEY> for each matrix key, and MORU_INPUT_<NAME> for each manual input (in a called job, each input of its own file);
  3. the step’s env;
  4. each secret the job lists, as a variable of its name;
  5. MORU_NEEDS_<JOB>_<KEY> for each output of each job it needs;
  6. MORU_SERVICE_<ID>_HOST and MORU_SERVICE_<ID>_PORT_<n> for each of the job’s services;
  7. the variables below, which nothing overrides.
VariableValue
CItrue
MORU_CI1
MORU_RUN_IDThe run’s ID (local in moru-runner ci run).
MORU_JOBThe job’s ID (checks/lint for a called job).
MORU_COMMITThe commit being tested.
MORU_REFThe 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_TRIGGERchange, push, manual or schedule.
MORU_REPOowner/name.
MORU_OUTPUTA file to write outputs to. See Outputs.
TMPDIRA temporary directory of the job’s own, removed afterwards.
MORU_ARTIFACTSWhere 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.

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