Gitpod Prebuild State Persistence for Interactive Setup

Answer to the Core Questions

1. Can prebuild snapshots pause for external input without triggering a timeout?

No. A prebuild runs in a headless, non‑interactive environment. All commands in the prebuild section must finish within the allotted prebuild timeout (usually 15 minutes). If a step requires user interaction, it will fail and the prebuild will be marked as failed.

2. Is there a mechanism to inject runtime secrets into a prebuilt snapshot that preserves the filesystem state?

Secrets cannot be baked into the prebuild snapshot because the snapshot is a read‑only image of the filesystem. The only supported way to supply secrets is at workspace start via Gitpod secrets or environment variables. Those secrets are injected into the workspace’s runtime environment, not into the prebuilt image itself.

However, you can use the prebuild to create configuration files that reference placeholders. At workspace start, an onCreate or tasks script can replace those placeholders with secret values, thereby persisting the final state in the workspace’s filesystem.

Practical Steps to Achieve Interactive Setup with Prebuilds

1. Define a prebuild that writes a template config file. This file should include a placeholder for the secret (e.g., __TOKEN__).

   prebuild:
     tasks:
       - init: |
           echo "apiToken=__TOKEN__" > .config/token.conf
   

2. Use the onCreate section to run an interactive script after the workspace starts. This script can prompt the user for a token or read it from a Gitpod secret and replace the placeholder.

   onCreate:
     - init: |
         if [[ -z "$TOKEN" ]]; then
           read -p "Enter your API token: " TOKEN
         fi
         sed -i "s/__TOKEN__/$TOKEN/g" .config/token.conf
   

3. Optionally, cache the dependency installation in the prebuild to speed subsequent workspaces.

   cache:
     - node_modules
   

4. Commit the .gitpod.yml and any template files to the repository.

5. Verify the prebuild by opening the Prebuilds tab in the Gitpod UI. Check that the image shows a cache hit and that the .config/token.conf file exists after workspace launch.

6. Use gp status in the terminal to confirm that the secret environment variable $TOKEN is present.

Verification Checklist

• Open .gitpod.yml and confirm prebuild, onCreate, and cache sections are present.
• Launch a workspace and inspect the filesystem for .config/token.conf containing the token value.
• In the Gitpod web UI, view the Prebuilds tab to see a successful cache hit.
• Run gp secret list to ensure the secret is defined and not stored in the repository.

What We Still Need to Know

To tailor the recommendation further, could you confirm whether the token you need to inject is already available as a Gitpod secret, or will it have to be entered manually during workspace start?