Workspaces
A throwaway clone of one git repository for one run: set up by the repository itself, changed through the workspace tools, pushed to a branch, and deleted when the run ends.
Onboarding an existing project? Start with What the repository provides, or give your coding assistant the LLM instruction for migrating an existing workspace. To set up the whole team as well (token, MCP server, code host, team clone and schedules), follow An engineering team on your repository.
What a workspace is
A workspace is a clone of one git repository, made for one run and deleted when that run ends. A member reads, changes, tests and commits code in it, and pushes the result to a branch. Nothing in it outlives the run except what was pushed.
A run gets a workspace only when its task declares workspace tools: workspace.read_file, workspace.edit,
workspace.run_command, workspace.git_push and the rest, each listed by name like any other tool. A task
without them never clones anything. What each tool takes and returns is in the
workspace tools reference.
Everything a workspace does is plain git and the repository's own tooling: it clones, branches, commits, merges and pushes through the repository's remote, and sets up and checks the code with the commands the repository declares (see What the repository provides). None of that depends on where the repository is hosted: the remote's address says which host it is, and the credential for it comes from the code host tool you bind. The task that reads an issue or pull request supplies its branch name. See Where the repository lives and The branch.
The workspace tools only touch the clone. Issues, pull requests, reviews and merging happen on your code host, through the host's own MCP server, bound like any other tool: GitHub has a setup guide, and any other host's server can be bound from Tools.
Where the repository lives
A run names its repository by its git remote address, on any host that serves git: GitLab, Bitbucket, Azure Repos, a self-hosted server, or GitHub.
{ "repo": "https://git.example.com/acme/website.git" }
Nothing about the host is set in the OS. The workspace reads what it needs from the remote itself: the host from the address, and the default branch and the branches from git.
The repository is cloned the first time the run needs it, with its last 50 commits.
The credential comes from the code host tool you bind
The clone and every push use the code host tool your enterprise or team binds on Tools. A workspace reads these custom props off the binding: key → value settings added behind Custom props on its form.
| Key | What it is | GitHub's |
|---|---|---|
git.host |
The host this binding's token is valid for | github.com |
git.username |
The username git sends alongside the token | x-access-token |
git.repoTemplate |
A clone address with {repo} in it, applied to a short owner/name input |
https://github.com/{repo}.git |
git.repo |
The repository the binding's layer works in, for a run whose input names none | Usually left out |
The workspace takes the binding, among those the run reaches (task, role, member, team, enterprise, in that
order), whose git.host matches the remote's. Each tool counts once: the nearest binding of it the run reaches, so
a member's own binding without the props hides the enterprise's. Its token is given to git scoped to that host, and only over
https://, so a prompt from any other host is answered with nothing. A remote on a host no binding names is cloned
with no credential: a public repository still clones, and nothing pushes. The GitHub guide
says what to set for GitHub.
A binding may also name the repository its layer works in (git.repo), and then a run needs no repo input at
all; a run that gives one overrides it. Because a binding can carry git.repoTemplate, a short input keeps working:
{ "repo": "acme/website" }
Credentials for the repository's own commands
A task that deploys, applies infrastructure or publishes runs the repository's own commands, and those commands need the enterprise's keys: a hosting token, a cloud credential, a state store's access key. The task version names what each command reads and which bound tool it comes from, in its workspace:
{
"credentials": [
{ "tool": "railway", "as": "RAILWAY_TOKEN" },
{ "tool": "terraform-state", "as": "AWS_ACCESS_KEY_ID", "prop": "accessKeyId" },
{ "tool": "terraform-state", "as": "AWS_SECRET_ACCESS_KEY" }
]
}
tool is the prefix of a tool bound on Tools; as is the environment variable the command reads;
prop takes one of the binding's custom props instead of its secret. The value comes from the nearest binding of
that tool the run reaches, of any kind: a Secret stored on Tools for exactly this (choose the Secret kind, give it
the prefix, the value and any custom props), a web credential, or a server's token.
The value goes into the environment of workspace.run_command and nowhere else. The model never reads it, and
whatever a command prints has every value masked ([credential removed]) before the model or the run's record sees
it. A name the harness owns (PATH, HOME, TMPDIR, TMP, TEMP, GIT_*, OS_*) is refused when the version is saved.
A run whose version asks for a credential no binding holds fails workspace_credential_missing before it calls
anything, and is listed under Blockers as a credentials block: save the binding on Tools and it resumes.
A run with no repository — neither in its input nor on a binding it reaches — fails workspace_repo_missing
before it calls anything. A run that names a short owner/name no binding's git.repoTemplate expands fails
workspace_repo_no_clone_address when it opens its workspace: the OS never guesses a host for it. Tools says when
tasks work in a workspace and no binding has git.* props, and flags a binding without them when another binding
of the same tool has them.
The branch
A run works on one branch, chosen in this order:
| The run works on | When |
|---|---|
Its branch input |
The run was started with one, or the task before it handed one on. |
| The task's branch template | The task's workspace sets branch and the input fills every {key}: fix/{issue} with { "issue": 42 } is fix/42. |
os/<task slug>-<first 8 characters of the run id> |
Neither. A new branch. |
| The default branch's tip, under that same new name | The task's workspace sets onDefaultBranch: true. No input or template is read: the run works on the default branch as it is, nothing is merged into it, and it cannot push. For a task that reads or verifies the default branch itself. |
The workspace does not look up an issue or pull request to choose a branch. The task that reads it reports a
branch in its result, and the following tasks, retries and resumes inherit it while working on the same
repository and issue or pull request. Renaming an issue later does not rename the branch. If a template needs
an input that is missing (including issue_slug), the run uses the fallback branch above. A run that started
without a branch also passes the branch it was given to its successors.
A branch that exists on the remote is checked out as it is there. One that does not is created from the default branch: the branch the clone checks out, which is the repository's own default.
Kept up with the default branch
When the run's branch already exists and is behind the default branch, the default branch is merged into it and pushed before setup runs and before the member does anything, so an open pull request never falls more than one run behind. It is an ordinary merge and an ordinary push. If the merge conflicts, or the remote refuses the push, it is undone and the branch is left exactly as the remote has it, for the run to deal with.
What the repository provides
How the code is set up and checked belongs to the repository, not to the task. Tasks are shared between enterprises through the catalog and pointed at other repositories, so a task's skill never names one repository's scripts.
Setup
After cloning, the workspace runs the repository's setup. With no setup file, it works out what to run, and runs both lines when both apply:
| The repository has | Setup runs |
|---|---|
mise.toml or .tool-versions |
mise install |
package.json with a packageManager of npm, and no pnpm-lock.yaml |
npm ci, or npm install without package-lock.json |
Any other package.json |
pnpm install --frozen-lockfile, or pnpm install without pnpm-lock.yaml |
To choose for yourself, add .os/workspace.yml (or .os/workspace.yaml, or .os/workspace.json) at the root of
the repository:
# Leave setup out to use the list above. `setup: []` skips setup altogether.
setup:
- [pnpm, install, --frozen-lockfile]
- [pnpm, run, generate]
teardown:
- [node, scripts/clean-up.mjs]
- Each step is one line,
- [binary, argument, …]: no shell, and no other YAML form. In this form an argument cannot contain a comma. Use the JSON form for arguments needing commas or more complex quoting. - The binary is one of
git,node,npm,pnpmandmise. Anything else a repository needs (another language, a particular version of Node) comes through mise: declare it inmise.toml, andmise installinstalls it. setupruns in order after every clone. If a step exits non-zero, the clone is thrown away and the workspace call fails withworkspace_setup_failed, naming the binary and the start of its output. The member is handed the error, and its next workspace call tries again.teardownruns when the workspace is deleted. A step that fails there is ignored.- The JSON form is the same two lists:
{ "setup": [["pnpm", "install"]], "teardown": [] }.
An explicit setup replaces all auto-detection. Include mise install yourself if your setup needs tools
declared in mise. There is no automatic os:setup or task-level startup hook: if you define an os:setup mise
task, call it explicitly from this file. Steps run from the repository root. Put shell logic and subdirectory
commands in repository scripts or mise tasks, then invoke those through an allowed binary.
Keep only one manifest: if several exist, .yml wins over .yaml, then .json.
For Yarn, Bun or a non-Node stack, provide explicit setup; auto-detection does not select those package managers.
Use locked, reproducible installs, generate anything a clean checkout needs, and install the repository's git hooks.
The environment is non-interactive, with CI=true, NODE_ENV=test and a fresh home directory. Do not depend on
your laptop's shell profile, global packages, local .env files or an existing database. Document any private
package access, test services or other prerequisites; binding a code host does not configure those for you.
After that setup, if the clone depends on @playwright/test or playwright, the OS installs Chromium for the
installed version into a shared cache (<runnerRoot>/.playwright-browsers/<version>) and sets
PLAYWRIGHT_BROWSERS_PATH on every workspace command. A cache hit is reused; a failed install is a warning on
run.workspace_ready and does not fail setup. The install does not run apt (--with-deps): the run-host image
must already include Playwright's Chromium system libraries (the production worker image does). Set
playwright: false in .os/workspace.yml to skip this, even when the package is present. Workspace commands still
get PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 then, so a repository that opts out installs its browser in its own setup
(for example npm exec -- playwright install chromium).
Services: a database for each run
A repository whose commands need a real database, to prove its migrations for example, can ask for one in the same file:
services: [mysql]
setup:
- [pnpm, install, --frozen-lockfile]
services is a list: services: [mysql] on one line, services: with one - mysql per line below it, or
"services": ["mysql"] in the JSON form. Leave it out and the run gets none. The one service today is mysql. Any
other name fails the setup with workspace_service_unknown:<name>. The OS never skips a service it does not know.
For mysql, each run gets an empty MySQL database of its own and a user with every privilege on that database and
on no other. Both are made before any of the repository's commands run, so the setup steps can use them as well as
the commands a task runs. Every command has exactly these five variables:
| Variable | What it holds |
|---|---|
WORKSPACE_MYSQL_HOST |
The database server's host |
WORKSPACE_MYSQL_PORT |
Its port |
WORKSPACE_MYSQL_USER |
The run's own user |
WORKSPACE_MYSQL_PASSWORD |
That user's password, new for each run |
WORKSPACE_MYSQL_DATABASE |
The run's own database |
Read them in your own scripts, for example to build a connection URL for your migration tool. The password is removed from anything a command prints before a member or the run's record sees it. The database is never the OS's own, and a run cannot reach any other run's.
The database and the user are destroyed with the workspace when the run ends, whether it succeeded or failed, after
the teardown steps. Anything a run leaves behind is dropped once it is six hours old. Nothing in it outlasts the run,
so a run starts from an empty database every time.
If the deployment has no database server for workspaces, or a run's workspace cannot reach it, the setup fails with
workspace_service_unavailable:mysql, and says why, before any of the repository's commands run. The run is blocked
and shown on Blockers. It never runs without the database the repository asked for.
Wiring mise.toml
Keep the project's existing language, package manager and test framework. Mise supplies a common command name
for each operation; the implementation stays in your repository. Add to an existing mise.toml rather than
replacing it. This tasks-only Node example delegates to scripts you must implement using the contracts below:
[tasks."os:red"]
description = "Run changed tests under tests/ with the project's test framework; print a short result (a line per test file and per failing test, full output to a file) and preserve the RED exit codes."
run = "node scripts/os-red.mjs"
[tasks."os:check"]
description = "Run lint, typecheck, tests and prerequisite builds; accept an optional issue number."
run = "node scripts/os-check.mjs"
[tasks."os:coverage"]
description = "Measure coverage of changed source lines against this project's thresholds."
run = "node scripts/os-coverage.mjs"
Replace the descriptions, paths and commands with your project's real ones. Trailing arguments must reach the
scripts: os:red accepts an issue number; os:check and os:coverage accept an optional one. Wrappers must
preserve exit codes. A task that just prints success does not implement a hook.
If you need pinned runtimes, add a [tools] table using versions compatible with the project. Run tools through
mise run or mise exec when they need mise's environment; installation alone does not activate a later bare
command. Check configuration trust in a fresh, non-interactive home directory. A reviewed config that requires
trust can be trusted explicitly in setup with [mise, trust, mise.toml] before installation. Keep complex shell
logic in scripts so template delimiters in inline commands do not unexpectedly trigger mise's trust checks.
See mise's task configuration and
trust command.
Git hooks
The repository's own git hooks run on the commits and pushes a member makes, once setup has installed them (a
prepare script that installs hooks runs as part of pnpm install or npm ci). The workspace tools never skip
them, and refuse the usual ways around them. A hook that fails refuses the commit or the push, and its output goes
back to the member to fix.
The engineering workflow commits and pushes deliberately failing tests before implementing them. Keep static
checks (formatting, lint and typecheck) working at that stage, while allowing genuine RED assertion failures to
reach the branch. If your hooks require every test to pass before any commit or push, adapt that policy explicitly
for the RED stage. Keep full tests and coverage before merge, in the verification below. Never solve this with
--no-verify, HUSKY=0, skipped tests or a blanket hook bypass.
Verification before merge
The engineering tasks verify a head in the workspace and record it on the pull request. The task that ran the
repository's check (os:check, part by part, and os:coverage) posts one note per head it checked, headed
## Verification: <commit>, naming each part and its exit, the coverage verdict, and the run that did it. The merge
task reads the newest note for the head it would merge before it asks for approval, and names the verified commit in
what the approver reads. A head nobody verified, such as a push a person made or the head after an update from the
default branch, is verified by a task of its own first. The OS runs no CI and reads no check run; a repository with
its own CI may have its tasks read that too. workspace.git_push answers the branch and the commit it pushed, so the
note names exactly what went up.
Commands for the engineering tasks
The engineering tasks in the catalog (writing an issue's tests, implementing it, validating it) never run a
repository's scripts by name. They call three mise tasks, and the repository's
mise.toml says what each one does:
| Command | Called as | What it has to do |
|---|---|---|
os:red |
mise run os:red <issue> |
Run the issue's tests: the test files the branch adds or changes against the default branch, including uncommitted tests. Print a short result a task can read whole, however many packages the tests touch: one line per test file with its path and its failed and passed counts, one line per failing test with its package, its name and the first line of its failure message, no passing tests, stack traces or colour codes, and the exit code last. Keep it under 10,000 characters; past that, count the failing tests left out on one line. Write the test runners' full output to a file, and name that file in the result. Exit 0 when every test passes, 1 for assertion failures, 3 for no suite (red_suite_missing), 4 for typecheck failures (red_suite_typecheck), and 5 for skipped, focused or todo tests (red_suite_skips). Its mise description says where tests live and which framework runs them: the task that writes tests reads it. |
os:check |
mise run os:check [issue] |
Everything to run once before committing: lint, typecheck, tests, and whatever build they need first. Exit 0 when it all passes. |
os:coverage |
mise run os:coverage [issue] |
Measure test coverage of the source lines the branch adds or changes, against the repository's own thresholds. Exit 0 when they are met or no measurable source changed; otherwise exit non-zero and list uncovered changed lines per file. |
os:test:summary |
mise run os:test:summary |
Optional. Print the test evidence the last os:red, os:check and os:coverage runs left in the clone, as a markdown table for a pull request: one row per phase and command, with the result, the passed, failed, skipped and todo counts from the test runners' own reports, the exit code, the duration and the commit tested. Read-only: it runs no test. A command that left no report reads no_test_results, never zero passing. |
A repository that has os:test:summary keeps that evidence by running the three commands through a test-report
wrapper, such as os-test-report from @juicyllama/repo 1.3.0:
os-test-report run --phase red|check|coverage --label 'mise run os:<name>' -- <the command>. The wrapper keeps the
command's exit status, and leaves .os/test-results/<run>/ (ignore it in git) with the full output.log, the
runners' native reports and the counts. It sets OS_TEST_REPORT_DIR for the command, so the command writes each
suite's report there: the runners' own JSON reports, and for a merge-base rerun a baseline/ directory, which is not
counted. A check that replays a cached result writes no report, so read nothing from a build cache for the test
runs. os:red's exits 3, 4 and 5 read red_suite_missing, red_suite_typecheck and red_suite_skips, 6
pre_existing_failure and 7 environment_failure. The tasks that post a pull request's test evidence read
os:test:summary when a repository has it, and say native counts are unavailable when it does not.
Use the remote's actual default branch, not a hard-coded main. Comparisons need its merge base with the working
branch. A shallow clone may need a fetch or deeper history before that can be calculated; a missing base is an
error, never an empty diff or a passing check. The issue number identifies the work, not a required test filename.
Tests should use the repository's normal locations and naming conventions. A RED test must import and typecheck
successfully, then fail on an assertion; missing modules, syntax errors and crashed runners are not valid RED proof.
os:check and os:coverage may also support these diagnostic exits:
| Exit | When it is valid |
|---|---|
| 6 | Every failure is a test proved to fail on the branch's merge base with the default branch too. Print pre_existing_failure: <file> › <test> (fails on <sha>) for each. Changed test files, broken suites, lint and typecheck failures do not qualify. |
| 7 | The test runner itself crashed, a retry also crashed, and there is no failure attributable to the branch. Print runner_crashed: <task>: <reason>. An exception in application code is not a runner crash. Also valid when no test runner started because the host had no room for one within a bounded wait, and nothing failed: print a host_short: line naming the free and maximum slots. |
Implement these only when the scripts can establish that evidence. Otherwise return an ordinary failure. Never relabel a failure just to make the workflow continue.
A repository with no os:red stops those tasks with a message saying it needs one. Any task can run whatever else
the repository's mise.toml defines, through workspace.run_command.
A check has to fit one command
Every command a member runs has limits: ten minutes, and 32,000 characters of output. A check that runs past the first is stopped before it can say what failed, and one that prints past the second is cut short. So:
- Print what failed, not everything. Keep the full output in a file in the clone and print where it is. A member can read the file when it needs to.
- Split a check that cannot finish in ten minutes.
mise run os:check --partsprints the name of each part, one per line, andmise run os:check --part <name>runs that part over the whole repository, with the same exit codes. A task that checks a whole branch asks for the parts and runs each in turn. A task that checks one issue asks with the issue,mise run os:check --parts <issue>: accept the number there, and print either every part or only the parts that issue's branch needs. A repository that does not answer--partsis checked with onemise run os:check. - Run each test once when coverage runs too. A task that runs
os:coverageafteros:checkasksmise run os:check --parts --covered-by-coverage <issue>. A repository whose coverage measurement runs some of the same tests, and fails on a failing test with the same exit codes, leaves those test parts out of the list. A repository that does not know the flag refuses it, and the task asks again without it. - Split a coverage measurement the same way.
mise run os:coverage --partsprints the parts for the branch as it is, one per line in the order to run them, andmise run os:coverage --part <name>runs one. Every part but the last only measures. The last prints the verdict, with the exit codes of the whole command, and must refuse to judge a part that has not run or that measured the branch before a later change. A repository that does not answer--partsis measured with onemise run os:coverage. - Measure with the tests that can reach the change. A measurement of the lines a branch changed learns nothing
from a test that never loads a changed file. A repository can run only the tests that can, and should when its
whole suite takes longer than a part. The tests it leaves out still run in
os:check, so it must not ask--covered-by-coverageto leave their parts out. - Keep every part well inside the limit. A part is as long as the longest thing in it that cannot be divided. When one test file alone takes most of ten minutes, adding parts does not help: run that file's tests across several parts, each test in exactly one. The last part must still fail on a test that failed in any part.
A command plans for four CPUs
A workspace shares its machine with other runs. Every command is held to a CPU budget of 4, so a build or a test runner that starts one worker per CPU starts four, not one for every core of the host.
Most tools see the budget without being told: nproc, Node's os.availableParallelism(), Go, Rust and the JVM count
the CPUs a command may run on. Node's os.cpus() and os.availableParallelism() do too: every spawn command is
started with a preload in NODE_OPTIONS that lists the CPUs it may run on, or OS_CPU_BUDGET when that is smaller,
ahead of any NODE_OPTIONS your command sets. Some tools count the
machine's cores anyway, such as Python's os.cpu_count(), and a tool built on those still sizes itself from the host.
For those, every command's environment carries OS_CPU_BUDGET. Read it where the tool takes its worker count, in its
config or in your mise run os:* task:
const workers = Number(process.env.OS_CPU_BUDGET) || undefined
A command that starts far more processes and threads than that can run the machine out of them. It then fails with
EAGAIN or Resource temporarily unavailable on code that builds anywhere else.
The machine's process and thread limit is shared by every run on it. A machine near its limit starts no new run until
it has room again, and another machine takes the run. A run with a command the machine had no room to start is
not blocked: its work is pushed to its branch, and it goes back to the queue by itself, to carry on where it stopped
on a machine with room. Its history says workspace_resource_exhausted:EAGAIN, with how many processes and threads
the machine held of how many it allows: workspace_resource_exhausted:EAGAIN pids.current=998 pids.max=1000. A run
that meets it five times in a row is one whose own commands need more than a machine has, and it waits on Blockers.
The same immediate path is taken when a command starts and then dies because the machine had no room: a test runner
crash, a browser that could not launch or crashed under load, or a heap limit. A test part that never starts because
the host is too busy (host_short:, exit 7) is classed workspace_resource_exhausted:HOSTSHORT and requeues later,
on a backoff of 2, 5, 15, 30 and then 60 minutes, instead: retrying at once would land on the same busy machine. It
waits on Blockers, and is escalated, only after all five of those retries are spent. A command that succeeded, or
one whose output names a failing test, always comes back to the run as it was, whatever else it printed.
Those are not failed tests. Keep your own suite's processes and threads within what a command plans for.
Temporary files and package stores
A workspace shares its machine's disk with other runs, and the machine holds only so many files. Every command's
temporary files go to the run's own temporary directory: TMPDIR, TMP and TEMP point at it, so Node's
os.tmpdir(), mktemp, Python's tempfile and most test runners' caches use it without being told. It is removed
with the workspace, so a test suite that leaves its temporary files behind leaves them for that run alone.
pnpm's store and npm's cache are kept for your organisation and shared by its runs (npm_config_store_dir and
npm_config_cache), so an install after the first one fetches and writes far less. They are never shared with
another organisation.
pnpm 11 and later do not read npm_config_store_dir, so the same store is also set as pnpm_config_store_dir.
Both are set for you, whichever version of pnpm your repository uses: there is nothing to change.
A tool that writes outside the clone and its temporary directory, to a fixed path such as /tmp/my-cache, still
fills the shared disk. Point it at TMPDIR instead.
Commands for a dependency refresh
Tasks that keep a repository's dependencies current call three more mise tasks. They are optional: a repository without them is not offered a refresh. Which package manager it uses, what counts as out of date and how a version is changed are the repository's own. The tasks name no package manager, so the same tasks work on any repository that answers these commands, and a repository can cover container images or CI actions by changing its own script.
| Command | Called as | What it has to do |
|---|---|---|
os:deps |
mise run os:deps |
Print what is out of date, in the form below. Exit 0 when the report is complete, with or without updates. Exit 2 (scan_failed) when the scan could not be completed: never print an empty report for a scan that failed. |
os:deps:apply |
mise run os:deps:apply [--major] <name@version>... |
Move each named dependency to exactly the version named, and update the lockfile. Without --major, stay on its current major. Skip one that is already there, so a line can be run again. Exit non-zero, changing nothing, when an argument matches nothing the repository declares. |
os:deps:verify |
mise run os:deps:verify |
Exit non-zero, naming each one, when a dependency now resolves lower than on the commit the branch started from. |
The report is markdown, because a task copies parts of it into issues as they are:
updates: 2 security: 1 majors: 1 held: 1
## Updates to apply
| Package | Current | Target | Level | Security | Note |
| ------- | ------- | ------ | ----- | -------- | ---- |
| `left` | 1.0.0 | 1.0.1 | patch | high | |
| `right` | 2.1.0 | 2.2.0 | minor | | |
Apply in this order, running the checks after each group:
1. Security: `mise run os:deps:apply [email protected]`
2. Minor: `mise run os:deps:apply [email protected]`
## Majors
### Major upgrade: framework 3 to 4
- `framework` 3.2.0 to 4.1.0 (released 2026-08-25)
- Release notes: https://example.com/framework/releases
- Apply: `mise run os:deps:apply --major [email protected]`
## Held back
- `odd` 1.0.0: the registry names no version to compare
What the tasks rely on:
- The first line is the counts.
updatesandmajorsboth 0 means there is nothing to do. ## Updates to applyholds the changes that are safe to make together: a table, then one runnablemise run os:deps:apply ...line for each group, numbered in the order to apply them. These become one issue, and one task runs the lines exactly as printed. What an argument looks like is the repository's choice.## Majorshas one###heading for each upgrade that may break the code, in the order to take them. The heading is used as the issue's title, so it must read the same on every scan for as long as that upgrade is on offer. A person rejects an upgrade by closing its issue as not planned, and a title that is already on an issue, open or closed, is never filed again. Under the heading: what moves, where to read what changed, and its own apply line.## Held backnames anything the scan could not decide, with the reason. Nothing is done with these.- The whole report fits in 32,000 characters. When it would not, leave out the least urgent updates and say how many were left out.
Deciding what is safe is the repository's job too. Things worth deciding there: how old a release must be before it is offered, whether a fix for a known vulnerability waits that long, and never offering a prerelease or a withdrawn release.
Runtimes are dependencies too
The runtime and the package manager (node, pnpm, npm) go through the same report, apply and verify as the
packages, so a new Node.js release, a security release above all, reaches the repository through its dependency
refresh with no person having to notice it. The scanner in @juicyllama/repo 1.3.0 reads them from every tracked
file that declares one: a mise or .tool-versions pin, .nvmrc, engines, packageManager, FROM node:<tag> and
ARG NODE_*_VERSION= in a Dockerfile, and node:<tag> images in compose files, workflows and Terraform.
- Every declaration's
file:lineis named, in the row's note or under the major's heading, so the issue says exactly what moves. - A Node security release skips the cooldown. It is offered at once, as is a package-manager release that fixes an advisory on the current version.
- A floating declaration is a
pinrow.node:26-alpinebuilds from whatever the cached tag held, so applying the row writes the exact release (node:26.12.1-alpine). It counts as a security fix while its major's latest security release is under 30 days old. - A
Security:line sits under a major whose current line is past its end of life, or has an advisory with no fix left in it, and the major counts insecurity:. - Held back, each with its
file:line: an engines floor (>=22) or a range across majors, a declaration that names no major (lts/*), an image pinned by digest, and declarations of one runtime that disagree.
A runtime move edits the declarations only and runs no install. A file generated from one of them is the
repository's own os:deps:apply task to regenerate afterwards. os:deps:verify fails on an exact runtime
declaration that went down, by its file, as it does on a package.
Commands for infrastructure
A task that applies a repository's infrastructure calls two more mise tasks. They are optional: a repository without them is never asked to apply anything. What a "stack" is, which tool plans it and where its state lives are the repository's own; the task names no tool. The credentials the commands need come from the environment the task's version declares (Credentials for the repository's own commands), never from a file in the repository.
| Command | Called as | What it has to do |
|---|---|---|
os:infra:plan |
mise run os:infra:plan <stack> |
Plan the stack against its real state and print what would change, under 5,000 characters, ending with plan-sha: <id>: a signature of the planned changes with every secret value left out. Exit 0 when nothing would change, 2 when something would, 1 on error, 9 when another run holds the state (state_locked). The summary is what the owner reads on the approval card, so name resources and the attributes that change, never a value. |
os:infra:apply |
mise run os:infra:apply <stack> --plan-sha <id> |
Plan again and apply only while the signature still matches <id>; print plan_drift and exit 8 otherwise, with nothing applied, so what the owner approved is what runs. Exit 0 when applied or nothing to apply, 1 on error, 9 locked. |
The task gates the apply on exactly that command (a gate on workspace.run_command whose match names
["mise", "run", "os:infra:apply"]), with the plan summary as the gate summary, so the owner approves the signature
the apply then holds itself to. A pull request's check runs the repository's own validation of a stack with no
credentials and no plan; the real plan is read at the apply.
Release copy: os:release
Release preparation is optional, like dependency refresh. A repository without os:release opts out.
The repository owns its note format, audience, brand rules, version mirrors and non-shipping path list.
The task writes only .release/pending/** on the PR branch, before merge approval. Runs still never bump
versions, stamp dates, tag, publish or deploy.
| Task | Result |
|---|---|
mise run os:release --pr N --base REF --labels JSON |
JSON contract: notes enabled/format/path/audience/style, brand spellings, pendingPath, deterministic bump, and nonShipping for the branch diff. Exit 0 on success; unavailable context is an error, never an opt-out. |
mise run os:release:verify --pr N --base REF --labels JSON |
Exactly one valid intent for this shipping PR, or a non-shipping diff with no intent. Exit 2 missing, 3 invalid, 4 brand lint, 5 unavailable context. |
mise run release |
CI only, outside the os:* contract. Consume all pending intents on main, bump once at the highest level, stamp each note, and print the version. No task may call it. |
N is the PR number, REF its base ref, and JSON the combined PR and linked issue label names.
Implementations may also accept RELEASE_PR, OS_BASE_REF, and RELEASE_LABELS. major wins over
minor; absent either label means patch. The model never chooses the bump.
A shipping PR writes .release/pending/pr-N.md:
---
bump: patch
title: Wallet sheets survive focus changes
description: Buyers can return to checkout without restarting payment.
tags: [Fix]
---
The customer-facing change and any integration action, in this repository's public voice.
There is no version or date. When notes are disabled, metadata remains and the body is empty. The filename is stable across retries. Existing pending files inherited from main are left alone. A branch changing only declared non-shipping paths needs no intent. Every other merge releases.
The note-writing task reads the PR, linked issue and diff, checks the contract, writes the intent and verifies before committing. The merge approval includes the bump and title so the approver sees the copy. A PR check enforces the same rules for manually written PRs. Enable that check only after the writer is available. A changed PR or linked issue label needs fresh verification before approval.
The repository's release workflow releases only a commit that passed its checks, serializes releases, pushes the
versioned main commit before its tag, and then publishes or deploys that commit. Several merged intents
can share one release version; each retains its own note. No pending intents means no release.
The public @juicyllama/repo package (1.3.0) provides the Node implementation and reusable GitHub workflows, as
well as the dependency scanner and the test-report wrapper above. Run them from the one installed version
(node node_modules/@juicyllama/repo/...) rather than fetching a second copy, so a bump of the package moves them
all. Other stacks may implement the same contract. Historical release gaps are not backfilled.
Public changelog: os:changelog
A public changelog is optional too, and separate from release copy: a repository can implement either without the
other. An enterprise that publishes stories about its finished work names the repository that hosts them once, in
the Public changelog repository setting on its Enterprise page. Shared tasks never name it, so updating one never
changes it. Every run carries it in its context as enterprise.changelogRepo, null when none is named. It is
named as owner/name or a clone address without credentials: access to a private repository comes from the code
host access the enterprise has bound, never from the address.
That repository says where a story goes, what it must look like and how it is checked. Its paths, story format, audience, voice, brand spellings and image rules are its own; the tasks that write a story name none of them.
| Task | Result |
|---|---|
mise run os:changelog --epic REF --title TEXT |
Exit 0 and print the JSON contract below. Any other exit means unavailable context: an error, never an opt-out. |
mise run os:changelog:verify --epic REF --story PATH |
Check one story against the repository's own rules before its pull request is opened, with the exits below. |
mise run os:changelog:image --epic REF --story PATH |
Optional. Make the hero image for a story already written at PATH, with the exits below. |
mise run os:changelog:release-notes --epic REF --merged OWNER/NAME#N ... |
Optional. Give back the public release-note pages for the changes a story was written from, with the exits below. |
REF is the epic the story is about, as owner/repo#number, and TEXT is that epic's title.
PATH is the story file, relative to the repository root.
Each OWNER/NAME#N is one change the story was written from: a merged pull request, in the repository it merged in.
The same inputs on the same commit always give the same answer.
So the story's path stays the same across retries, and a retried run finds the story it already wrote.
os:changelog prints one JSON object:
| Field | What it holds |
|---|---|
enabled |
false when this repository hosts no public changelog. The other fields may then be left out. |
path |
Where this epic's story goes, relative to the repository root. Decided only by --epic, --title and the tree. |
format |
The story's type, the front-matter fields it needs and what each holds, and the rules for its body. |
audience |
Who reads the story. |
style |
The voice, tense and length to write in. |
brand |
Each correct spelling, with the wrong variants a story may not use. |
neverName |
What a story must never name, on top of the rule every story keeps: no task names, issue numbers, members or unreleased work. |
links |
Optional. The public URL prefixes a story may link to. When present, a story that links outside them fails the check with exit 4. When absent, links are left to the writing rules. |
learnMore |
Optional. The public pages a story's "Learn more" section may list, each with a url, a title and an about that says what the page covers. |
images |
Optional. The rules for images: where they go (path), which formats and sizes, and the alt text each needs. hero, when present, is the hero image's width, height and formats; a hero is a png, webp, jpg or jpeg file, the only image files a story pull request may carry. |
{
"enabled": true,
"path": "changelog/export-reports.md",
"format": {
"type": "markdown",
"frontMatter": {
"title": "The story's headline",
"date": "Publication date, YYYY-MM-DD",
"tags": "One or more of Feature, Fix",
"image": "The hero image's path, from os:changelog:image",
"imageAlt": "The hero image's alt text"
},
"body": "Two to four short paragraphs, then an optional Learn more section. No other headings."
},
"audience": "People who use the product, not the team that builds it",
"style": "Plain, present tense, second person",
"brand": { "GitHub": ["Github", "github"] },
"neverName": ["Customer names", "Internal service names"],
"links": ["https://example.com/docs/"],
"learnMore": [
{
"url": "https://example.com/docs/reports/export/",
"title": "Export a report",
"about": "Exporting reports as CSV or PDF"
},
{
"url": "https://example.com/docs/billing/",
"title": "Billing",
"about": "Plans, invoices and payment methods"
}
],
"images": {
"path": "changelog/images/",
"formats": ["png", "webp"],
"maxWidth": 1600,
"alt": "required",
"hero": { "width": 1600, "height": 900, "formats": ["png"] }
}
}
Learn more. Every url in learnMore is a public page, and when links is present it sits inside one of the links prefixes.
A story's "Learn more" section, at its end, lists only learnMore entries whose about relates to the feature the story is about, each linked with its title.
The section is left out when none of them relate, or when learnMore is absent.
A prefix in links allows a link; an entry in learnMore names one page and says what it covers, so a story never invents a page to point to.
Hero image. os:changelog:image is optional: it makes the story's hero image, in the repository's own brand, once the story is written at PATH.
It writes the image under images.path, at the width and height and in one of the formats that images.hero declares, on an opaque background, so it reads on light and dark pages and in link previews.
It prints one JSON object, { "path", "alt", "text" }: path is the image file, relative to the repository root, alt is its alt text, and text is every word drawn on the image, taken only from the story's own title and summary.
So the image names nothing the story does not, and cannot contradict it.
It makes the same image for the same story on the same commit.
The story carries path and alt in the front-matter fields format names (image and imageAlt in the example above), so the changelog shows the image and uses it when the story is shared.
A hero is a png, webp, jpg or jpeg file: a hero declared in any other format is reported as an image error, and the story goes out text-only.
os:changelog:image exits:
- 0 made the image: the story uses it as its hero.
- 2 no image for this story: the story goes out text-only.
Any other exit is an error: the story still goes out text-only, and the error is reported with it, so a broken command stays visible instead of reading as no image.
A repository that does not define os:changelog:image has no generated hero images, and its stories go out text-only.
Release notes. os:changelog:release-notes is optional: it gives back the public pages of the release notes the repository publishes for the changes a story was written from, so a reader who wants the detail behind the story can find it.
The OS passes the epic as --epic and one --merged for each merged pull request the story was written from, and nothing for work still open, closed as not planned or closed unmerged.
Public release notes carry no internal references, so the match between a note and its change happens inside the repository, which knows how it releases them.
It prints one JSON list, [{ "url", "title" }]: each url is a public page, http or https with no sign-in details and, when links is present, inside one of its prefixes, and each title is the note's own title.
Nothing internal comes back: no pull request numbers, no owner/name#N references and no file paths.
It gives the same answer for the same inputs on the same commit.
The story lists the pages in a "Release notes" section, before "Learn more" when it has both, each linked under its own title, once, in the order the changes merged.
An entry that is not a public page, or whose title or url names a pull request or issue number, an owner/name#N reference or a file path, is left out, never edited to pass, and the "Release notes" section is left out when no page is left: a story never has an empty heading.
[
{ "url": "https://example.com/docs/releases/export-reports-as-pdf/", "title": "Export reports as PDF" },
{ "url": "https://example.com/docs/releases/schedule-a-report/", "title": "Schedule a report" }
]
os:changelog:release-notes exits:
- 0 the pages: the story links them in its "Release notes" section.
- 2 no published notes for these changes: the story has no "Release notes" section.
Any other exit is an error, and so is output that is not the JSON list: the story still goes out, with no "Release notes" section, and the problem is named on a "Release notes:" line of its pull request description, so a broken command stays visible instead of reading as no notes.
A failing release-notes command never stops a story.
A repository that does not define os:changelog:release-notes publishes no release notes to link, so its stories have no "Release notes" section and are otherwise unchanged.
os:changelog:verify exits:
- 0 valid: the story can be committed and its pull request opened.
- 2 story missing: there is no file at
PATH. - 3 invalid format: the story is not at
path, its front matter or body breaksformat, or it has a "Learn more" or "Release notes" heading with no links under it. - 4 public-writing lint: a wrong brand spelling, something
neverNameor the rule every story keeps forbids, a link outsidelinks, a "Learn more" link that is not inlearnMore, a "Release notes" link thatos:changelog:release-notesdoes not return for the epic's merged pull requests, an image that breaksimages, or an image whose drawn text does not come from the story's title or summary. Verify gets no--mergedlist, so for a "Release notes" link it reads every merged pull request of the epic--epicnames itself, and checks the link against the pagesos:changelog:release-notesreturns for all of them: a page the command returned for the pull requests a story was written from, which are some of that set, must pass. - 5 unavailable context: the epic, the tree or the rules could not be read. This is never a valid story.
A story with no image is valid (exit 0), whether or not the repository defines os:changelog:image.
A failed check prints what is wrong, one line per problem, as <rule>: <file>:<line>: <what>, and exits with the
code above. When a story breaks both its format and the public-writing rules, every problem is printed and it exits 3.
A "Learn more" link that is not in learnMore prints learnMore: <file>:<line>: <url> is not in learnMore.
Drawn image text that does not come from the story's title or summary is reported under images.
brand: changelog/export-reports.md:7: "Github" is spelled "GitHub"
links: changelog/export-reports.md:12: https://internal.example.net/report is outside the declared links
learnMore: changelog/export-reports.md:18: https://example.com/docs/api/ is not in learnMore
images: changelog/export-reports.md:4: the hero's drawn text "Beta for Acme" is not in the story's title or summary
An enterprise has no public changelog when any of these holds:
- it names no repository in Public changelog repository;
- the named repository does not define an
os:changelogtask; os:changelogprints"enabled": false;- the repository cannot be read with the code host access the enterprise has bound.
Then nothing fails and nothing is retried: a task that would write a story finishes without one.
A defined os:changelog that exits non-zero, or prints anything but this contract, is an error, never an opt-out.
It is reported as an error, so a broken implementation stays visible instead of reading as no changelog.
LLM Instruction for migrating an existing workspace
Open the existing repository in a coding assistant that can read and edit files and run commands, then paste the instruction below. It asks the assistant to implement and validate the integration using this page's contracts. You keep the repository, its stack and its CI; the migration adds the commands the engineering team needs. If the assistant cannot open this page, give it the page's contents before it starts.
Onboard this existing development repository as a Zero Human workspace so a cloned
engineering team can work on it. Implement the integration in this repository.
Read https://zerohuman.com/docs/tools/workspaces in full, including the setup,
verification, dependency and release contracts. Use that page as the contract.
If you cannot access it, ask me for its contents instead of guessing.
Read this repository's AGENTS.md and contributor/development instructions first.
1. Inspect before editing.
Identify the language/runtime versions, package manager and lockfiles, monorepo
layout, test frameworks and locations, lint/typecheck/build commands, git hooks,
CI requirements, coverage thresholds, release process and existing mise config.
Detect the remote's default branch. Identify required generated files, test
services and private dependencies. Preserve existing work and use an isolated
branch or worktree. Summarize the mapping from existing commands to the hooks
below, then implement it. Ask only for decisions you cannot infer safely.
2. Make setup work from a clean, non-interactive clone.
Add to mise.toml rather than replacing existing configuration. Keep the current
stack and package manager; pin compatible runtimes where needed. Use the existing
lockfile and reproducible installs. Add .os/workspace.yml only when auto-detection
is insufficient, or update the existing manifest without creating a competing one.
Explicit setup replaces ALL auto-detection: include tool installation, dependency
installation, code generation and hook installation as needed.
Each setup/teardown step is an argv array starting with git, node, npm, pnpm or
mise; there are at most eight steps in each list and 16 argv entries per step.
Put shell logic in repo scripts or mise tasks. Do not put shell strings, pipes,
redirects or cd in manifest argv. Validate mise trust and runtime activation in
a fresh home directory; do not depend on my shell profile or global packages.
Setup must work with CI=true and NODE_ENV=test. Do not copy secrets into the repo.
Document missing credentials or services instead of assuming they are available.
3. Implement the three core mise hooks with real checks.
- mise run os:red <issue>: run the test files this branch adds or changes relative
to the default branch, including uncommitted tests, and print every suite path.
Use normal test filenames, not issue-number filenames. Its description must
tell an agent where tests belong and which framework and conventions to use.
Exit 0 for green, 1 for assertion failures, 3 for no suite, 4 for typecheck
failures, 5 for skipped/focused/todo tests. Setup/import errors are not RED proof.
- mise run os:check [issue]: run lint, typecheck, tests and prerequisite builds.
Without an issue, check the whole repository. Any scoped run must cover affected
code and dependencies. Add --parts and --part <name> if the full check exceeds
ten minutes; every part must fit and a part checks the repo without an issue.
--parts accepts an optional issue and may then print only the parts it needs.
- mise run os:coverage [issue]: enforce the project's thresholds on changed source
lines, print uncovered changed lines per file, and fail below the thresholds.
Report explicitly when there is no measurable source change. If no coverage
policy exists, propose one and ask me to choose it; do not silently pick zero.
Add --parts and --part <name> if measuring exceeds ten minutes: every part must
fit, the last part prints the verdict, and it must refuse stale or missing parts.
Forward arguments and exit codes through every wrapper. Resolve the real default
branch and merge base, fetching more history when the 50-commit clone is too shallow.
Missing history must fail clearly. Keep each invocation within ten minutes and
32,000 output characters: print a verdict and failure details, save full logs to
ignored files. Bound concurrency for CI resources. Only implement diagnostic
exits 6 and 7 if you can prove the conditions in the workspace guide.
4. Preserve the RED-to-GREEN workflow and merge checks.
Git hooks must install and run normally. Deliberate assertion failures in the
RED phase must be committable and pushable to a working branch, with static
checks still enforced. If hooks or branch rules currently prevent that, identify
the conflict and make the smallest explicit adjustment permitted by repo policy.
Keep full tests, coverage and required CI checks before merge. Never use
--no-verify, HUSKY=0, skipped tests, reduced thresholds or success-only stubs.
5. Assess optional hooks; implement only what the project will use.
For dependency maintenance, implement os:deps, os:deps:apply and os:deps:verify
together, matching the report, exact-version, --major and downgrade contracts.
For release-note preparation, assess os:release and os:release:verify against the
existing release process. If adopted, implement the JSON contract and pending
intents from the guide and keep versioning/tagging/publishing/deployment in CI.
Do not replace the project's release process without agreement. Otherwise list
these optional capabilities as not configured; do not install empty placeholders.
Do not invent other mandatory os:* hooks. A helper such as os:setup only runs
when the manifest or another command explicitly invokes it.
6. Validate the integration, not just the file syntax.
In a disposable fresh clone with a clean home and CI-like environment, run the
actual setup, discover the mise tasks and run every implemented hook. Exercise
argument forwarding, os:red's no-suite case, a temporary assertion failure and
its passing counterpart, typecheck failure where applicable, and skip/focus/todo
rejection. Confirm coverage fails below its threshold and handles no changed
source. Check every os:check part if implemented. Exercise local git hooks on a
disposable branch without pushing. Remove temporary probes afterwards.
Report commands, exit codes, timings and any checks blocked by this environment.
Do not claim a hosted Zero Human run has passed from local checks alone.
7. Leave a reviewable change and an onboarding handoff.
Document the files added/changed, hook commands and descriptions, prerequisites,
coverage policy, optional capabilities and remaining blockers in the repo's
developer docs. Explain the remaining Zero Human setup: clone the engineering
team, connect a code-host MCP tool with repository access, and configure git.host
and git.username. Set git.repoTemplate for short owner/name inputs or use a full
HTTPS repo input; optionally set git.repo. Check task write globs/required files
against this repo's paths.
Cloned tasks may require their source owner's changes or an independently owned
copy; repo config does not override task permissions. Keep credentials and team
configuration out of committed files. Leave merge/deploy and the first hosted
smoke run for me to approve. Finish with what is ready and what remains unverified.
Connect the team after the repository change
Merge the reviewed onboarding files before starting new work, so fresh branches inherit the setup. Cloning a team does not configure repository credentials or make its task write rules fit every project. Connect the code host binding, check the team's task paths and required files, and configure its agents before the first run. Workspace support for a git host does not automatically translate a cloned task's GitHub issue or pull-request tools to another host's tools.
Start with a small issue on a disposable working branch. Confirm setup succeeds, the expected tests run, the member commits and pushes, and the pull request reaches the configured merge approval with the expected CI checks. Local validation proves the repository integration; this first run proves the team's bindings and workflow work with it.
What a task decides
A task version's Workspace decides which branch its runs work on and which files they may change. On a task in the portal it is Workspace JSON:
{
"branch": "fix/{issue}",
"writeAllow": ["src/**", "tests/**"],
"writeDeny": ["src/generated/**"]
}
| Field | What it does |
|---|---|
branch |
The branch template (see The branch). |
onDefaultBranch |
true keeps the run on the default branch's tip with no branch of its own and nothing to push (see The branch). |
pushAllow |
The full ref globs (refs/heads/main, refs/tags/v*, refs/heads/production) a run may push with workspace.git_push's ref besides its own branch. It is the one way a run pushes the default branch, a tag, or a branch a host builds from, never by force, and it needs a writeAllow. For a task that cuts a release. |
writeAllow |
Paths the run may change freely. A non-empty list refuses other paths unless rewriteAllow or appendOnly matches them. Matching paths may be rewritten even if appendOnly also matches. A glob may name a run input as branch does: {contentDir}/** is the folder the run's contentDir input names, so a task cloned from the catalog holds each company's runs to the folders that company set; a glob whose input is empty on a run is left out of that run. The same holds for rewriteAllow, writeDeny and appendOnly. |
rewriteAllow |
Paths the run may change freely, even where appendOnly matches, without refusing everything else. |
writeDeny |
Paths the run may never change. It wins over every other field. |
appendOnly |
Paths the run may add files and lines to, but where no line that was there when the run started may change or go. |
requireFiles |
Paths that must exist in the clone before the run starts work; each {key} is filled from the run's input. If one is missing, the run fails workspace_file_missing. |
credentials |
The values the run's repository commands need, each { tool, as, prop? }: a bound tool's secret, or its custom prop, as the environment variable as of workspace.run_command alone (see Credentials for the repository's own commands). |
Paths are globs: * stays inside one folder, ** crosses folders. A task with none of the path fields set may
change anything in the clone.
The rules are checked when a file is written, edited or deleted, again on what a commit would include (a command
can change files too), and, for appendOnly, once more on the run's own commits when it pushes. A refused write
changes nothing; a refused commit commits nothing. During a merge, a file the merge brings in may be written and
committed as the merge has it, whatever the rules say, so a run can finish a merge; a line of the run's own in
such a file is still refused.
Commits and pushes
Commits are authored and committed as the member the run belongs to: its name and the email address on its
member page. A run with no member commits as the enterprise itself, under your enterprise's name, from an os@
address on your enterprise's Zero Human mail domain.
Code hosts link a commit to an account by its email address. For commits to show under the member's own account on your host, add the member's address to that account and verify it (for GitHub, see GitHub). The push itself is made by whichever account the credential belongs to.
workspace.git_commit stages what the run changed and commits it; a new file that only a command created may need
a git add first. workspace.git_push pushes the branch to the repository's remote under the same name, as an
ordinary push: it never overwrites work someone else pushed.
If a run of a task that lists workspace.git_push finishes without a successful push while its workspace holds
changes or commits the remote does not have, it fails: git_push_missing, or the reason the commit or push was
refused. Work is not lost behind a success. If a run runs out of steps, or its model call fails, the OS commits and
pushes what it had before the run fails, where the task's rules allow, so a retry picks up from there. A task that
gates its own push gets no such save (see What waits for you).
What is never allowed
- Pushing the default branch.
workspace.git_pushrefuses the repository's default branch, and any branch namedmainormaster(default_branch_refused). A member has no other way to push:workspace.run_commandrefuses a command withgit pushanywhere in it, including throughmise,pnpmornode(git_push_via_run_command). - Skipping the repository's hooks. A git command with
--no-verify,git commit -n, or acore.hooksPathoverride is refused (git_hooks_skip_refused), and the file tools write nothing under.git/hooks. - A shell.
workspace.run_commandruns one binary with its arguments: no pipes, no redirects, nocd, no&&. The binary is one ofgit,node,npm,pnpmandmise, named, not given as a path (bin_not_allowlisted). - Files outside the clone. Every path the file tools read or write is inside the clone. A path that resolves outside it is refused.
What waits for you
A run's workspace waits for you only where its task says so. Without a gate, every write, commit and push goes ahead
as the task's rules allow, and only ever to a branch that is not the default one. A gate the task declares on a
workspace.* or memory.* tool waits like any other gated call: the OS stops the call, and runs exactly what you
approved. The gate can name one tool, all the workspace or all the memory tools (a row naming just workspace or
memory), or only some calls of a tool (match). A memory.* call is checked against the memory grants first, so
one they refuse fails without asking you. See Gates and grants in the
built-in tools reference.
A task that gates workspace.git_push, or all the workspace tools, gets no OS checkpoint. A checkpoint is the OS
saving a run's work for it: it commits the work and pushes it to the run's branch, so nothing is lost if the worker
running it goes. The OS makes one when the run waits at a gate, when a release hands the run to another worker, and
when the run stops because its model gave out or ran out of steps. While the push is gated, a checkpoint would send
the remote commits you have not approved, so the OS saves nothing on the task's behalf: the work stays only on the
worker that holds it, and the run's own push waits for you.
Gating the push has a cost. Work that is not pushed is lost if its worker goes before the run pushes it: a release, a crash, or a run that waits at a gate for longer than the worker lives. The run then carries on on another worker, from what was last pushed. When a release handed it on, or a gate it waited at is decided there, it is told which files were lost and has to make those changes again, and it cannot finish as a success until it has pushed again, which waits for you like any other push. After a crash it is told only that unpushed work is gone. So gate the push only when a push itself needs your approval; to approve what reaches the default branch, gate the merge instead (below).
A gate limited by match to calls the OS's own push never makes does not stop the checkpoint. For example, a gate on
workspace.git_push with "match": { "ref": "refs/heads/production" } holds a run's pushes to production, but the
checkpoint pushes the run's own branch with no ref, so it still goes ahead.
The decision that waits is the merge. Getting a branch into the default branch goes through your code host: a pull
request, or merge request, and the host's merge tool, which a task that merges should gate. On GitHub it has to: a
task that names github.merge_pull_request cannot be saved without a gate on it. See
Gates and tool scopes.
Planned
What a merge needs will be set on the task's own gate, for any host's merge tool: that the gate is required, that the run writes a summary before it waits, and that approving it ends the run. The OS will not know GitHub's merge tool by name.
Limits
| Limit | Value |
|---|---|
| One command | 10 minutes, then it is stopped with everything it started. |
| CPUs for one command | 4, also given as OS_CPU_BUDGET. See A command plans for four CPUs. |
| A command's output | At most 32,000 characters go back to the member. The exit code always does. |
| Setup and teardown | 8 steps each, each at most 16 argv entries including the binary. |
| Clone depth | The last 50 commits. |
| Reading without changing | 40 repeated reads (the same file, folder or search again, or an ad hoc command) with no write, edit or commit between them, and a per-run budget of 600 distinct files, folders and searches. The next one past either is refused (exploration_budget_exceeded), and the member is told to act on what it has read. |
| Search | 100 matches by default, 500 at most. |
Running mise run …, git status, git diff, git log or git commit is progress, not reading: it starts the
count of repeated reads again. Nothing resets the per-run budget, but a file, folder or search the run has already
read never counts against it twice.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
workspace_setup_failed |
A setup step exited non-zero | Run the same step in a fresh clone of the repository and fix it there, or change .os/workspace.yml |
workspace_manifest_invalid |
.os/workspace.yml is not in the form above |
One step per line, - [binary, argument], under setup: or teardown: |
workspace_service_unknown:<name> |
.os/workspace.yml asks for a service the OS does not provide |
Remove it from services:. The one service is mysql |
workspace_service_unavailable:mysql |
The deployment has no database server for workspaces, the server could not be reached, or the run's workspace cannot reach the network it is on | Read the reason after the code. The run is blocked, and resumes once the server is there |
workspace_setup_bin:<name> |
A setup step uses a binary that is not allowed | Run it through mise, or a package.json script |
tool_auth_denied:workspace.… |
The host refused the clone or the push | Check that the code host binding's account can write to the repository, and that its token has not expired |
workspace_repo_missing |
Neither the run's input nor a binding it reaches names a repository | Give the run a repo, or set the repository on the code host binding |
workspace_repo_no_clone_address |
The run names a short owner/name, and the nearest code host binding it reaches has no git.repoTemplate to expand it |
Add git.repoTemplate under Custom props on that binding on Tools, or give the run a full repo address |
| The clone asks for a password, or the push is refused | No binding the run reaches names the remote's host | Add git.host and git.username under Custom props on that code host's binding, which holds the token — see Where the repository lives |
default_branch_refused |
The run was working on the default branch | Give the task a branch template, or start the run with a branch input |
git_push_missing |
The run finished with work it never pushed | Read the run's last commit and push calls: a refused commit or push says why |
workspace_write_not_allowed or workspace_commit_not_allowed |
A path outside the task's rules | Change the task's Workspace, or the work |
A build or test run dies with EAGAIN, Resource temporarily unavailable or "can't spawn worker thread" |
A tool sized its workers from the host's cores, not the command's CPU budget | Give the tool its worker count from OS_CPU_BUDGET: see A command plans for four CPUs |
workspace_resource_exhausted:EAGAIN pids.current=<n> pids.max=<m> on Blockers |
A command could not start five times in a row: the run's own commands start more processes and threads than a machine allows | Size your suite's workers from OS_CPU_BUDGET, then retry the run. Once or twice in a run's history is a busy machine, and the run went back to the queue by itself |
workspace_append_only |
The run changed or removed a line in an add-only path | Add lines without changing existing ones, or have the task owner grant a deliberate rewriteAllow or writeAllow exception |