gitpod Documentation

File: README.md Copy Chapter

Gitpod has been renamed to Ona - mission control for software projects and software engineering agents. We no longer recommend this version of Gitpod, users should take advantage of Ona's free tier or contact sales for enterprise. With Ona you gain more powerful development environments than Gitpod Classic with industry-standard specifications based on Dev Container and Ona Agents.

Gitpod Classic Copy Chapter

Gitpod Classic is a developer platform providing on-demand, pre-configured development environments in the cloud. It allows developers to spin up secure workspaces with a simple .gitpod.yml configuration file, eliminating the need for manual environment setup. The platform integrates seamlessly with GitHub, GitLab, Bitbucket, and Azure DevOps, offering features like prebuilt environments, collaborative code reviews, and professional developer experience with VS Code extensions and customization options. Workspaces are ephemeral, secure, and based on Docker, providing developers with the same capabilities as their local Linux machines but in a consistent, reproducible cloud environment.

Important: Gitpod Classic pay-as-you-go did sunset on October 15th 2025. See our blog for detailed instructions.

Documentation Copy Chapter

All documentation can be found on www.gitpod.io/docs. For example, see Gitpod tutorial and check the following helpful resources:

• Workspace Lifecycle
• Configure repositories
• Organizations
• IDE & Editors support
• Video screencasts
• Gitpod samples

Related Projects Copy Chapter

During the development of Gitpod, we also developed some of our infrastructure toolings to make development easier and more efficient. To this end, we've developed many open-source projects including:

• Workspace images: Ready to use docker images for Gitpod workspaces
• OpenVSCode Server: Run the latest VS Code on a remote machine accessed through a browser
• Gitpod browser extension: It adds a Gitpod button to the configured GitLab, GitHub, Bitbucket and Azure DevOps installations

File: components/blobserve/README.md Copy Chapter

Required Permssion

If you want it to work in a particular public cloud, you may need to grant some permissions.
Below is a reference for this.

AWS IAM Policy Copy Chapter

If you would like to use ECR as a container registry, please add the following IAM policy below.
Also, if you want to use ECR as public, you should add ecr-public too.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        }
    ]
}

File: components/common-go/nsenter/README.md Copy Chapter

nsenter Copy Chapter

Credits Copy Section

This package was taken from seccomp agent and adapted for the needs of workspacekit.

Source: https://github.com/kinvolk/seccompagent/blob/main/pkg/nsenter/README.md
Original Source: https://github.com/opencontainers/runc/blob/master/libcontainer/nsenter/README.md

How does it work? Copy Section

The nsenter package registers a special init constructor that is called before
the Go runtime has a chance to boot. This provides us the ability to setns on
existing namespaces and avoid the issues that the Go runtime has with multiple
threads. This constructor will be called if this package is registered,
imported, in your go application.

The nsenter package will import "C" and it uses cgo
package. In cgo, if the import of "C" is immediately preceded by a comment, that comment,
called the preamble, is used as a header when compiling the C parts of the package.
So every time we import package nsenter, the C code function nsexec() would be
called.

Because nsexec() must be run before the Go runtime in order to use the
Linux kernel namespace, you must import this library into a package if
you plan to use libcontainer directly. Otherwise Go will not execute
the nsexec() constructor, which means that the re-exec will not cause
the namespaces to be joined.

File: components/common-go/README.md Copy Chapter

How to upgrade Kubernetes dependencies

General steps:

1. Check https://github.com/kubernetes/kubernetes/releases for the Kubernetes version. E.g. we use EKS 1.31, latest 1.31 Kubernetes release is 1.31.8 which is Kubernetes version 31.8. Run ./go-get-kubernetes.sh 31.8.
2. modify target versions in go-update-wc-deps.sh
3. run ./go-update-wc-deps.sh
4. if it fails, fix the test/code, and run it again until all tests are good - except install/installer
5. take care of install/installer
6. manually verify that the go.mod has the target versions set, and if not, adjust manually (not sure why these get overriden there)
7. make sure helm.sh/helm/v3 is set to a compatible version (refer to https://github.com/helm/helm/releases/ to see which release bumps "k8s-io" to which version)
8. test with go mod tidy && go test ./... until it succeeds

gpl: I just noticed that probably go-get-kubernetes.sh was meant for bumping kubernetes versions in common-go - which I did manually. So probably that should be the very first step.

File: components/dashboard/README.md Copy Chapter

Dashboard

The dashboard is written in TypeScript and React. For styling it uses TailwindCSS which is a bit nicer than inlining CSS as it supports pseudo classes and a is a little more abstract/reusable.

The App.tsx is the entry point for the SPA and it uses React-Router to register all pages.

<Switch>
    <Route path="/" exact component={Workspaces} />
    <Route path="/profile" exact component={Profile} />
    <Route path="/notifications" exact component={Notifications} />
    <Route path="/subscriptions" exact component={Subscriptions} />
    <Route path="/env-vars" exact component={EnvVars} />
    <Route path="/git-integration" exact component={GitIntegration} />
    <Route path="/feature-preview" exact component={FeaturePreview} />
    <Route path="/default-ide" exact component={DefaultIDE} />
</Switch>

Pages are loaded lazily using React.lazy so that not everything needs to be loaded up-front but only when needed:

const Notifications = React.lazy(() => import("./account/Notifications"));
const Profile = React.lazy(() => import("./account/Profile"));
const Subscriptions = React.lazy(() => import("./account/Subscriptions"));
const DefaultIDE = React.lazy(() => import("./settings/DefaultIDE"));
const EnvVars = React.lazy(() => import("./settings/EnvVars"));
const FeaturePreview = React.lazy(() => import("./settings/FeaturePreview"));
const GitIntegration = React.lazy(() => import("./settings/GitIntegration"));

Global state is passed through React.Context.

After creating a new component, run the following to update the license header:
leeway run components:update-license-header

How to develop in gitpod.io Copy Chapter

Against any* Gitpod installation Copy Section

Gitpod installations have a feature that - if you are authorized - allow different versions of the dashboard. This allows for front-end development with live data and super-quick turnarounds.

Preconditions

1. logged in user on the respective Gitpod installation (e.g. gitpod.example.org)
2. user has the "developer" role

Steps

1. Start a workspace (on any installation), and start the dev-server with yarn start-local
2. Configure your browser to always send header X-Frontend-Dev-URL with value set to the result of gp url 3000 to the Gitpod installation you want to modify (gitpod.example.org)
3. Visit https://gitpod.example.org, start modifying your dashboard in your workspace, and experience the effect live (incl. hot reloading)

*: This feature is not enabled on all installations, and requires special user privileges.

Outdated, in-workspace (?) Copy Section

All the commands in this section are meant to be executed from the components/dashboard directory.

1. Environment variables

Set the following 2 environment variables either via your account settings or via the command line.

You are not expected to update the values of these variables for a long time after you first set them.

🚨 Heads up! Be careful when using the command line, as the gp CLI will restrict the scope of the variables to the current project, meaning if you are not already working from your own personal fork you'll end up having variables you can't access when you do.

You can always go to your account settings and edit the scope for each variable to something like */gitpod.

# Use "gitpod.io" for the SaaS version of Gitpod, or specify the host of your self-hosted gitpod
GP_DEV_HOST=gitpod.io

# Notice the cookie name (_gitpod_io_v2_) may be different if self-hosted.
# Read below for how to get the actual value to use instead of "AUTHENTICATION_COOKIE_VALUE"
GP_DEV_COOKIE="_gitpod_io_v2_=AUTHENTICATION_COOKIE_VALUE"

Replace AUTHENTICATION_COOKIE_VALUE with the value of your auth cookie taken from your browser's dev tools while visiting your target Gitpod host (e.g. s%3Axxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.XXXXXXXXXXXXXXX).

2. Start the dashboard app

🚀 After following the above steps, run yarn run start to start developing.
You can view the dashboard at https://PORT_NUMBER-GITPOD_WORKSPACE_URL (PORT_NUMBER is usually 3000).

How to run tests in watch mode Copy Section

Open a terminal, launch the dashboard app (see instructions above):

yarn start

When the dashboard app is up and running, open another terminal using Bash as shell (this is mandatory at the moment)

File: components/ee/agent-smith/README.md Copy Chapter

Agent Smith 🕵️‍♂️

Agent smith is the component that takes care of policing workspaces
against threats and noisy neighbours to make sure that everyone gets a safe and
smooth Gitpod experience.

How to add new signatures? Copy Chapter

# find something to match, e.g. using elfdump or by inspecting scripts
agent-smith signature elfdump 

# create a new signature
agent-smith signature new ...

Hint: do not use the base64 to encode a signature

How can I check if a signature matches? Copy Chapter

agent-smith signature new <signature-args> | agent-smith signature match <test-binary>

File: components/gitpod-cli/README.md Copy Chapter

Gitpod CLI

A CLI binary that comes pre-installed within the Gitpod workspace environments.

Description Copy Chapter

Here are a few of the things you can do with it:

• Open a file in the IDE
• Open a URL in the IDE's preview
• Watch the progress of a running task defined on .gitpod.yml by attaching the terminal to its process.
• Control user-defined environment variables
• Stop the current workspace
• Notify and wait for events to happen, to control the order of execution of terminal tasks
• Make a port available on 0.0.0.0 so that it can be exposed to the Internet
• Wait for a process to listen on a port
• Print the URL of the current workspace
• Take a snapshot of the current workspace
• Create a Gitpod configuration for the current project

Learn more about it by running gp —-help or checking the documentation.

Useful Links Copy Chapter

• Usage Docs
• GitHub Issues

Contributing Copy Chapter

• The Gitpod CLI is written in Go.
• Most of the functionalities that the CLI implements, make use of the Supervisor API.

If you would like to contribute to this component, check the related GitHub issues or start a discussion in the Discord #contributing channel.

Ownership Copy Chapter

To know which Gitpod Team owns this component, check the CODEOWNERS.

File: components/gitpod-db/src/typeorm/migration/README.md Copy Chapter

TypeORM DB Migrations

To create a new migration file, run this command in the gitpod-db component directory:

yarn typeorm migration:create -n NameOfYourMigration
leeway run components:update-license-header

Then, simply populate the up and down methods in the generated migration file.
(Hint: You can look at other migration files for inspiration.)

File: components/gitpod-db/README.md Copy Chapter

Gitpod-db Copy Chapter

Contains all the database related functionality, implemented using typeorm.

Working on gitpod-protocol component Copy Section

When you are making changes to gitpod-protocol component, make sure to run yarn build in gitpod-protocol folder to make sure your changes will be rebuild. Also consider running yarn watch so that any changes are rebuilt in realtime.

Adding a new table Copy Section

1. Create a migration - use the baseline as an exemplar
2. Create a new entity that implements the requisite interface or extend an existing entity as required - see db-user.ts
3. If it is a new table, create the matching injectable ORM implementation and interface (if required) - see user-db-impl.ts and user-db.ts. Otherwise extend the existing interface and implementation as required.
4. Add the injectable implementation to the DB container module, binding the interface and implementation as appropriate, otherwise it will not be instantiated correctly e.g.

bind(TypeORMUserDBImpl).toSelf().inSingletonScope();
    bind(UserDB).toService(TypeORMUserDBImpl);

5. Add the new ORM as an injected component where required e.g. in user-controller.ts

@inject(UserDB) protected readonly userDb: UserDB;

File: components/ide/jetbrains/gateway-plugin/README.md Copy Chapter

Gitpod Gateway Copy Chapter

Provides a way to connect to Gitpod workspaces.

This plugin is based on the IntelliJ Platform Plugin Template.

Development Copy Chapter

This project is not Gitpodified yet because it requires running the JetBrains Gateway locally. For now, for development, contributors can use IntelliJ IDEA installed on their machines.

Testing Copy Chapter

For testing purposes, it's possible to build the plugin and launch a JetBrains Gateway instance which comes with the dev build of the plugin pre-installed.

Run:

./gradlew runIde

If you want to open a real workspace in the dev build, follow these steps:

1. Start a workspace
2. Open the terminal and run
   console Copy

   curl http://localhost:24000/gatewayLink
   
   # This will output something like:
   # jetbrains-gateway://connect#gitpodHost=gitpod.io&workspaceId=andreafalze-gitpodexper-4xasfqb42zr&backendPort=63342

3. Copy the output value
4. Go to your local terminal and run:
   console Copy

   ./gradlew runIde --args="jetbrains-gateway://connect#gitpodHost=gitpod.io&workspaceId=andreafalze-gitpodexper-4xasfqb42zr&backendPort=63342"

For executing the tests and the static analysis validations, run:

./gradlew check

Note: Gradle should run with Java 11.

How to test from a Pull Request Copy Chapter

• Ensure you have the latest JetBrains Gateway installed: https://www.jetbrains.com/remote-development/gateway/
• Download this Gateway Plugin build, from Gitpod's Plugin Dev Channel: https://plugins.jetbrains.com/plugin/18438-gitpod-gateway/versions/dev
• Install it on the Gateway following these instructions: https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk
• Do the checks requested by the pull request creator or do a full manual test as instructed below.

Checklist for a Full Manual Test Copy Chapter

• Check if you can create a new workspace
• Check if you can connect to a running workspace
• Check if you can connect to a stopped workspace
• Check if changing the "Gitpod Host" in Preferences >> Tools >> Gitpod takes effect
• Check if the info displayed in the workspaces list is matching what you see on the Web App Dashboard