## File: README.md

**[Gitpod has been renamed to Ona](https://ona.com/stories/gitpod-is-now-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](https://app.gitpod.io/) or [contact sales for enterprise](https://ona.com/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 

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](https://ona.com/stories/gitpod-classic-payg-sunset)** 2025. See our blog for detailed instructions.

## Documentation

All documentation can be found on [www.gitpod.io/docs](https://www.gitpod.io/docs). For example, see [Gitpod tutorial](https://www.gitpod.io/docs/introduction/gitpod-tutorial) and check the following helpful resources:
  - [Workspace Lifecycle](https://www.gitpod.io/docs/configure/workspaces/workspace-lifecycle)
  - [Configure repositories](https://www.gitpod.io/docs/configure/repositories)
  - [Organizations](https://www.gitpod.io/docs/configure/orgs)
  - [IDE & Editors support](https://www.gitpod.io/docs/references/ides-and-editors)
  - [Video screencasts](https://www.gitpod.io/screencasts)
  - [Gitpod samples](https://github.com/gitpod-samples)

## Related Projects

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](https://github.com/gitpod-io/workspace-images): Ready to use docker images for Gitpod workspaces
- [OpenVSCode Server](https://github.com/gitpod-io/openvscode-server): Run the latest VS Code on a remote machine accessed through a browser
- [Gitpod browser extension](https://github.com/gitpod-io/browser-extension): It adds a Gitpod button to the configured GitLab, GitHub, Bitbucket and Azure DevOps installations

---

## File: components/blobserve/README.md

# 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

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.

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

---

## File: components/common-go/nsenter/README.md

## nsenter

### Credits

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?

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](https://golang.org/cmd/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

# 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`.
 1. modify target versions in `go-update-wc-deps.sh`
 1. run `./go-update-wc-deps.sh`
   1. if it fails, fix the test/code, and run it again until all tests are good - except `install/installer`
 1. take care of `install/installer`
   1. manually verify that the `go.mod` has the target versions set, and if not, adjust manually (not sure why these get overriden there)
   1. 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)
   1. 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

# 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.

```ts
<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:

```ts
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

### Against any* Gitpod installation

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)
 1. user has the `"developer"` role

**Steps**
 1. Start a workspace (on any installation), and start the dev-server with `yarn start-local`
 1. 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)
 1. 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 (?)

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](https://www.gitpod.io/docs/environment-variables) either [via your account settings](https://gitpod.io/variables) or [via the command line](https://www.gitpod.io/docs/environment-variables#using-the-command-line-gp-env).

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`.

```bash
# 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`).

| ℹ️ How to get the cookie name and value                                    |
| -------------------------------------------------------------------------- |
|  |

#### 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

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

```sh
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

# 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?
```
# 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?
```
agent-smith signature new <signature-args> | agent-smith signature match <test-binary>
```

---

## File: components/gitpod-cli/README.md

# Gitpod CLI

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

## Description

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](https://www.gitpod.io/docs/command-line-interface/).

## Useful Links

- [Usage Docs](https://www.gitpod.io/docs/command-line-interface)
- [GitHub Issues](https://github.com/gitpod-io/gitpod/labels/component%3A%20gp%20cli)

## Contributing

- The Gitpod CLI is written in [Go](https://go.dev/).
- Most of the functionalities that the CLI implements, make use of the [Supervisor API](https://github.com/gitpod-io/gitpod/tree/main/components/supervisor-api).

If you would like to contribute to this component, check the [related GitHub issues](https://github.com/gitpod-io/gitpod/labels/component%3A%20gp%20cli) or start a discussion in the Discord [#contributing](https://discord.com/channels/816244985187008514/885406100436951080) channel.

## Ownership

To know which Gitpod Team owns this component, check the [CODEOWNERS](https://github.com/gitpod-io/gitpod/blob/main/.github/CODEOWNERS).

---

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

# 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

## Gitpod-db

Contains all the database related functionality, implemented using [typeorm](https://typeorm.io/).

### Working on gitpod-protocol component
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
1. Create a [migration](./src/typeorm/migration/README.md) - use the [baseline](./src/typeorm/migration/1592203031938-Baseline.ts) as an exemplar
2. Create a new entity that implements the requisite interface or extend an existing entity as required - see [db-user.ts](./src/typeorm/entity/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](./src/typeorm/user-db-impl.ts) and [user-db.ts](./src/user-db.ts). Otherwise extend the existing interface and implementation as required.
4. Add the injectable implementation to the [DB container module](./src/container-module.ts), 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](./src/user/user-controller.ts)
```
    @inject(UserDB) protected readonly userDb: UserDB;
```

---

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

## Gitpod Gateway


Provides a way to connect to Gitpod workspaces.



This plugin is based on the [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template).

## Development

This project is not Gitpodified yet because it requires running the JetBrains Gateway locally. For now, for development, contributors can use [IntelliJ IDEA](https://www.jetbrains.com/idea/) installed on their machines.

## Testing

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:

```console
./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
    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
    ./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:

```console
./gradlew check
```

**Note**: Gradle should run with Java 11.

## How to test from a Pull Request

- 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

- 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