Skip to main content

Diagnose Job Execution with Web Terminal

Use a web terminal to inspect a running command step and change its live workspace while diagnosing a problem. This requires an active Enterprise subscription, available under Administration / Subscription Management.

Pause a Command Step​

Insert @pause@ on its own line at the point you want to inspect. For example, run the following commands in an alpine:3.20 container:

echo before-pause
echo terminal-fixture > proof.txt
@pause@
test -f terminal-proof.txt
cat terminal-proof.txt
echo after-pause

Start the job and open its Log tab. The step stops at Execution paused, with a Resume link. Set the job timeout long enough for your investigation: pausing does not disable the timeout.

Paused command step and terminal button

Inspect the Running Step​

Click the terminal button beside the running build status. It opens a separate window; allow pop-ups for your OneDev site if your browser blocks it.

Terminal access can change the running job. Project managers can open it; code writers must also satisfy the applicable build-spec modification restrictions. A pull request submitter can open the terminal for their pull request build. Merely being able to run a job does not grant terminal access.

In the terminal, inspect the workspace and create the file expected by the paused command:

pwd
cat proof.txt
printf 'web-terminal-ok\n' > terminal-proof.txt
cat terminal-proof.txt

Interactive terminal inspecting and modifying the build workspace

The example prints /onedev-build/work, terminal-fixture, and web-terminal-ok. The terminal operates in the running step's environment, so available commands depend on its image or executor host.

Resume Execution​

Return to the build log and click Resume. The example verifies the file created in the terminal, prints web-terminal-ok and after-pause, and succeeds. Close the terminal window when finished. You can also cancel the build if it should not continue.

This walkthrough was verified with the server Docker executor. The terminal is also available with other supported executors; their shell and environment depend on the executor configuration.