Gitpod can provide fully initialized, perfectly set-up developer environments for any kind of software project. This page helps you understand how to provide such a configuration for your project.
Start your first workspace
The best way to configure Gitpod is by using Gitpod - you could perform the following steps in your local environment as well, but we may as well experience ephemeral developer environments right from the beginning.
- In a browser, navigate to your project’s GitHub, GitLab or Bitbucket page.
- In the browser’s address bar, prefix the entire URL with
gitpod.io/#and press Enter.
- For example,
- We recommend you install the Gitpod browser extension to make this a one-click operation.
- For example,
- Sign in with one of the listed providers and let the workspace start up.
Congratulations, you have started your first of many ephemeral developer environments 🎉!
💡 You can also start a Gitpod workspace with more options. Learn more
Open in Gitpod button
You can add the following button to your Development/Setup Docs so that users can launch projects in Gitpod and begin working on them without having to go through the entire setup process.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#<your-repository-url>)
your-repository-urlcan be something like:
https://github.com/gitpod-samples/awesome-gitpodor any of your Repository URLs.
Contribute with Gitpod badge
To make it easy for anyone to start a Gitpod workspace based on your project, we recommend you add a badge to your
<a href="https://gitpod.io/#<your-repository-url>"> <img src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod" alt="Contribute with Gitpod" /> </a>
Next, let’s help Gitpod understand your repository to automate the developer environment and turn on prebuilds to supercharge your development workflow.
Help Gitpod understand your repository
When you started your first workspace above, Gitpod didn’t do much. In fact, all it did was start the workspace and
git clone your source code.
To develop, you still would have to install dependencies, run build scripts and start the development server every time you start a workspace… We can do better, so let’s automate that!
- In the workspace terminal, make sure you are in your project’s root directory (
gp initto generate a scaffold
.gitpod.ymlconfiguration file (see the .gitpod.yml reference for all configuration options).
- Open the newly created
Most projects require some sort of initialization script to download and install dependencies, compile the source code, etc. For example, a Node.js project requires
npm install. The
init task by default reads
echo 'init script', let’s replace that with your project-specific init command, for example:
tasks: - init: npm install command: echo 'start script'
Excellent! To learn more about the difference between
command, please have a look at Start Tasks.
Next, let’s adjust the
command script. This is the script Gitpod executes when the workspace successfully started up. In most cases, this is where you start your application’s development server, e.g.
npm run dev.
tasks: - init: npm install command: npm run dev
Configure your app’s ports
If your application starts a development server that listens on a certain port, we can let Gitpod know how to deal with that. To get started, update the
port according to what your application listens on, e.g.
tasks: - init: npm install command: npm run dev ports: - port: 3000 onOpen: open-preview
When Gitpod notices port 3000 is available, it automatically opens your application in a preview to the right of your editor - ready for you to develop and see your changes.
Lastly, make sure to commit the
.gitpod.yml configuration file to Git and push it to your repository.
Start your second workspace
Once you committed and pushed
.gitpod.yml, open a new browser tab and navigate to your project’s page on GitHub, GitLab or Bitbucket.
If you pushed to a branch, please make sure you switch to that branch before you continue.
- Open a new workspace (see Start your first workspace above).
- Observe how Gitpod automatically runs the tasks you configured.
- Wait until the development server started and your application’s preview is displayed on the right side of the editor.
If for some reason the second workspace does not start, simply close the tab and navigate back to the first workspace. Fix the errors that caused the workspace to fail based on the error output you see, commit and push your changes and start yet another workspace to test the latest changes.
Congratulations, again 😊! You now have a basic Gitpod configuration and for each new workspace you start, Gitpod automatically runs the scripts you manually have to run locally.
Shut down your workspaces
This is easy - close the workspace browser tabs.
Within three minutes, the workspaces will be stopped. You can always find them at https://gitpod.io/workspaces - to be honest though, you can forget about them and start a new workspace the next time you work on your project.
Supercharge your experience with prebuilds
The automation you have experienced so far is nice, but there’s more! Remember that
init task we configured earlier?
You may have wondered why there are separate
command tasks. This is because we can tell Gitpod to run the
init script every time new code is pushed to your project. By the time you or one of your organization members starts a new workspace, the
init task already finished and you don’t have to wait for that - saving you precious time. We call this prebuilds.
An intro to prebuilds
Let’s first look at an example and then configure your project to take advantage of prebuilds.
Imagine this common workflow where Nina and Paul work on the same project:
- Nina opens a pull request where she developed a feature that requires a new dependency.
- Gitpod notices the new code and kicks off a prebuild by cloning the source code and executing the
inittask. The result is saved as a prebuilt workspace.
- Some time later, Paul opens the pull request to start his code review.
- He opens a Gitpod workspace for that given pull request (learn more about contexts).
- Gitpod recognizes it already ran the
inittask and loads the prebuilt workspace
- By the time the workspace starts, Paul sees the development server starting up and the application’s preview is ready for review.
For each new commit to your project, Gitpod continuously creates prebuilt workspaces so that the project is always ready-to-code. If your project is open source, anyone gets to enjoy the efficiency of prebuilds regardless of whether they are part of your organization or not.
Configure prebuilds for your projects
Depending on your Git provider, the steps to configure prebuilds vary slightly. Please refer to the dedicated Prebuilds page for detailed instructions on how to configure prebuilds for your project.
At this point, you have a
.gitpod.yml configuration file to automate repetitive tasks and prebuilds configured to let Gitpod execute many of these tasks continuously whenever new code is pushed to your project - freeing you from waiting to download, install & build your project and its dependencies.
To explore more of what Gitpod has to offer, we recommend the following next topics:
- Configure to learn more about start tasks, environment variables and how to provide your own custom Docker image as the foundation for workspaces.
- Develop to learn more about the productivity gains you get with ephemeral workspaces, how contexts assist you and how to collaborate with organization members.