Skip to content
Source
Sign inSign up

Run hooks in workspaces

Work with agents / Local workspaces

Run hooks in workspaces

A new workspace sometimes needs more than its dependencies, for example a database with test data. Hooks run your commands when a workspace is made, when src ws accept tests its changes, and when the workspace closes.

3 min read

1. Add the hooks

In .source/workspace.yaml:

hooks:
  setup: pnpm db:seed
  validate: pnpm test
  teardown: pnpm db:drop
HookWhen it runs
setupIn each new workspace, after its layers are ready, its env files are copied and its ports are set.
validateIn the candidate folder of src ws accept, before your checkout changes. If it exits with a code other than 0, accept stops, shows the output, and your checkout does not change.
teardownIn close, after src stops the processes that the workspace owns. Then close gives the folder to the pool of ready workspaces. When the pool is off, it deletes the folder.

2. Trust the hooks

src ws trust

The hooks are commands of the config, so they run only after src ws trust.

3. Create a workspace

src ws create api

create runs setup in the new workspace.

Done

Each new workspace runs setup, each accept runs validate before your checkout changes, and each close runs teardown.

What the hooks get

setup and teardown get the environment of src ws exec: the ports, the caches, and the vault values after src ws trust. restore and sync do not run setup again.

To skip the hooks once, add --no-hooks to create, close, accept or repair.

When a hook fails

  • When setup fails, the workspace stays. Its state is setup-failed, and create shows the end of the output and exits 1. Fix the cause, then repair the workspace.
  • When teardown fails, close shows the output and still closes the workspace.

Repair a workspace

A setup hook failed, or a layer folder of a workspace is gone. Fix the cause, then run:

src ws repair api

repair runs the steps that did not finish:

  1. If the create of the workspace failed, it makes the folder again from its baseline.
  2. It makes each layer again that failed, or whose folder is gone. The other layers stay.
  3. It copies missing env files again, and sets the read-only flags again.
  4. If setup failed before, or the folder is new, it runs setup again.

When every step works, the state is live again. A workspace that needs nothing stays as it is, so you can run repair again with no harm. A workspace with conflicts from a sync needs src ws sync <name> --continue first.