Updates and Maintenance
This guide covers how to keep your Linux runner updated and running smoothly.
Version Management
The runner periodically checks for newer versions and logs a message when updates are available. You can see the current version of your runner in the Gitpod UI under Settings -> Runners.
Updating the Runner
Updates are performed manually using the Gitpod CLI. To update your runner:
-
Stop the runner
-
If running in the terminal, press Ctrl+C
-
If running as a service:
Stopping the runner does not stop any running environments. The environments will continue running, but the runner will not process any new start/stop requests or report environment status updates to Gitpod while it is stopped.
-
-
Run the update command:
-
Restart the runner
- If running in the terminal:
- If running as a service:
- If running in the terminal:
Monitoring
Logs
- If running in the terminal, logs are printed directly to stdout
- If running as a systemd service, view logs with:
Use the -f
flag to follow logs in real-time:
Runner Status
You can monitor your runner’s status in the Gitpod UI under Settings -> Runners. The status will show:
- Connection state
- Version information
- Any warning or error messages
Resource Management
The Linux runner runs environments as virtual machines on your host. The runner has a built-in limit of 10 environments (excluding deleted environments) per runner. To maintain good performance:
- Monitor system resource usage (CPU, memory, disk)
- Consider the number of concurrent environments
- Keep sufficient free disk space for environment data
Best Practices
-
Regular Updates
- Watch for update notifications in the logs
- Plan updates during low-usage periods
- Keep the runner up to date for the latest features and fixes
-
Log Management
- If using systemd, consider configuring log rotation
- Monitor logs periodically for warnings or errors
- Keep track of resource usage patterns
-
Backup Considerations
- The runner stores environment data in
~/gitpod-runner
- Consider this location in your backup strategy if needed
- The runner stores environment data in
-
System Maintenance
- Keep the host system updated
- Monitor system health
- Maintain sufficient free resources
Common Maintenance Tasks
Checking Runner Status
Restarting the Runner
Deleting the Runner
To completely remove a runner:
-
Delete the runner from Gitpod in Settings -> Runners
-
On your Linux machine:
a. Stop the runner process:
- If running in the terminal, press Ctrl+C or terminate the
gitpod runner run
process - If running as a systemd service:
b. Remove runner files and environment data:
c. If you set up a systemd service, remove it:
- If running in the terminal, press Ctrl+C or terminate the
Next Steps
- Troubleshooting guide for common issues
- System requirements for reference
- Setup guide for installation details
Was this page helpful?