{"id":47801393,"url":"https://github.com/ota-run/ota","last_synced_at":"2026-04-26T04:03:52.593Z","repository":{"id":346038101,"uuid":"1188051251","full_name":"ota-run/ota","owner":"ota-run","description":"Ota is the open repo-readiness layer for every stack, every team, and every AI agent.","archived":false,"fork":false,"pushed_at":"2026-04-03T15:36:49.000Z","size":2894,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T18:51:30.920Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ota.run","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ota-run.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-21T14:53:55.000Z","updated_at":"2026-04-03T17:49:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"fd3c9871-aace-40ef-8e03-92498c599543","html_url":"https://github.com/ota-run/ota","commit_stats":null,"previous_names":["ota-run/ota"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/ota-run/ota","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ota-run%2Fota","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ota-run%2Fota/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ota-run%2Fota/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ota-run%2Fota/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ota-run","download_url":"https://codeload.github.com/ota-run/ota/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ota-run%2Fota/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31516839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T17:03:05.352Z","updated_at":"2026-04-26T04:03:52.585Z","avatar_url":"https://github.com/ota-run.png","language":"Rust","funding_links":[],"categories":["Development"],"sub_categories":["Chat"],"readme":"\u003c!--\n                █████\n               ░░███\n       ██████  ███████    ██████\n      ███░░███░░░███░    ░░░░░███\n     ░███ ░███  ░███      ███████\n     ░███ ░███  ░███ ███ ███░░███\n     ░░██████   ░░█████ ░░████████\n      ░░░░░░     ░░░░░   ░░░░░░░░\n\n   Copyright (C) 2026 — 2026, Ota. All Rights Reserved.\n\n   DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.\n\n   Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.\n   You may not use this file except in compliance with that License.\n   Unless required by applicable law or agreed to in writing, software distributed under the\n   License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,\n   either express or implied. See the License for the specific language governing permissions\n   and limitations under the License.\n\n   If you need additional information or have any questions, please email: os@ota.run\n--\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/ota-icon.svg\" alt=\"ota logo\" width=\"110\" height=\"110\" /\u003e\n  \u003ch1\u003eota\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eOpen repo-readiness infrastructure for humans, CI, and AI agents.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\u003cstrong\u003eDoctor first. Contract second.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003e\n    Give every repo one explicit contract for diagnosis, setup, execution, and safe automation\n    instead of guessing from README drift.\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/ota-run/ota/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/ota-run/ota?style=flat-square\" alt=\"Latest release\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ota-run/ota/actions/workflows/release-gate.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ota-run/ota/release-gate.yml?branch=main\u0026style=flat-square\u0026label=release%20gate\" alt=\"Release gate status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ota-run/ota/actions/workflows/docs-quality.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ota-run/ota/docs-quality.yml?branch=main\u0026style=flat-square\u0026label=docs\" alt=\"Docs quality status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/ota-run/ota?style=flat-square\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003c!--     \u003ca href=\"https://github.com/ota-run/ota/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/ota-run/ota?style=flat-square\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e --\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\u003cstrong\u003eBuilt for\u003c/strong\u003e humans, CI, AI agents, containers, and multi-repo workspaces.\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://ota.run/docs/getting-started\"\u003eGet Started\u003c/a\u003e ·\n    \u003ca href=\"https://ota.run/docs\"\u003eDocs\u003c/a\u003e ·\n    \u003ca href=\"https://ota.run/docs/reference\"\u003eReference\u003c/a\u003e ·\n    \u003ca href=\"https://ota.run\"\u003eWebsite\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://ota.run/docs/install\"\u003eInstall\u003c/a\u003e ·\n    \u003ca href=\"https://ota.run/docs/quickstart\"\u003eQuickstart\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/ota-run/examples\"\u003eExamples\u003c/a\u003e ·\n    \u003ca href=\"https://ota.run/docs/reference/governance\"\u003eGovernance\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/ota-run/ota/releases\"\u003eReleases\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://discord.gg/45mBMzSkKC\"\u003eDiscord\u003c/a\u003e ·\n    \u003ca href=\"https://x.com/otaready\"\u003eX (Twitter)\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## One explicit contract for repo readiness\n\nMost repos fail the same way:\n\n- setup is split across README prose, shell scripts, manifests, and tribal knowledge\n- contributors guess which runtimes, tools, versions, and task order the repo actually needs\n- local, CI, and container workflows drift apart\n- AI agents see partial guidance and make unsafe assumptions\n- diagnosis starts after the repo already feels broken\n\nota is not another task runner or package manager. It gives every repo one explicit contract for\nwhat it needs, how it is diagnosed, how it is prepared, and how tasks run, so humans and AI agents\ncan answer why a repo is or is not runnable without guesswork.\n\nota fixes that by making readiness explicit and machine-readable:\n\n- `ota doctor` shows what is missing and the next safe step\n- `ota validate` keeps the contract honest before humans, CI, or agents rely on it\n- `ota init` writes a starter contract when the repo needs one\n- `ota up` prepares the repo from the contract instead of from guesswork\n- `ota run` executes declared work through the same contract every time\n- `ota detect` turns repo signals into a contract you can review when you are authoring or refining the file\n\nThe result is a repo that is easier to trust, easier to onboard, and easier to operate across\nhumans, CI, containers, and AI agents.\n\n## Installation\n\nInstall the latest release binary:\n\n```bash\ncurl -fsSL https://dist.ota.run/install.sh | sh\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://dist.ota.run/install.ps1 | iex\n```\n\nWindows Git Bash, MSYS, MinGW, or Cygwin:\n\n```bash\ncurl -fsSL https://dist.ota.run/install.sh | sh\n```\n\nPin a release:\n\n```bash\nOTA_VERSION=vX.Y.Z curl -fsSL https://dist.ota.run/install.sh | sh\n```\n\nWindows PowerShell:\n\n```powershell\n$env:OTA_VERSION = \"vX.Y.Z\"\nirm https://dist.ota.run/install.ps1 | iex\n```\n\nUpdate an existing install:\n\n```bash\nota upgrade\n```\n\nInstall from a local checkout:\n\n```bash\n./scripts/install.sh --from-source\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\install.ps1 -FromSource\n```\n\nSee [Install](https://ota.run/docs/install) for the public install path and\n[docs/installation.md](docs/installation.md) for repo-local mirror/CDN and source fallback details.\n\n## Quickstart\n\nChoose the path that matches the repo.\n\n### Existing repo with `ota.yaml`\n\nStart with the read path:\n\n```bash\nota doctor\nota explain\nota up\nota run \u003ctask\u003e\nota receipt\n```\n\nThis path tells you what is wrong, turns the findings into an ordered plan, prepares the repo,\ngives you one declared task path without guessing, and captures the resulting repo state as a\nreviewable artifact.\n\nIf the repo is meant to run inside a container, use:\n\n```bash\nota doctor --mode container\n```\n\nIf you are not sure which task to run after `ota up`, use:\n\n```bash\nota tasks --use\n```\n\nIf you want repo-local agent guidance from the same contract after the core loop is working, use:\n\n```bash\nota agents\n```\n\n### Repo without `ota.yaml`\n\nUse the authoring path first:\n\n```bash\nota doctor\nota explain\nota detect --dry-run .\nota init --dry-run\n```\n\nThen choose one explicit write path:\n\n```bash\nota init\n# or:\nota detect --write .\n```\n\nIf you want an explicit conventional starter instead of detector-led init, use a pack:\n\n```bash\nota init --packs\n# or:\nota init --pack node\n# or:\nota init --pack node --package-manager npm --dry-run\n# or:\nota init --pack python --dry-run\n# or:\nota init --pack python --test-runner unittest --dry-run\n# or:\nota init --pack go --dry-run\n# or:\nota init --pack rust --dry-run\n# or:\nota init --pack dotnet --dry-run\n# or:\nota init --pack php-composer --dry-run\n# or:\nota init --pack java-maven --dry-run\n# or:\nota init --pack java-gradle --dry-run\n```\n\nThe Java packs prefer `./mvnw` or `./gradlew` when the repo already ships those wrappers. When no\nwrapper is present, they seed the global Maven or Gradle prerequisite explicitly.\nThe Node pack accepts `--package-manager npm|pnpm|yarn|bun`, and the Python pack accepts\n`--test-runner pytest|unittest`.\nThe `php-composer` pack stays on the explicit Composer boundary and does not pretend to infer\nframework-specific entrypoints or whether the repo uses phpunit, pest, artisan, or another test\nwrapper unless the repo already declares `scripts.test` in `composer.json`.\nIf you choose the wrong explicit pack, ota can surface an advisory note and JSON `pack_advisory`\nfield, but it keeps the selected pack authoritative and does not auto-switch starters.\n\n### Existing repo with `ota.yaml`, but contract drift is suspected\n\nReview the delta before writing:\n\n```bash\nota detect --merge --dry-run .\nota detect --rewrite --dry-run .\n```\n\n### Policy boundary review\n\nUse the conservative policy scaffold first when a team needs a starter org policy pack:\n\n```bash\nota policy init --dry-run\nota policy init\nota policy init --preset required-sections --dry-run\nota policy init --preset provisioning --dry-run\nota policy init --preset agent --dry-run\n```\n\n### One repo rollout story\n\nFor one repo, the repeatable local path is:\n\n```bash\nota doctor\nota up\nota run ci\nota receipt\n```\n\nFor CI, keep the same contract boundary and archive the read-only receipt:\n\n```bash\nota validate\nota doctor --json\nota receipt --json --archive\n```\n\nThat keeps the local path and the CI artifact story on the same surface instead of inventing a\nsecond readiness workflow.\n\nWhen you want a repo-owned baseline for later compare gates:\n\n```bash\nota receipt --json --archive --promote-baseline\nota receipt --json --baseline promoted\n```\n\nUse `promoted` when a team wants an explicit accepted repo state, and use `latest` when the newest\narchived receipt is enough for a local drift check.\n\nUse policy review when the contract and approved policy need to be reconciled:\n\n```bash\nota policy review\n```\n\n### Agent guidance from the same contract\n\nIf you want repo-local agent guidance from the same contract:\n\n```bash\nota agents\nota agents --write\n```\n\n### Workspace bootstrap\n\nIf you are setting up multiple repos together:\n\n```bash\nota workspace doctor .\nota workspace up\nota workspace tasks .\nota workspace validate .\n```\n\nIf the contract declares agent guidance, `ota doctor --json` and `ota explain --json` surface the\nsame safe-task, verification, and writable-path hints that humans can review in `ota.yaml`.\n\nExample contracts:\n\n- [basic-node](examples/basic-node/ota.yaml) - Node / TypeScript starter\n- [basic-dotnet](examples/basic-dotnet/ota.yaml) - C# / .NET starter\n- [basic-java](examples/basic-java/ota.yaml) - Maven starter\n- [basic-rust](examples/basic-rust/ota.yaml) - Cargo starter\n- [basic-script](examples/basic-script/ota.yaml) - Script-only starter\n- [basic-services](examples/basic-services/ota.yaml) - Service-backed repo starter\n- [full-contract](examples/full-contract/ota.yaml) - Full contract surface\n- [workspace-acquire](examples/workspace-acquire/ota.workspace.yaml) - Workspace acquisition flow\n- [ota-run/examples](https://github.com/ota-run/examples) - advanced, production-adjacent examples and templates\n\n## Why ota exists\n\nRepo setup truth is usually fragmented across:\n\n- language manifests\n- runtime version files\n- task scripts\n- container config\n- CI config\n- README setup notes\n- tribal knowledge\n\nota consolidates that into one canonical contract:\n\n```yaml\nota.yaml\n```\n\nThe goal is not hidden automation. The goal is deterministic, inspectable repo readiness.\n\n## Open Source and Governance\n\nota is maintainer-led open infrastructure for repo readiness. The core CLI, contracts, JSON output,\nand docs are public under Apache 2.0, while roadmap stewardship and future enterprise offerings stay\noperated by Ota.\n\nota is open source, but it is not positioned as a community-governed codebase.\n\n- governance is maintainer-led by Ota so the contract, diagnosis model, and machine-readable surfaces stay coherent\n- issues, bug reports, docs feedback, and real-repo examples are welcome\n- external code contributions are not currently accepted\n\nSee [docs/policy/governance.md](docs/policy/governance.md) for the governance model and\n[CONTRIBUTING.md](CONTRIBUTING.md) for the current contribution policy.\n\n## What ota does today\n\nThe public command surface is in [docs/spec/command-reference.md](docs/spec/command-reference.md).\nStart with `ota doctor`, then `ota validate`, `ota up`, and `ota run \u003ctask\u003e`.\n\nNear-term policy and provisioning direction:\n\n- [Environment variables](docs/spec/env-resolution-and-policy.md)\n- [Policy-backed provisioning sources](docs/spec/policy-backed-provisioning.md)\n- [Policy inspection](docs/spec/command-reference.md#ota-policy)\n- [Uninstall](docs/spec/command-reference.md#ota-uninstall)\n\nGlobal flag:\n\n```bash\nota --debug \u003ccommand\u003e\nota --plain \u003ccommand\u003e\n```\n\n`--debug` emits command-phase tracing to stderr without changing normal stdout.\n`--plain` emits ASCII-first output without emoji, icons, or ANSI color.\n\nUse `--debug` when you want command traces for `ota up`, `ota run \u003ctask\u003e`, `ota workspace up`,\n`ota workspace refresh`, `ota workspace diff`, `ota workspace status`, `ota workspace run \u003ctask\u003e`, `ota doctor`, `ota detect`, `ota diff`, and\n`ota explain`.\nCommands like `ota validate`, `ota tasks`, `ota workspace validate`, `ota workspace tasks`, and\n`ota workspace list` should usually stay quiet unless you are actively debugging.\n\nCurrent behavior:\n\n- `ota validate` parses and semantically validates `ota.yaml`\n- `ota tasks` lists validated tasks and their execution form\n- `ota run \u003ctask\u003e` resolves dependencies, executes the requested task deterministically, and honors declared `after_success`, `after_failure`, and `after_always` hooks as part of the task's final result\n- `ota diff` compares two contracts semantically and reports added, missing, and changed fields in deterministic order\n- `ota explain` turns readiness findings into an ordered remediation plan\n- `ota doctor` reports readiness findings for env, runtimes, tools, services, and checks with severity, explanation, and next action, still gives a useful repo/host diagnosis when no `ota.yaml` exists yet, leads with the highest-priority blocker first, and supports `ota doctor --mode container` for container-targeted readiness\n- `ota init` creates a starter contract for repos that do not yet have `ota.yaml`, both detector-led starters plus starter packs can seed short task `description` fields so users can see and refine that authoring pattern immediately, detector-led starters can also carry existing repo-root dotenv sources such as `.env.local` and `.env` into `env.sources`, explicit `--pack` mode can emit an advisory note when strong repo signals disagree without auto-switching packs while still staying on the conventional starter boundary, the Node/Python starter packs expose explicit knobs for package-manager and test-runner selection, and the built-in pack catalog now spans `node`, `python`, `go`, `rust`, `dotnet`, `php-composer`, `java-maven`, and `java-gradle`\n- `ota agents` exports or syncs a repo-local `AGENTS.md` from the contract’s agent guidance, preserves existing user-authored content by appending an ota-managed block, skips the write when the generated content is already present, and shows a `Managed block:` label in text output so the ota-owned section is explicit, including the `ota run ...` command form for each listed task\n- `ota check` runs configured checks without runtime, tool, env, or task execution\n- `ota up` validates, runs blocking preconditions, runs `setup` early when preconditions fail and the repo declares it, starts required services in declared dependency order, uses required service healthchecks as readiness gates, runs `setup` if present, and re-checks readiness\n- `ota detect` (default) infers a candidate contract and prints provenance/confidence without writing\n- `ota completion --setup` auto-installs shell completion for the current shell, `ota completion --remove` removes the managed hook and zsh support file, `ota completion check` verifies the managed hook, current binary path, and any managed zsh completion file, `ota completion zsh` now prints both the `_ota` completion file and the `.zshrc` loader for self-contained manual setup, and `ota completion \u003cshell\u003e --script` prints the raw generated registration script; once sourced, `ota \u003cTAB\u003e` completes commands first and keeps global `--flags` after them in zsh, `ota run \u003cTAB\u003e` completes task names only when one shared invocation can satisfy the selected repo/member target set and now includes task descriptions when the contract declares them, `ota run \u003ctask\u003e \u003cTAB\u003e` completes shared task input flags plus constrained values, `ota env --task \u003cTAB\u003e` completes task names, `ota extensions --run/--publish \u003cTAB\u003e` completes declared extension names, `ota receipt --baseline \u003cTAB\u003e` completes `latest`, `promoted`, and archived receipt files from the active repo, `--member \u003cTAB\u003e` completes monorepo member names, and workspace completion suggests workspace-wide task names only when one shared invocation can satisfy the available repos, shared workspace task inputs, and declared repo names\n- `ota detect --write` writes a contract conservatively from `high` confidence fields only\n- `ota detect --merge --dry-run` compares detected repo signals against an existing `ota.yaml` without writing and surfaces stale contract fields that no longer match repo reality\n- `ota detect --merge` applies only additive `high` confidence missing fields to an existing `ota.yaml`\n- there is no standalone `ota drift` command yet; drift review stays on `ota detect --merge --dry-run` and trust/readiness drift stays on `ota doctor`\n- `ota workspace validate` validates `ota.workspace.yaml` separately from repo contracts\n- `ota workspace tasks` lists workspace repo tasks in dependency order without executing them, including declared post-outcome hook relationships when repo contracts define them\n- `ota workspace run \u003ctask\u003e` executes one task across workspace repos in dependency order with deterministic reporting\n- `ota workspace explain` turns workspace readiness findings into ordered remediation steps\n- `ota workspace check` runs configured checks across workspace repos with deterministic reporting\n- `ota workspace doctor` aggregates repo readiness across a workspace contract without merging repo and workspace truth, including repos that are not acquired yet\n- `ota workspace up` can acquire missing repos from git sources and then orchestrates repo-level `up` across the workspace contract without inventing a second bootstrap model\n- `ota workspace refresh` re-syncs repos that already exist locally without cloning missing ones\n- `ota workspace refresh --dry-run` previews the refresh commands without changing repo state\n- `ota workspace refresh --force` hard-resets refreshed repos to the declared source or `--ref` override\n- `ota workspace refresh --prune` drops stale remote-tracking refs during refresh\n- `ota workspace refresh --ref \u003cbranch|tag|sha\u003e` overrides the source ref used for refresh\n- `ota workspace diff` compares local workspace repo state against the declared source without mutating anything\n- `ota workspace status` combines readiness and drift into one read-only workspace summary\n- `ota workspace receipt` captures the same workspace state as a read-only receipt artifact for CI and archiving\n- editor and CI consumers should prefer `--json` surfaces such as `ota doctor --json`, `ota workspace doctor --json`, `ota workspace list --json`, and `ota up --json` instead of scraping text output\n\n### Shell completion quickstart\n\nUse the managed shell hook first:\n\n```bash\nota completion --setup\nota completion --remove\nota completion check\n```\n\nIf auto-detection is not available or you want one explicit shell:\n\n```bash\nota completion zsh --setup\nota completion zsh --remove\nota completion bash --setup\nota completion fish --setup\nota completion powershell --setup\nota completion elvish --setup\n```\n\nOnce the shell has sourced that hook, ota keeps completion contract-aware instead of static: repo commands complete member names, task names, and task inputs from the active contract, while workspace commands complete declared repo names and only suggest workspace task names that remain runnable across the selected repo set.\nReceipt compare flows also complete `latest`, `promoted`, and archived receipt JSON files from `.ota/receipts` so baseline selection stays discoverable at the shell.\n\n## Execution Modes and Provisioning\n\nota supports three execution backends for task-oriented commands:\n\n- `native` runs tasks on the host machine.\n- `container` runs tasks in an OCI-compatible container using the image defined by the repo contract.\n- `remote` runs tasks on a separate machine or workspace through a remote provider.\n\n### Why the three modes exist\n\n- `native` is the simplest path when the host already has the right toolchain and you want to debug against the real machine.\n- `container` is the reproducible path when you want a fixed toolchain, deterministic setup, and CI-like behavior.\n- `remote` is the off-host path when execution needs to happen somewhere else entirely, such as a dev box, cluster, or managed workspace.\n\n### What ota does today\n\n- `ota run` and `ota up` can execute through the configured backend path.\n- `ota up` can run the `setup` task through the same backend selection as `ota run`.\n- policy-backed provisioning adapters follow the same backend selection, so container-backed `ota up` provisions inside the container instead of on the host and stops before host provisioning when the selected container engine is unavailable.\n- `ota doctor` checks the prerequisites for the preferred backend and reports missing tools or suspicious remote target shape early.\n- `ota clean` can remove persistent container state for container-backed repos.\n- `ota clean --stale` can remove exited ota-managed containers across repos without requiring an `ota.yaml`, and it surfaces container-engine query failures instead of silently treating them as empty.\n\n### What ota does not do today\n\n- ota does not automatically install every missing host tool or language runtime.\n- ota does not turn a laptop into a fully managed workstation.\n- ota does not invent remote provisioning or remote workspace selection beyond the configured provider path.\n\n### Container backend\n\nContainer execution is useful when you want ota to run repo tasks in a known environment instead of relying on whatever happens to be installed locally.\n\nBenefits:\n\n- removes drift in Java, Maven, shell, and other repo tool versions\n- makes local execution closer to CI\n- gives agents a stable execution surface\n- supports persistent or ephemeral lifecycle behavior where the contract and command support it\n\nRequirements:\n\n- at least one supported container engine CLI must be installed and running\n- the contract must declare `execution.backends.container.image`\n- the image must be pullable and runnable by the selected engine\n\nIn this repository, the container image is:\n\n```yaml\nexecution:\n  preferred: container\n  lifecycle: persistent\n  supported:\n    - native\n    - container\n  backends:\n    container:\n      image: rust:1.85\n```\n\n### Native backend\n\nNative execution is useful when:\n\n- you want to debug against the exact host environment\n- the repo already has the required toolchain installed\n- you want the fewest moving parts and no container boundary\n\nNative execution does not require a container engine, but it does require the host tools that the task depends on.\n\n### Remote backend\n\nRemote execution is useful when the work should happen outside the local machine:\n\n- `ssh` for a team dev box or dedicated host\n- `kubectl` for execution inside a Kubernetes-backed environment\n- `tsh` for Teleport-managed infrastructure\n- `daytona` for a managed remote development workspace\n\nRemote execution is only available when the contract declares the provider and target fields required by the backend.\n\n### Which commands use the backend\n\nThese commands execute repo tasks and therefore respect the backend selection:\n\n- `ota run \u003ctask\u003e`\n- `ota up`\n\nThese commands do not run repo tasks and therefore do not use the execution backend:\n\n- `ota validate`\n- `ota doctor`\n- `ota detect`\n- `ota init`\n- `ota tasks`\n\n### Override syntax\n\nUse `--mode` to force one invocation to use a specific execution mode:\n\n```bash\nota run test --mode native\nota run test --mode container\nota up --mode native\nota up --mode container\n```\n\nUse `--lifecycle` when you need to override container reuse for one invocation:\n\n```bash\nota run test --mode container --lifecycle persistent\nota run test --mode container --ephemeral\n```\n\nUse `ota tasks --use` to see the exact runnable task commands for the current contract:\n\n```bash\nota tasks --use\n```\n\n## Hosted validation and service provisioning\n\nIn CI, the runner still owns the job. ota owns the repo contract and can provision declared\nservices such as Postgres through `ota up`, so the workflow stays thin and the service intent lives\nwith the repo instead of being duplicated in pipeline YAML.\n\nIf the runner is GitHub Actions and you want the official wrapper for step summaries, annotations,\npull-request comments, and receipt artifacts, use\n[ota-run/action](https://github.com/ota-run/action) and see\n[docs/spec/github-action-workflow.md](docs/spec/github-action-workflow.md).\nIf you need a repo-local summary renderer outside that wrapper, `ota annotations --format markdown`\nemits a compact step-summary or PR-comment block from the same canonical doctor JSON, and\n`ota annotations --mode receipt-diff --format markdown` does the same for\n`ota receipt --json --baseline ...` compare output.\n\nThat is different from host provisioning. ota can provision declared services and run tasks in a\ncontainer or remote backend, but it does not replace the OS package manager, language installer,\nor workstation bootstrap process.\n\n```yaml\nname: ci\n\non:\n  push:\n  pull_request:\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v4\n      - name: Install ota\n        run: curl -fsSL https://dist.ota.run/install.sh | sh\n      - name: Validate contract\n        run: ota validate\n      - name: Prepare repo\n        run: ota up\n      - name: Run lint\n        run: ota run lint\n      - name: Run tests\n        run: ota run test\n```\n\n## Detect trust model\n\nota treats detection as trust-sensitive.\n\n- `ota detect --dry-run` is the review path\n- `ota detect --merge --dry-run` is the review path for existing contracts\n- every inferred field includes provenance\n- every inferred field includes confidence\n- write mode uses only `high` confidence fields\n- write mode validates before writing\n- write mode refuses to overwrite an existing `ota.yaml`\n- merge write is additive only in the current implementation\n- lower-confidence or conflicting changes stay review-only\n\nThis is intentional. The project prefers conservative correctness over aggressive generation.\n\n## Open standard intent\n\nota is being built as open infrastructure, not as a vendor-specific workflow.\n\nThe long-term aim is:\n\n- one canonical readiness contract per repo\n- one canonical bootstrap contract per workspace\n- deterministic behavior without LLM dependency in the core path\n- human and agent symmetry\n- interoperability with the existing tool ecosystem\n\n## Current status\n\nV1 is complete and the release gate is green.\n\nThe current shipped foundation includes:\n\n- contract validation\n- task listing\n- deterministic task execution\n- readiness diagnosis\n- onboarding via `up`\n- detection with dry-run, conservative first write, and conservative additive merge\n- separate workspace contract validation, diagnosis, and bootstrap\n- generic git-based workspace acquisition for missing repos\n- monorepo root/member loading for repo commands via `--member`\n- fixture-backed coverage for Java detection, container-heavy, container-only, conflict-heavy Node, mixed Node/Python, legacy Python, and ugly/polyglot mixed-reality repo shapes\n\nCurrent planning state:\n\n- V1 archive: [docs/planning/v1/phases.md](docs/planning/v1/phases.md)\n- V1 release gate: [docs/planning/v1/release-gate.md](docs/planning/v1/release-gate.md)\n- V2 archive: [docs/planning/v2/plan.md](docs/planning/v2/plan.md)\n- V2.1 archive: [docs/planning/v2.1/plan.md](docs/planning/v2.1/plan.md)\n- V6 archive: [docs/planning/v6/plan.md](docs/planning/v6/plan.md)\n- Active version: [docs/planning/v7/plan.md](docs/planning/v7/plan.md)\n- Archived local UX hardening slice: [docs/planning/v5-ux-hardening.md](docs/planning/v5-ux-hardening.md)\n- V5 mutation controls and caching: [docs/spec/mutation-controls-and-caching.md](docs/spec/mutation-controls-and-caching.md)\n\n## Enterprise Direction\n\nEnterprise work is planned as a layer around the open core, not as a different contract truth.\n\n- the open core remains the public CLI, repo/workspace schemas, JSON output, and documentation\n- enterprise value should come from hosted policy, audit, fleet coordination, private adapters,\n  onboarding, and support\n- the public contract should stay usable on its own and should not become a thin wrapper around a paid control plane\n\nSee [docs/policy/support-and-enterprise.md](docs/policy/support-and-enterprise.md) for the current\nenterprise boundary and likely future commercial surfaces.\n\n## Contribution policy\n\nota is maintainer-led. External code contributions are not currently accepted.\n\nUse the GitHub issue templates for bug reports, feature requests, docs feedback, and real-repo\nreproductions.\n\nRead:\n\n- [CONTRIBUTING.md](CONTRIBUTING.md) for the current contribution workflow\n- [docs/policy/governance.md](docs/policy/governance.md) for project governance\n- [docs/policy/commercial-policy.md](docs/policy/commercial-policy.md) for the open-core and commercial boundary\n- [docs/policy/support-and-enterprise.md](docs/policy/support-and-enterprise.md) for support and enterprise direction\n\nRepo-level support entry point: [SUPPORT.md](SUPPORT.md)\n\n## Documentation\n\n### Start here\n\n- [One-team rollout](docs/adoption/one-team-rollout.md)\n- [Worked example: existing repo](docs/adoption/worked-example-existing-repo.md)\n- [Command reference](docs/spec/command-reference.md)\n- [GitHub Action workflow](docs/spec/github-action-workflow.md)\n- [Contract reference](docs/spec/contract-reference.md)\n- [Workspace reference](docs/spec/workspace-reference.md)\n- [Shell semantics](docs/spec/shell-semantics.md)\n- [Service behavior](docs/spec/service-behavior.md)\n- [JSON output reference](docs/spec/json-output-reference.md)\n- [Audit and provenance](docs/spec/audit-and-provenance.md)\n- [Policy packs](docs/spec/policy-packs.md)\n- [Exit codes](docs/spec/exit-codes.md)\n- [Docs clarity spec](docs/spec/docs-clarity-spec.md)\n\n### Core concepts\n\n- [Philosophy](docs/philosophy.md)\n- [Governance](docs/policy/governance.md)\n- [Compatibility policy](docs/spec/compatibility-policy.md)\n- [Support policy](docs/spec/support-policy.md)\n\n### Design and engineering\n\n- [Security posture](docs/design/security-posture.md)\n- [Performance budget](docs/design/performance-budget.md)\n- [Doctor quality bar](docs/design/doctor-quality-bar.md)\n- [UX review loop](docs/design/ux-review-loop.md)\n- [Adoption readiness gate](docs/design/adoption-readiness-gate.md)\n- [Detect write gate](docs/design/detect-write-gate.md)\n\n### Planning and roadmap\n\n- [V1 phases](docs/planning/v1/phases.md)\n- [V1 release gate](docs/planning/v1/release-gate.md)\n- [V2 plan](docs/planning/v2/plan.md)\n- [V2.1 plan](docs/planning/v2.1/plan.md)\n- [V3 plan](docs/planning/v3/plan.md)\n- [V4 plan](docs/planning/v4/plan.md)\n- [V5 plan](docs/planning/v5/plan.md)\n- [V6 plan](docs/planning/v6/plan.md)\n- [V7 plan](docs/planning/v7/plan.md)\n- [V8 plan](docs/planning/v8/plan.md)\n- [V9 plan](docs/planning/v9/plan.md)\n- [V5 UX hardening completion slice](docs/planning/v5-ux-hardening.md)\n- [Hosted validation workflow](docs/spec/hosted-validation-workflow.md)\n- [Fixture repo plan](docs/planning/fixture-repo-plan.md)\n- [Roadmap](ROADMAP.md)\n\n### Contributing\n\n- [Contributing guide](CONTRIBUTING.md)\n\n## Examples\n\nChoose by goal:\n\n- first repo contract: [Basic Node](examples/basic-node/ota.yaml), [Basic Python](examples/basic-python/ota.yaml), [Basic Rust](examples/basic-rust/ota.yaml)\n- existing app with services: [Basic Services](examples/basic-services/ota.yaml), [Mixed Node + Python](examples/mixed-node-python/ota.yaml)\n- multi-repo bootstrap: [Basic Workspace](examples/workspace-basic/ota.workspace.yaml), [Acquisition Workspace](examples/workspace-acquire/ota.workspace.yaml)\n- realistic reference shape: [Fullstack Node + Go](examples/fullstack-node-go/ota.yaml), [Full contract example](examples/full-contract/ota.yaml), [ota-run/examples](https://github.com/ota-run/examples)\n\n### Minimal contracts\n\n- [Basic Node](examples/basic-node/ota.yaml) - Node / TypeScript starter\n- [Basic .NET](examples/basic-dotnet/ota.yaml) - C# / .NET starter\n- [Basic Java](examples/basic-java/ota.yaml) - Maven starter\n- [Basic Python](examples/basic-python/ota.yaml) - Python starter\n- [Basic Go](examples/basic-go/ota.yaml) - Go module starter\n- [Basic Rust](examples/basic-rust/ota.yaml) - Cargo starter\n- [Basic Script](examples/basic-script/ota.yaml) - Script-only starter\n\n### Mixed and realistic repos\n\n- [Mixed Node + Python](examples/mixed-node-python/ota.yaml) - Polyglot app example\n- [Fullstack Node + Go](examples/fullstack-node-go/ota.yaml) - Frontend/backend split example\n- [Full contract example](examples/full-contract/ota.yaml) - Exhaustive contract reference\n- [ota-run/examples](https://github.com/ota-run/examples) - advanced, production-adjacent examples and templates\n\n### Workspace\n\n- [Basic Workspace](examples/workspace-basic/ota.workspace.yaml) - Multi-repo starter; use `ota workspace doctor` to review readiness and `ota workspace up` to prepare the stack.\n- [Acquisition Workspace](examples/workspace-acquire/ota.workspace.yaml) - Workspace acquisition flow; use `ota workspace init` first, then `ota workspace up` to acquire and prepare repos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fota-run%2Fota","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fota-run%2Fota","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fota-run%2Fota/lists"}