When a Gitpod workspace times out, is there a configurable grace period for process cleanup?

Short answer

Gitpod does not expose a documented, user-configurable grace period for arbitrary in-flight processes when an inactivity timeout stops a workspace. The only user-facing controls are the inactivity timeout itself and workspace pinning. Neither option extends a post-timeout cleanup window.

Confirmed behavior versus inferred platform behavior

Confirmed product behavior: you can adjust the inactivity timeout at the user or team level, and pinning a workspace prevents automatic inactivity stops. The .gitpod.yml tasks section controls startup commands only; there is no documented shutdown or pre-termination hook for arbitrary processes.

For Gitpod Classic, workspaces run as Kubernetes pods. That means container termination follows standard Kubernetes pod shutdown semantics—typically a SIGTERM followed by SIGKILL after the pod's termination grace period. However, Gitpod does not surface that grace period as a product setting, nor does it guarantee that arbitrary user processes receive meaningful cleanup time. Treat the Kubernetes grace period as an infrastructure default, not a Gitpod feature.

Gitpod Flex uses a different workspace lifecycle architecture. Its timeout and cancellation semantics are not documented in the same terms as Classic, so you should not assume the two platforms behave identically.

Practical steps for long-running tasks

1. Do not rely on a shutdown grace period. Checkpoint state to external storage or a database at regular intervals.
2. For jobs that must survive workspace stops, run them outside the workspace—for example, in a CI pipeline or a dedicated VM.
3. If you need the workspace to stay alive during a critical phase, pin it. Remember that pinning prevents inactivity stops but does not create a cleanup window.

Verifying current behavior in your environment

Because documentation does not guarantee a cleanup window and Flex behavior may differ, verify empirically before relying on any signal handling. Create a small script that traps SIGTERM and appends to a file in your project directory, run it in the background, let the workspace time out, then restart the workspace and inspect the file.

#!/bin/bash\ntrap 'echo "SIGTERM at $(date)" >> ./shutdown-test.log; exit 0' TERM\nwhile true; do sleep 1; done

If the log entry appears after restart, the workspace delivered a termination signal and allowed the trap to run. If the file is empty or missing, the process was killed before it could flush state. Repeat the test separately on Flex if you use both platforms.