Guides

Once meets a project where it is. Start from native project metadata, cache the automation that already works, and add a typed graph only where more structure helps.

Start with an existing project#

Once can recognize supported native projects and make their build, test, and run capabilities available without requiring changes to their project files. Native project descriptions and lockfiles remain authoritative. Read the Typed Graph guide to discover and preview supported projects without adding Once configuration.

Cache existing automation#

Use Scripted automation to add explicit inputs, outputs, environment, and cache policy to commands or scripts that already work. The existing script remains the source of truth, while Once caches operations such as packaging, generation, and checks.

Add structure when it helps#

Use the Typed Graph guide for named targets, typed dependencies, build and run capabilities, and ecosystem integrations. You can keep native discovery and cacheable scripts beside typed targets while the graph grows. Add a package manifest when you want to keep a choice in the repository. Introduce a project Starlark module only when the built-in target kinds cannot express reusable behavior your project needs.

  • Testing and scheduling covers normalized test results, selection, batching, retries, and custom test runners.
  • Linting covers cacheable static analysis, shared finding results, failure policy, built-in analyzers, and custom analyzer target kinds.
  • Ecosystems helps choose between typed targets and scripted automation.

Run work where it makes sense#

Once runs actions locally first. As a project grows, control how much work runs at once, then share cached results or move suitable work to remote execution.

  • Control local execution: use Memory Limits to keep concurrent local actions within a scheduling budget on constrained or shared machines.
  • Share or move execution: add shared cache entries, isolated sandboxes, or hosted execution after the local workflow is working well.

Bring Once into your workflow#

The command line works on its own. Use the following integrations when another application or a coding agent needs to work with the same cache, graph, and execution model.