Working in a run's shell

A terminal step stops a run for a person to work in its workspace from a shell, then carries on when they press Done.

Some work is a person's to do by hand: signing a build with a key that never leaves a laptop, poking at a database, re-running a test the agent couldn't explain. A terminal step stops the run and gives somebody a shell in the phase's workspace:

- type: terminal
  name: Sign the build
  note: Run ./sign.sh with your key, then press Done.

The step's card in the run says what it asks, with Open terminal and Done. The shell opens under the transcript on the web and in the desktop app, beside the transcript on a Mac or an iPad, and full screen on a phone, with a row of keys a phone's keyboard lacks.

What the shell is

It runs on the machine the phase runs on, in its workspace, with the same environment the steps get — the run's secrets included — and it can reach the network. What you change there goes out with the phase's commit; the steps after it see the tree you left.

More than one person can open it, each with a shell of their own. Closing yours doesn't end the step: it waits for Done.

Who may open it

Open terminals, in the project the run belongs to. Nobody has it until a role grants it — Everyone doesn't. A step can narrow it further to roles and people it names:

  attendees:
    - role: [Release managers]
    - member: [ana@example.com]

Anybody who may open it may press Done, whoever started the run.

What is recorded

The transcript says who opened a shell and when they closed it, and the audit log has a row for each. What was typed and what the shell printed are not stored anywhere.

It does not pin a machine

While nobody has a shell open, Peractor keeps the machine warm for a few minutes, then saves the workspace and gives the machine back — the step still waiting. Opening it again brings the workspace back on a machine first, which takes a moment. A shell nobody has typed in for half an hour is closed.

Resume with a terminal

When a phase fails and keeps its work, the failed step's menu offers Resume from this step, which runs the phase again from there over what the earlier steps produced, and Resume with a terminal: the phase starts again over that work, stops before the step that failed with a shell for you to look into it, and runs the step again when you press Done. Both need Start runs, as a restart does; the terminal one needs Open terminals too.