Smart Workspaces

Documentation / Run jobs

Smart Workspaces

Opt-in, for pnpm projects: keep an installed dependency tree on the machine’s own disk and hand it to each job after checkout, instead of installing it again.

Opt in per pool

Smart Workspaces is opt-in. It supports pnpm projects on Linux. It has been measured on a small repository only, and only for the dependency step. We do not claim a faster complete job.

A pool without this profile behaves as described in the other guides. Nothing here applies until the profile is enabled for a pool and the action below is added to a workflow. The profile is enabled for a pool by whoever operates the machine.

What it covers

Smart Workspaces handles one thing: the installed node_modules tree of a pnpm project. That is the only dependency tree it prepares, checks and hands to a job.

In your jobWith Smart Workspaces
pnpm installReplaced by the prepared node_modules tree on an exact match. Otherwise a normal locked install runs.
npm, Yarn and Bun installsNot handled. The action is for pnpm projects only.
pip, uv, Cargo, Go, Gradle and Maven dependenciesNot handled.
Build outputs, such as a Cargo target directory or a Turborepo or Nx cacheNot handled.
Compiler caches, such as ccache and sccacheNot handled.
Docker image layersNot handled. This profile does not run Docker jobs.

The action has no input that names a directory to keep. It cannot be pointed at another tool’s cache.

For everything in the “not handled” rows, keep the cache steps your workflow already has, such as actions/cache or the cache option of a setup action. Those steps are GitHub’s, not ours: they keep their data with GitHub, not on the machine.

What it does

On a Smart Workspaces pool, a job’s working directory is a private workspace on the machine’s own disk. A dependency tree that was installed ahead of time, reviewed and approved is kept on that disk too, read-only.

After checkout, the prepare action reads the files actually checked out and computes a key from the lockfile, package inputs, patches, pnpm configuration, and the Node version and platform. On an exact match it moves the approved node_modules into the job’s workspace without downloading or copying packages. On any difference it runs a normal locked pnpm install.

Your build and tests always run. A prepared tree never stands in for a test result.

Add the prepare action

Run the action after checkout and tool setup, in place of your dependency install step. Pin both actions to full commit SHAs you have reviewed:

- uses: actions/checkout@FULL_REVIEWED_COMMIT_SHA
  # Keep your existing checkout inputs.
- uses: OWNER/enginebox/packages/enginebox-actions@FULL_REVIEWED_COMMIT_SHA
  with:
    install-scripts: deny
    path: '.'
    require-hit: 'false'
    offline: 'false'
- run: pnpm test

OWNER and the SHAs are placeholders. The dashboard’s Prepared runner profile view previews this fragment for a pool; it does not edit your workflow or open a pull request.

Remove the install step the action replaces. A later npm ci deletes the restored tree. Review pnpm and setup-action cache restores that are now redundant. Caches for other artifacts are unaffected.

Inputs and outputs

InputDefaultMeaning
path.Checkout path relative to GITHUB_WORKSPACE.
install-scriptsrunrun or deny. Must match the pool’s policy. A prepared tree is used only with deny; run always does a normal locked install.
require-hitfalsetrue fails the step when the exact prepared tree is unavailable, instead of installing.
offlinefalsetrue forbids dependency downloads when the action falls back to an install.

The action sets two outputs: mode, either installed-tree or install, and key, the dependency identity it computed. The step summary reports which path was taken, the preparation time and the number of packages downloaded. These are diagnostics, not check results.

Limits

  • pnpm only. The prepared path is qualified for pnpm 12.15.0. Nested workspace selections are refused. What it covers lists the tools it does not handle.
  • No install scripts in the prepared tree. A project that needs lifecycle scripts uses install-scripts: run and gets a normal locked install.
  • No sudo installs and no Docker jobs under this profile.
  • One private repository per pool, with a runner group restricted to that repository and to listed workflows on protected branches. Do not admit untrusted pull requests: every admitted job can read the prepared dependencies.
  • Linux only. Container jobs, native modules and arbitrary monorepo layouts are not qualified.

A small dependency tree can be slower this way than an ordinary pnpm install with a warm cache, because the fixed cost of checking inputs dominates. Measure your own workload before relying on it.

Where the prepared tree comes from

The machine’s operator builds the dependency tree in a separate, clean environment from the same runner image, with a frozen lockfile and lifecycle scripts disabled. It is never taken from the disk of a finished job. The owner reviews and approves it before any job can use it, and can revoke it.

Registry tokens, Git credentials and job logs must not be part of a prepared tree. Private packages in it stay private to the one repository the pool serves.

The source repository is private. Source access is by request.

Search concepts, guides and command examples.