Understanding Gitpod configuration
The .gitpod.yml
file
The primary method of configuration is using a YAML file named .gitpod.yml
, located at the root of your repository. The gitpod.yml
file defines (for example):
- The processes to start for your project - e.g. a database or webserver.
- Required tools to install before the project starts.
- Any editor extensions or IDE plugins to install.
A gitpod.yml example
.gitpod.yml
yarn
project with a webserver, exposed on port 3000. On start, an in-editor preview of the webserver is opened automatically.
The workspace image
In addition to thegitpod.yml
you can also specify a workspace image for:
- Application portability
- Re-using an existing Dockerfile
Creating a Gitpod configuration
You can create a.gitpod.yml
manually, or by using the gp init
command (or gp init -i
for interactive mode). The gp
CLI tool is part of the Gitpod CLI, which is included in all Gitpod workspaces by default.
Validate your Gitpod configuration
You can test your configuration, including your.gitpod.yml
, without leaving your workspace or committing your changes by using the gp validate
command. This command opens a workspace (that runs from within your current workspace) which includes your configuration changes. Thus, allowing you to troubleshoot workspace configuration (ports, tasks, etc.) and more.
You can use the gp validate
command to test various configuration setups: simple workspace starts (without Prebuilds enabled), workspace starts using a Prebuild, or for debugging Prebuilds themselves. See below for the differences:
Command | Steps ran |
---|---|
gp validate | before + init + command |
gp validate --prebuild | before + init |
For improved speed and convenience while updating your workspace configuration, consider starting your workspace using a large Workspace Class.
Validate a workspace start
- Run
gp validate
to emit a Workspace URL. - Open the workspace and review your configuration.
- Update your configuration in the original workspace, and re-run
gp validate
(if needed).
Validate a Prebuild
You can rungp validate --prebuild
to validate how a prebuild process would look upon completion (this runs before
and init
tasks, but not command
tasks).
- Run
gp validate --prebuild
- This command will emit a Workspace URL. - Open the workspace to check your configuration.
- Update configuration in the original workspace, re-running
gp validate
if needed.
Important: This command runs the workspace as a Prebuild not from a prebuild. Meaning this produces the same environment that is created by a Prebuild process, before a workspace is subsequently started using it.
Apply configuration changes
To apply your changes for all subsequent workspaces, commit and push thegitpod.yml
(and .gitpod.Dockerfile
if you created one) to the root of your repository.
Open the commit in a new workspace by either:
- Prefixing your repo URL with
https://gitpod.io/#
- For example: https://gitpod.io/#https://github.com/nodejs/node
- Opening a new workspace from the Gitpod dashboard
- Installing, and using the Gitpod Browser Extension
Important: You must commit the
.gitpod.yml
to the root of the repository and start a new workspace for changes to apply (a workspace restart is not sufficient).FAQs
Can I use an Android emulator with Gitpod and JetBrains IntelliJ IDEA for Android development?
Android app development is possible in Gitpod, but you cannot directly run an Android emulator on Gitpod. Check this relevant issue: You have two options:- Connect to a physical device with a wirelessly exposed
adb
server. Some guides: - Use the exposed
adb
server from a local Android emulator (e.g. from JetBrains Android Studio)
adb
server inside a Gitpod workspace. For instructions, see:
You might also want to use Gitpod with JetBrains IDE locally:
For Flutter Android development, there is a template available: gitpod-samples/template-flutter