# Account
Source: https://www.gitpod.io/docs/gitpod/account/overview



Gitpod provides secure authentication through trusted identity providers while maintaining your organization's security requirements. With an Account, you can create multiple organizations and switch between these easily.

<Frame caption="You can join multiple organizations using the same IdP identity.">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/accounts-gitpod-flex.png" />
</Frame>

## Supported Sign-in Methods

We support authentication using the following providers:

* Google
* GitHub
* Custom Single-Sign-on (configurable once you sign-up with the above)

## Account Creation

When signing in for the first time:

* Select either GitHub or Google as your authentication provider, and complete authentication through your selected provider.
* You'll be prompted to create a new organization or join an existing one
* If your email domain matches an organization's allowed domains, you'll see available organizations to join

## Account Deletion

If you no longer want to keep your Gitpod Account, you can delete it, together with all of your data at any time. Navigate to Settings > Profile and confirm your want to delete your account.


# Use Gitpod docs with AI
Source: https://www.gitpod.io/docs/gitpod/ai/use-docs-with-ai

Learn how to use Gitpod documentation with AI tools and language models for better development workflows.

You can use Gitpod documentation with your AI tool of choice, making it easy to search and get answers from our docs right from your editor or other AI tools.

## How it works

Large language models (LLMs) are great at reading markdown because, unlike HTML, there's a lot less noise for them to parse. To make our documentation more accessible to AI, we've provided markdown-accessible versions of our documentation so you can reference it with your own AI tools.

You can access plain-text markdown versions of our docs in a few ways:

* **[Our llms.txt file](#use-our-llm-sitemap)**: This is an emerging standard and acts as a sort of LLM-friendly sitemap. It provides links to our markdown files so your LLM can access markdown versions of our pages without having to download them.
* **[Download individual markdown pages](#download-plain-text-documentation)**: You can download or reference individual pages to add to your own knowledge base or use them as a reference for your LLM.

## Use our LLM sitemap

You can access or download our LLM-friendly documentation files to help your LLM access, and provide answers based on, markdown versions of our documentation.

We provide two versions of our documentation sitemap based on the emerging llms.txt standard:

* **[llms.txt](https://www.gitpod.io/docs/llms.txt)**: A concise version with links to all our documentation pages
* **[llms-full.txt](https://www.gitpod.io/docs/llms-full.txt)**: A comprehensive version with full content of all documentation pages included inline

The llms.txt files are flattened versions of our documentation sitemap based on an emerging standard for LLM-friendly documentation. While it's still an early standard, it can be a handy way to get answers from our docs without having to open a new browser tab or download individual pages.

* [Access our concise llms.txt file](https://www.gitpod.io/docs/llms.txt)
* [Access our comprehensive llms-full.txt file](https://www.gitpod.io/docs/llms-full.txt)
* [Learn more about the proposed llms.txt standard](https://llmstxt.org)

## Download plain text documentation

You can download or copy our documentation as plain text markdown files for use with your LLM of choice—you can even create your own GPTs and tools!

All of our documentation is written in MDX (Markdown with JSX), which is easily parseable by LLMs. You can access the source markdown for any page by adding `.md` to the end of most URLs to get the raw markdown version.

For example, you can check out the markdown for this page at `https://www.gitpod.io/docs/gitpod/ai/use-docs-with-ai.md`.


# Audit Logs
Source: https://www.gitpod.io/docs/gitpod/audit-logs/overview



Audit logs provide a record of all actions taken in a Gitpod organization. Using the audit logs, you can track who performed an operation, on which resource, and when. Gitpod produces audit logs for all operations within an organization.

## Accessing Audit Logs

Audit logs are accessible to users with the **Organization Owner** role. You can retrieve audit logs using the **Gitpod CLI** or the **Gitpod API**.

### Using the CLI

You can view audit logs using the `gitpod` CLI, which is pre-installed on all Gitpod environments.

```bash
gitpod audit-logs [--limit=number_of_entries]
```

For additional options, including filtering and output formatting (JSON or YAML), run:

```bash
gitpod audit-logs --help
```

#### Example Output

```bash
➜ gitpod audit-logs

SUBJECT ID                           SUBJECT TYPE            ACTOR ID                             ACTOR PRINCIPAL       ACTION                       CREATED AT
01951d94-d6ac-7edf-9021-a044cfd1908f RESOURCE_TYPE_ENVIRONMENT 0193e2f2-d0b5-7d52-87eb-235deadaf625 PRINCIPAL_RUNNER changed update_time, status, phase, last_running_session 2025-02-21T12:10:05Z
0194f5dd-01ca-75f4-a200-74381ed43f86 RESOURCE_TYPE_ENVIRONMENT 0193e2f2-d0b5-7d52-87eb-235deadaf625 PRINCIPAL_RUNNER changed update_time, status, phase, last_running_session 2025-02-21T12:10:03Z
...
```

### Using the API

You can retrieve audit logs programmatically via the Gitpod API. For detailed documentation, refer to the [API Reference](https://www.gitpod.io/docs/api-reference/resources/events/methods/list/).

#### Example Request

```bash
curl https://app.gitpod.io/api/gitpod.v1.EventService/ListAuditLogs \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{}'
```


# Configuring Automations
Source: https://www.gitpod.io/docs/gitpod/configuration/automations/basic-configuration

Explore Gitpod's automation features: Services and Tasks. Learn how to configure long-running services and execute specific tasks to streamline your development workflow. Understand execution options, dependencies, and best practices for efficient environment management.

# Basic configuration

When an environment is created the system loads Automations from the default file: `.gitpod/automations.yaml` relative to your repository root. You can change this location using [Projects](/flex/projects). An `automations.yaml` consists of services and tasks defined at the root level, for example:

```yaml
services: ...

tasks: ...
```

Services and tasks are a map where the key serves as reference for the corresponding item. When looking at task dependencies their use becomes clear.

See [reference](/flex/configuration/automations#reference) for a full example.

## Services in the automations.yaml

Example workflow:

```yaml
services:
    database:
        name: PostgreSQL
        description: The backend database
        triggeredBy:
            - postEnvironmentStart
        commands:
            start: 'docker run --rm -t --name database postgres:latest'
    redis:
        name: Redis
        description: Our message bus
        triggeredBy:
            - postEnvironmentStart
        commands:
            start: >-
                docker run --rm -t --name redis -p 6379:6379
                redis/redis-stack-server:latest
    backend:
        name: Application Backend
        description: The application backend
        triggeredBy:
            - postEnvironmentStart
        commands:
            start: cd backend && go run main.go
```

## Tasks in the automations.yaml

Example workflow:

```yaml
tasks:
    buildAll:
        name: Build All
        description: builds all code
        command: go build .
    runUnitTests:
        name: Runs unit tests
        command: go test -v ./...
    validate:
        name: Validate
        description: Builds and tests the code
        triggeredBy:
            - postEnvironmentStart
        dependsOn:
            - buildAll
            - runUnitTests
```

## Iterating on Automations

You can iterate on Automations using the [CLI](/flex/cli) which is available by default in every Gitpod environment. The CLI can

* reload the Automations file using:

```sh
gitpod automations update [optional-path-to-automations.yaml]
```

* start a task or service:

```sh
gitpod automations service start ...
gitpod automations task start ...
```

## Using Automations outside of an environment

The CLI commands to interact with an environment’s Automations are also available outside of an environment. The following snippet brings up an environment, adds a task, runs it, waits for the task to complete and brings the environment back down again:

```sh
# gitpod env create will set the environment context to the newly created env
gitpod env create https://github.com/some/repo

# add the task to the environment
cat <<EOF | gitpod automations update -
tasks:
  build:
    command: go build ./...
EOF

# run it
gitpod automations task start build

# stop the environment
gitpod env stop
```


# Examples
Source: https://www.gitpod.io/docs/gitpod/configuration/automations/examples



Gitpod enables a wide range of use cases for automated and secure development environments. Here are some ways you can leverage Gitpod, with concrete examples and explanations of how Automations support each use case:

## Automate Environment Setup

Gitpod allows you to fully automate the setup and configuration of development environments.

### One-click onboarding

New developers can start coding immediately without manual setup.

Example: An automation task clones multiple repositories, installs project-specific dependencies, and configures environment variables.

```yaml
tasks:
    build:
        name: Build Code
        command: yarn && yarn build
    test:
        name: Run unit tests
        dependsOn: ['build']
        command: yarn test
    setup:
        name: Set up the environment
        dependsOn: ['build', 'test']
        command: echo "all set up and ready to go"
```

### Database provisioning

Automatically create and seed databases for development.

Example: A service spins up a PostgreSQL database and runs migration scripts.

```yaml
tasks:
    seedDatabase:
        name: (Re)seed the development database
        triggeredBy: ['manual']
        command: dev/seed-development-db.sh
services:
    postgresql:
        name: PostgreSQL
        description: A fully initialized development database
        triggeredBy: ['postDevcontainerStart']
        commands:
            start: docker run -d --name postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgres:latest
            # Note: there is no support yet for task to service dependencies.
            ready: docker exec postgres pg_isready -U postgres && gitpod auto task start seedDatabase
```

### Cloud authentication

Securely authenticate to cloud services.

Example: A task uses Gitpod's built-in identity provider to authenticate with AWS.

```yaml
tasks:
    awsAuth:
        name: AWS Auth
        command: gitpod idp login aws
```

These Automations ensure consistent environments and dramatically reduce time spent on setup and configuration.

## Flexible Editing Interfaces

Launch the right editing interface for each project:

### Jupyter for data science

Example: Start a Jupyter Notebook server with required Python packages.

```yaml
services:
    jupyter:
        name: Jupyter Notebook
        command: |
            pip install jupyter pandas numpy matplotlib &&
            jupyter notebook --ip=0.0.0.0
```

### Storybook for UI development

Example: Automatically start Storybook server for component development.

```yaml
services:
    storybook:
        name: Storybook
        commands:
            start: yarn storybook
            ready: curl http://localhost:5173 -s -f -o /dev/null
```

## Self-Serve Testing Environments

Empower QA and testing with on-demand environments:

### Preview environments

Automatically create environments for pull requests.

Example: A service that builds and deploys the application to a preview URL.

```yaml
services:
    preview:
        triggeredBy: postDevcontainerStart
        commands:
            start: |
                npm install
                npm run build
                npx serve -p 3000 ./build
            ready: curl http://localhost:3000 -s -f -o /dev/null && gitpod ports open 3000 --name "Application Preview"
```

### Parallel testing

Run tests across multiple configurations simultaneously.

Example: Services that spin up different database versions for compatibility testing.

```yaml
services:
    pg12:
        name: Postgres 12
        commands:
            start: docker run -d --name pg12 -p 5432:5432 postgres:12
    pg13:
        name: Postgres 13
        commands:
            start: docker run -d --name pg13 -p 5433:5432 postgres:13
tasks:
    test:
        name: Run Tests
        command: |
            npm run test:pg12
            npm run test:pg13
```

These Automations allow testers to quickly access and verify changes in isolated environments.

## Operational Runbooks

Automate operational tasks and provide secure access:

### Troubleshooting environments

Pre-configured environments with necessary tools and access.

Example: A task that installs monitoring tools and sets up VPN access.

```yaml
tasks:
    troubleshoot:
        name: Setup Troubleshooting Env
        triggeredBy: ['manual']
        command: |
            sudo apt-get update && sudo apt-get install -y htop iftop
            ./setup_vpn.sh
```

### Verify log rates

Use a project which creates environments on a runner located so that AWS access is possible.

Example: A task that logs into AWS and verifies log error rates

```yaml
tasks:
    awsSetup:
        name: Setup AWS credentials
        commands: gitpod idp login aws --role arn::some:role
    troubleshoot:
        name: Setup Troubleshooting Env
        triggeredBy: ['postEnvironmentStart']
        dependsOn: ['awsSetup']
        command: |
            aws logs filter-log-events --log-group-name /aws/lambda/my-function --start-time $(date -u -d '1 hour ago' +%s000) --filter-pattern "ERROR"
```

These configurations ensure that operational tasks are performed consistently and securely.

These Automations enhance developer productivity and maintain security standards across all environments.

By centralizing and automating environment configuration, Gitpod enables you to standardize workflows, improve security, and unlock new possibilities across your development lifecycle. The combination of tasks and services allows for complex, multi-step Automations that can be easily shared and version-controlled alongside your codebase.


# Generating Automations
Source: https://www.gitpod.io/docs/gitpod/configuration/automations/generating-automations

Explore Gitpod's automation features: Services and Tasks. Learn how to configure long-running services and execute specific tasks to streamline your development workflow. Understand execution options, dependencies, and best practices for efficient environment management.

Dynamic Automations in Gitpod allow you to create and update environment Automations on the fly, adapting your development environment to changing needs without manually editing configuration files.

## Creating Automations

To create a dynamic automation, use the Gitpod CLI to generate or obtain the automation configuration and pipe it directly into the `gitpod automations update -` command. Notice the `-` at the end which signals that we want to read the Automations from stdin.

> When generating tasks and services, keep in mind that their IDs can only contain alphanumeric characters, underscores, and hyphens, and must be between 1 and 128 characters long.

Basic example:

```bash
echo '{"tasks": {"update_deps": {"name": "Update dependencies", "command": "npm update"}}}' | gitpod automations update -
```

## Example uses

* **Exposing Package Scripts**: Create tasks from scripts in a `package.json` file:

  ```bash
  jq -r '.scripts | to_entries[] | {(.key | gsub("[^a-zA-Z0-9_-]"; "_")): {"name": .key, "command": .value}}' package.json |
  jq -s 'add | {"tasks": .}' |
  gitpod automations update
  ```

  This example uses `gsub` to ensure all task IDs comply with the required format.

* **Dynamic Service Creation**: Create services for components in a specific directory:

  Suppose you have a `components` directory which contains a set of Go components. The following command creates services
  for each of those components.

  ```bash
  find ./components -type d -maxdepth 1 -mindepth 1 |
  jq -R '{(. | gsub("[^a-zA-Z0-9_-]"; "_")): {"name": "Start " + ., "command": "cd " + . + " && go run ."}}' |
  jq -s 'add | {"services": .}' |
  gitpod automations update -
  ```

* **Remote Automation Configuration**: Download and apply Automations from a remote source:

  ```bash
  curl https://example.com/gitpod-automations.json | gitpod automations update -
  ```

  > Only ever download Automations from sources you trust; better yet, verify the integrity of the Automations file before applying it.

  Make sure that the remote configuration file uses compliant task and service IDs.

## Interacting with Dynamic Automations from Outside an Environment

One of Gitpod's most powerful features is the ability to interact with and control Automations from outside the environment itself. This capability, combined with Gitpod's environment management features, transforms Gitpod into a flexible automation and execution platform. You can orchestrate complex workflows and tasks without needing to be actively connected to an environment.

When interacting with Automations from outside an environment, you can perform the same operations as from within an environment:

* **Execute Tasks**: Start, monitor, and manage automation tasks in remote environments.
* **Control Services**: Start, stop, and manage long-running automation services.
* **Access Logs**: Retrieve and monitor logs from tasks and services running in the environment.
* **Update Automations**: Modify automation configurations for environments on the fly.

These operations can all be performed using the Gitpod CLI from your local machine or integrated into your CI/CD pipelines for even greater automation potential.

### Example Workflow: Create, Execute Automation, and Clean Up

Here's a concrete example of how you might use these capabilities along with Gitpod's environment management to create an environment, run an automation task, and then clean up:

```bash
# 1. Create a new environment (find an environment class using \"gitpod environment list-classes\")
ENV_ID=$(gitpod environment create https://github.com/your-repo/your-project --dont-wait --class-id some-env-class-id)

# 2. Start a specific automation task in the environment
TASK_ID=$(gitpod automations task start build-and-test --environment-id $ENV_ID)

# 3. Wait for the automation task to complete
gitpod automations task logs $TASK_ID --environment-id $ENV_ID

# 4. Check the automation task status
TASK_STATUS=$(gitpod automations task get $TASK_ID --environment-id $ENV_ID -o json | jq -r .status)

# 5. Clean up the environment
if [ "$TASK_STATUS" = "succeeded" ]; then
    echo "Automation task completed successfully. Cleaning up environment."
    gitpod environment delete $ENV_ID
else
    echo "Automation task failed. Environment left running for inspection."
fi
```

This script demonstrates how you can:

1. Create a new environment based on a Git repository.
2. Start a specific automation task (in this case, 'build-and-test') in that environment.
3. Stream the logs of the automation task to monitor its progress.
4. Check the final status of the automation task.
5. Based on the task's outcome, either clean up the environment or leave it running for further investigation.

### Benefits of External Automation Control

1. **CI/CD Integration**: Easily integrate Gitpod Automations into your existing CI/CD pipelines.
2. **Batch Processing**: Set up and run multiple automation tasks across different environments in parallel for large-scale operations.
3. **Automated Testing**: Create ephemeral environments for running automated test suites without manual intervention.
4. **Resource Optimization**: Run Automations in environments only when needed and automatically clean them up after use.

By leveraging these external automation capabilities alongside Gitpod's environment management features, you can create powerful, flexible workflows. This enables you to automate complex development and testing processes with ease, all while maintaining full control from outside the environment.


# Overview
Source: https://www.gitpod.io/docs/gitpod/configuration/automations/overview

Explore Gitpod's automation features: Services and Tasks. Learn how to configure long-running services and execute specific tasks to streamline your development workflow. Understand execution options, dependencies, and best practices for efficient environment management.

Through [Dev Container](/flex/configuration/devcontainer) you specify your environment basics like base image and editor plugins. Automations go beyond Dev Container to provide **a powerful way to define, automate and share common tasks** you perform with your development environment, such as seeding databases or provisioning external infrastructure.

<Frame caption="Environment details with Automations">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/environment-details.png" />
</Frame>

Using Automations you can automate:

* **Setup** - Seed a database, provision infra or authenticate with a cloud account
* **Operations** - Turn your runbooks into one-click self-service actions
* **Editor interfaces** - Start up a server such as Jupyter notebook
* **Enforce policies** - Run security or scanning tools
* **AI workflows** - Configure AI agents or code assistants

See [examples](/flex/configuration/automations/examples) for more.

Automations are defined in configuration YAML files that can live alongside your source code, in another repo, or any location accessible from the development environment.

* [Automations](#automations)
  * [The two modes of Automations](#the-two-modes-of-automations)
  * [Services](#services)
    * [Service Configuration](#service-configuration)
  * [Tasks](#tasks)
  * [Triggers](#triggers)
    * [Available Triggers](#available-triggers)
    * [Runners vs. Gitpod Desktop behaviors](#runners-vs-gitpod-desktop-behaviors)
    * [Dependencies](#dependencies)
    * [Best Practices for Using Triggers](#best-practices-for-using-triggers)
  * [Reference](#reference)

## The two modes of Automations

Gitpod supports two primary types of Automations:

1. **[services](#services)** - for long-running processes like starting a server
2. **[tasks](#tasks)** - for performing one-off actions like executing unit tests

```yaml
services:
    database:
        name: PostgreSQL
        commands:
            start: docker run postgres
tasks:
    run-unit-tests:
        name: Runs unit tests
        command: go test -v ./...
```

**Caption:** A minimal automation definition.

## Services

Services are **designed for long-running processes**. These are typically components that need to be continuously available throughout your development session.

Common examples include:

* Databases like PostgreSQL
* Caching systems such as Redis
* Your project's backend and frontend servers.

The key characteristic of a service is its persistent nature – it's not expected to terminate on its own but to remain active and ready for interaction as long as your development environment is running.

See [reference](#reference) for a full example.

### Service Configuration

Configuring a service involves defining up to three key commands:

* `start` (required) - The service itself. The process is expected to continue running until stopped. If this command fails (i.e. exits with a non-zero exit code), the service is considered failed.

* `ready` (optional) - Acts as a health check, determining when the service is fully operational and available for use. Gitpod executes this command periodically (once per second) until it exits with a status code of 0, indicating the service is ready. If you don't specify a `ready` command, Gitpod assumes the service is immediately available after the `start` command completes.

* `stop` (optional) - Defines a graceful shutdown procedure for your service. If omitted, Gitpod will send a `SIGTERM` signal to terminate the service when needed.

## Tasks

In contrast to services, **tasks are individual commands designed to perform specific, often one-off actions within your environment**.

Common examples include:

* Compiling code
* Executing test suites
* Populating a database with test data
* Authenticating with cloud services
* Resetting your local environment to a known state.

Tasks are typically short-lived, executing a defined set of operations and then terminating once complete. Tasks consist of a single command to be executed, however their power lies in their ability to be chained and dependent on other components of your environment.

Tasks will exit immediately if a command exits with a non-zero status code, and the task will be marked as failed. This behavior allows for proper error handling in automation pipelines and dependency chains. For example, if a task depends on another task that fails (exits with non-zero status), the dependent task will not be executed.

See [reference](#reference) for a full example.

### Stop a Task

A started task can be stopped prematurely, which will send a `SIGTERM` signal to the task's command (or any chained commands). Once the command has exited, the task will be marked as stopped.
If the command does not exit within 10 seconds, it will be forcefully terminated and the task run will be marked as failed.

## Triggers

Triggers are **the events that initiate the execution of Automations in your Gitpod environment**. This section covers the available triggers and explains their behavior.

### Available Triggers

Gitpod supports three main types of triggers for Automations:

* The `postEnvironmentStart` trigger activates every time the environment is started. This includes both the initial start of the environment and any subsequent restarts. It's particularly useful for operations that need to be performed consistently on every environment start, regardless of the underlying container state. For example, you might use this trigger to set up environment variables or check for updates to critical tools.

* The `postDevcontainerStart` trigger, on the other hand, is activated every time the devcontainer is started. This occurs during the first start of the environment and any subsequent devcontainer restarts, such as after a rebuild. This trigger is ideal for setup tasks that are specific to the devcontainer configuration, like initializing databases or compiling project-specific dependencies.

* The `manual` trigger provides a unique affordance in the user interface, allowing developers to start an action on demand. This trigger is particularly valuable for curating a set of actions that developers frequently perform. By using manual triggers, you can shape and refine the experience others will have in your Gitpod environment. For instance, you might create manual triggers for running tests, generating documentation, or deploying to a staging environment. This approach not only streamlines common tasks but also helps standardize processes across your team.

See [reference](#reference) for a full example.

### Runners vs. Gitpod Desktop behaviors

It's important to note that the behavior of these triggers can vary depending on the Gitpod runner being used. The AWS runner typically uses a suspend/resume model for environment management. When an environment is restarted on EC2, it usually resumes from a suspended state. In this scenario, `postDevcontainerStart` is not called on restart, but `postEnvironmentStart` is still triggered.

Gitpod Desktop takes a different approach. Instead of using suspend/resume, it reboots the entire environment on restart. This causes both `postDevcontainerStart` and `postEnvironmentStart` to run on every environment restart.

This intentional difference in behavior is designed to help recreate state that might be lost due to the lifecycle of individual elements in different environments. For AWS runners, the suspended state preserves most of the environment, so fewer reinitializations are needed. For Gitpod Desktop, the full reboot ensures a clean state each time, which may require more extensive reinitialization.

### Dependencies

Tasks can specify dependencies, allowing you to create sophisticated automation workflows. A task can depend on other tasks, ensuring that these dependencies are executed beforehand. This feature is particularly useful for setting up complex environments where certain operations must occur in a specific order.

It's important to note that task dependencies are re-evaluated and re-executed each time the main task runs. This ensures that your environment is always in the expected state before a task begins, even if it's run multiple times during a development session.

Each task execution is treated as an isolated event. This means that if you modify a task's definition while it's running, those changes won't affect the current execution. This isolation ensures consistency and predictability in your automation workflows.

### Best Practices for Using Triggers

When working with triggers, it's advisable to use `postEnvironmentStart` for tasks that should run on every start, regardless of the runner or whether it's a fresh start or a resume.

Use `postDevcontainerStart` for tasks specifically related to devcontainer setup or for operations that need to run after a full environment reboot. This could involve compiling dependencies or initializing databases.

The `manual` trigger is best used for discretionary tasks that developers might need to perform multiple times during a session, or for complex operations that don't need to run automatically. By thoughtfully implementing manual triggers, you can significantly improve the usability of your Gitpod environment for all team members.

## Reference

Automations are defined as YAML, in a [file](/flex/configuration/automations/basic-configuration) or [directly uploaded to the system](/flex/configuration/automations/generating-automations).

```yaml
# defines automation services (optional)
services:
    # serviceReference is an identifier for the service within the environment.
    # It is used when referencing the service, e.g. from the CLI.
    # It needs to only contain alphanumeric characters, underscores, and hyphens, and must be between 1 and 128 characters long.
    serviceReference:
        # Name is a required, human readable string.
        name: Human readable name
        description: Optional description providing more detail
        # triggeredBy lists all trigger that start the service. If none are provided the service isn't started automatically.
        # See below for a complete list of trigger.
        triggeredBy:
            - ...
        commands:
            # start is a mandatory command constitutes the service itself and is expected to continue running until stopped.
            # If this command fails (i.e. exits with a non-zero exit code), the service is considered failed.
            start: your-service-command
            # ready acts as a readiness check, determining when the service is fully operational and available for use.
            # Gitpod executes this command periodically (once per second) until it exits with a status code of 0, indicating the service is ready. # If you don't specify a ready command, Gitpod assumes the service is immediately available after the start command completes.
            ready: your-service-command --is-running
            # This optional command allows you to define a graceful shutdown procedure for your service.
            # If omitted, Gitpod will send a SIGTERM signal to terminate the service when needed.
            stop: killall your-service-command

# defines automation tasks (optional)
tasks:
    taskReference:
        # Name is a required, human readable string.
        name: Human readable name
        description: Optional description providing more detail
        # triggeredBy lists all trigger that start the service. If none are provided the service isn't started automatically.
        # See below for a complete list of trigger.
        triggeredBy:
            # postEnvironmentStart activates every time the environment is started, e.g. on first start
            - postEnvironmentStart
            # postDevcontainerStart activates every time the devcontainer is started, e.g. on first start or devcontainer rebuild
            - postDevcontainerStart
            # manual trigger provides a unique affordance in the user interface, allowing developers to start an action on demand.
            - manual
        # dependsOn expresses a dependency on another task which ensures that this other task runs before this one.
        dependsOn:
            - someOtherTask
        # command is the actual task command that gets executed. Gitpod will run this as a shell script, i.e. multiline input is possible
        command: |
            echo We are in the workspace directory: $PWD
            echo Let's go
```


# Getting started
Source: https://www.gitpod.io/docs/gitpod/configuration/devcontainer/getting-started

Explore Gitpod's Dev Container features. Learn about the benefits of using Dev Containers, how to create a devcontainer.json file, and how to use Gitpod's Dev Container support.

<Note>
  {' '}

  If you're configuring your Dev Container in **VS Code** also check out the [VS
  Code documentation](/flex/editors/vscode). Particularly for extra information
  on rebuilding your container, recovery mode and accessing logs.
</Note>

When you first create a development environment in Gitpod, it looks for a [devcontainer.json](https://containers.dev/implementors/spec/#devcontainerjson) file in your repository. This file acts as a blueprint for setting up a consistent, standardized environment for your project.

If you haven't created a devcontainer.json file yet and start an environment in Gitpod, your environment will automatically have a Dev Container created in the environment. This initial configuration should form a good basis for iterating further.

When refining your environment, you'll need to choose between two main scenarios for your Dev Container:

* **Single Container Setup**: This simplest scenario runs everything you need inside a single container. It's ideal for most projects where one environment can handle your entire development stack—for instance, a Node.js application with all dependencies and tools in one container.

* **Multi-Container Setup with Docker Compose**: For more complex projects involving multiple services—such as a web application with a separate database—Docker Compose allows you to define and orchestrate multiple containers. Each service operates in its own container, yet they function together as a unified environment.

## Starting with a custom Dockerfile

If you’re using a single container and already have a Dockerfile, you can base your Dev Container configuration on it. Here’s how you might set it up:

```json
{
	"name": "Node.js Dev Container",
	"build": {
		"context": "..",
		"dockerfile": "../Dockerfile"
	},
	"customizations": {
		"vscode": {
			"settings": {},
			"extensions": ["dbaeumer.vscode-eslint"]
		}
	},
	"remoteUser": "node"
}
```

* **build:** Builds the container from the Dockerfile in the parent directory.

* **vscode:** Installs the ESLint extension for JavaScript linting in VS Code.

* **remoteUser:** Specifies the user inside the container (set to **node**).

**.gitpod/automations.yaml:** For installing dependencies, use [automations](../automations):

```yaml
tasks:
    install-dependencies:
        name: Install dependencies
        command: npm install
        triggeredBy:
            - postDevcontainerStart
            - manual
```

## Starting with a Docker Compose

In this example, we set up a multi-container environment using Docker Compose. This setup includes two containers: one for the application (service container) and another for the PostgreSQL database.

> Beware that devcontainer's interaction with docker compose can quickly lead to broken environments, due to unforeseen interactions between your devcontainer and Docker services.

**devcontainer.json:** This file defines the development container configuration and ties it to the Docker Compose setup.

```json
{
	"name": "Node.js + PostgreSQL Dev Container",
	"dockerComposeFile": "../docker-compose.yml",
	"service": "app",
	"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
	"customizations": {
		"vscode": {
			"extensions": [
				"dbaeumer.vscode-eslint",
				"ms-azuretools.vscode-docker"
			]
		}
	},
	"remoteUser": "node"
}
```

* **dockerComposeFile:** Points to the Docker Compose file that defines the services.

* **service:** Specifies the main development container (**app**).

* **workspaceFolder:** Defines the working directory inside the container.

* **vscode:** Installs the necessary VS Code extensions.

* **remoteUser:** Specifies the user inside the container (set to node).

**.gitpod/automations.yaml:** For installing dependencies, use [automations](../automations):

```yaml
tasks:
    install-dependencies:
        name: Install dependencies
        command: npm install
        triggeredBy:
            - postDevcontainerStart
            - manual
```

**docker-compose.yml:** This file configures the multi-container setup, defining both the **app** and **db** services.

```yml
version: '3.8'
name: node-postgres-app
services:
    app:
        build:
            context: .
        dockerfile: Dockerfile
        volumes:
            - '..:/workspaces:cached'
        command: sleep infinity
        network_mode: 'service:db'
    db:
        image: 'postgres:latest'
        restart: unless-stopped
        volumes:
            - 'postgres-data:/var/lib/postgresql/data'
        environment:
            POSTGRES_USER: postgres
            POSTGRES_DB: postgres
            POSTGRES_PASSWORD: postgres
volumes:
    postgres-data: null
```

* **name:** Sets the name to ensure containers are properly identified under a specific project name.

* **app service:** This container is used for development. It builds from a Dockerfile and mounts the project directory as a volume. The command is overridden to keep the container alive (**sleep infinity**), and it shares the network stack with the **db** service (**network\_mode: service:db**), which simplifies access to the database.

* **db service:** This container runs PostgreSQL and is configured with environment variables for the user, password, and database name. The database data is persisted using a Docker named volume (**postgres-data**).

## Iterating and Rebuilding

After modifying the devcontainer.json file, you must rebuild your container to apply the changes. You can initiate a rebuild from VS Code using the **Gitpod Flex: Rebuild Container** command. During this process, Gitpod will disconnect your session, then automatically reconnect you once the rebuild is complete.

You can also rebuild your environment from the terminal using the Gitpod CLI. For instance, to trigger a rebuild from your environment, use:

```sh
gitpod environment devcontainer rebuild
```

### Recovery mode

If an errors occur when the devcontainer is started during a rebuild, Gitpod enters **recovery mode**. This allows you to examine environment logs (use the **Gitpod Flex: Show Environment Logs** command in VS Code), adjust the devcontainer.json file to resolve issues, and attempt the rebuild again.

## Environment Isolation Considerations

The Dev Container runs in an isolated Linux VM. Although the VM is part of the environment, the content and structure of the host is not customizable and may change at any time. Relying on the structure or contents of the underlying host impacts the portability and stability of your devcontainer configuration. It's crucial to respect this isolation to maintain portable and reliable Dev Container configurations:

* Use **initializeCommand** by avoiding adding dependencies to the VM.

* Opt for named volumes instead of bind mounts, as Docker controls them.

* Consider that "**localEnv**" in parameter expansion refers to the host VM, not your local machine, even when you are running locally.

### Host Network Stack

By default, the dev container network is isolated from the VM. However, you can configure the devcontainer to use the host's network stack, which is necessary for [port sharing](/flex/integrations/ports).

* For a single container, add `--network=host` in the `.devcontainer.json` file:
  ```json
  "runArgs": ["--network=host"]
  ```
* For multiple containers, use `network_mode: host` in the `docker-compose.yml` file:
  ```yml
  network_mode: host
  ```

## Using Private Container Images

<Warning>
  {' '}

  Currently, basic authentication (username/password) is supported for most registry types. AWS ECR is also supported only when using AWS EC2 runners.
</Warning>

If your Dev Container configuration uses private container images with basic authentication, you'll need to configure authentication credentials in your project's secrets:

1. Go to your Project Settings > Secrets
2. Create a new Container Registry secret with the appropriate registry URL and credentials. For detailed instructions, see the [Secrets documentation](/flex/secrets#types-of-secrets).
3. The environment will automatically authenticate with the registry using the credentials you provided.

<Note>
  {' '}

  If your workflow requires pulling additional private images from within your environment, your Dev Container image should include Docker CLI for most private registries, or Docker CLI. Without these tools, you may see a warning in your environment creation dashboard and won't be able to access the private registry from inside your environment.
  For AWS ECR registries, we don't automatically log you into the registry from the environment. You'll need to authenticate as part of your workflows using either [AWS native authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html) setup or [Gitpod OIDC](/gitpod/configuration/oidc).
</Note>

## References

* Refer to [containers.dev/implementors/json\_reference/](https://containers.dev/implementors/json_reference/) for the reference documentation of devcontainer.json format. This resource provides detailed information about attributes, lifecycle hooks, and other essential aspects of Dev Containers.

* For a comprehensive list of pre-built development container images that can be used as a starting point for your projects, visit [github.com/devcontainers/images](https://github.com/devcontainers/images). These images are maintained by the Dev Containers project and are designed to work well with VS Code and other Dev Container-compatible tools.

* While Gitpod doesn't allow opening a Dev Container using [the Dev Containers](marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension in VS Code, it leverages its editing experience and customizations. You can find more information about this, as well as generally applicable advice, at [code.visualstudio.com/devcontainers/containers](https://code.visualstudio.com/devcontainers/containers). Be aware that not everything is applicable given the isolated nature of Gitpod environments. For general best practices on working with Dev Containers, visit [containers.dev/guides](https://containers.dev/guides).


# Optimizing your Environment
Source: https://www.gitpod.io/docs/gitpod/configuration/devcontainer/optimizing-startup-times

Learn how to optimize your development environment for Gitpod. Discover tips and best practices for improving the startup time of your environment.

There are several ways to optimize the startup of your environment:

* **Place stable dependencies in the Dockerfile**: For tools that rarely change (e.g., build tools, system dependencies), include them directly in the custom Dockerfile.

* **Use prebuilt Docker images**: Build your image, and push it to a container registry. Reference this image in your devcontainer.json file to avoid rebuilding from scratch each time.

* **Enable dev container image cache**: For AWS runners, the [dev container image cache](/gitpod/runners/aws/devcontainer-image-cache) automatically caches built devcontainer images, significantly reducing startup times for environments with identical configurations.

* **Use [automations](../automations) for dynamic dependencies**: For frequently changing tools and dependencies, such as npm modules, use Automations to handle installations during the environment's startup process.

Gitpod environments may take some time to start initially, but they're quick to stop and restart after setup, and they automatically stop when disconnected. Here's how you can leverage these to speed up your workflows:

* **Reuse environments:** Accelerate recurring tasks by reusing environments. For instance, eliminate the need to repeatedly repopulate databases or download dependencies.

* **Use multiple environments:** Organize your work by maintaining separate environments for different tasks, such as code reviews and feature development for. This enables faster context switching within the same repository.


# Overview
Source: https://www.gitpod.io/docs/gitpod/configuration/devcontainer/overview



Gitpod fully supports [Development Containers](https://containers.dev/), allowing you to standardize development environments across your team. Define your setup in a `devcontainer.json` file to ensure consistent tools, dependencies, and configurations for all developers.

## Benefits

Using Dev Containers with Gitpod provides several advantages:

* **Standardized environments** across all team members
* **Consistent tooling** with precisely defined dependency versions
* **Isolated Linux VM environments**, even when running locally
* **Support for both single and multi-container** development setups
* **Version-controlled configuration** that lives with your codebase
* **Integration with VS Code** and other supported editors
* **Separation** of development environment from local machine configuration

## Configuration

### File Location

Place your `devcontainer.json` file in one of these standard locations:

* `.devcontainer/devcontainer.json`
* `.devcontainer.json`

### Basic Configuration Example

```json
{
	"name": "My Project",
	"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
	"features": {
		"ghcr.io/devcontainers/features/node:1": {
			"version": "lts"
		}
	},
	"customizations": {
		"vscode": {
			"extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
			"settings": {
				"editor.formatOnSave": true
			}
		}
	},
	"forwardPorts": [3000, 8080]
}
```

This configuration:

* Uses a base Ubuntu image
* Adds Node.js LTS
* Includes ESLint and Prettier VS Code extensions
* Configures auto-formatting on save
* Forwards ports 3000 and 8080

## Multiple Dev Container Configurations

You can manage multiple Dev Container configurations using Gitpod's project feature. This allows you to define different environments for:

* Different branches or repositories
* Various development scenarios
* Specialized tasks requiring specific tools

## Migration from .gitpod.yml

If you're already using a `.gitpod.yml` file, Gitpod provides tools to convert your existing configuration to the Dev Container format. See our [migration guide](/flex/configuration/migrate-from-classic) for step-by-step instructions. Dev Containers offer a more standardized approach that works across multiple platforms and tools.

## Known Limitations

When using Dev Containers with Gitpod, be aware of these limitations:

* Platform-specific features may not work with Gitpod Desktop
* Conflicting features can cause build failures (Gitpod will display an error message)
* Some Dev Container commands might behave differently in Gitpod's environment
* When build errors occur, recovery mode is engaged, requiring manual intervention

## Recommended Images

Microsoft provides well-maintained Dev Container base images for popular development stacks:

* `mcr.microsoft.com/devcontainers/base:ubuntu` - Ubuntu base image
* `mcr.microsoft.com/devcontainers/javascript-node` - Node.js development
* `mcr.microsoft.com/devcontainers/python` - Python development
* `mcr.microsoft.com/devcontainers/dotnet` - .NET development
* `mcr.microsoft.com/devcontainers/java` - Java development
* `mcr.microsoft.com/devcontainers/go` - Go development

## Advanced Configuration

### Multi-Container Development

For more complex setups, you can define multiple containers using Docker Compose:

```json
{
	"name": "Multi-container App",
	"dockerComposeFile": "docker-compose.yml",
	"service": "app",
	"workspaceFolder": "/workspace",
	"customizations": {
		"vscode": {
			"extensions": ["ms-azuretools.vscode-docker"]
		}
	}
}
```

### Adding Custom Features

[Dev Container Features](https://containers.dev/features) are self-contained, shareable units of installation code and configuration that let you quickly add tooling, runtimes, or libraries to your development container.

You can add features to your Dev Container by adding them to the `features` section of your `devcontainer.json` file:

```json
{
	"features": {
		"ghcr.io/devcontainers/features/docker-in-docker:2": {},
		"ghcr.io/devcontainers/features/github-cli:1": {}
	}
}
```

Gitpod works well with many Dev Container Features, especially official ones that are designed with remote development environments in mind. Linux-based runners generally provide best compatibility with most Dev Container Features. Here's what you should know:

* Community-supported features might require additional testing, as they may have been developed without specific consideration for compatibility.
* When using the Gitpod Desktop's Mac runner, some features might not work right away with the Rosetta virtualization layer. [See troubleshooting section](#troubleshooting)
* Feature behavior can vary depending on base images, other installed features, and specific configurations in your setup.

## Troubleshooting

If your Dev Container fails to build:

1. Check the Gitpod console for specific error messages
2. Verify that all specified features are compatible

   <Expandable title="features that require extra work on Gitpod Desktop's Mac runner">
     * ghcr.io/devcontainers/features/docker-in-docker:2

       Disabling `moby` can be required to build this features. Alternatively, you can provide Docker CE through the image of your dev container. [Learn more](https://github.com/devcontainers/features/tree/main/src/docker-in-docker#limitations)

     * ghcr.io/devcontainers/features/docker-outside-of-docker:1

       Disabling `moby` can be required to build this features. Alternatively, you can provide Docker CE through the image of your dev container. [Learn more](https://github.com/devcontainers/features/tree/main/src/docker-outside-of-docker#limitations)

     * ghcr.io/devcontainers/features/kubectl-helm-minikube:1

     * ghcr.io/devcontainers/features/nix:1

     * ghcr.io/devcontainers/features/oryx:1

     * ghcr.io/devcontainers/features/terraform:1

     * ghcr.io/devcontainers-contrib/features/yamllint:2

       The installation fails due to platform mismatch. It's possible to set `platform=linux/arm64` to build this feature, but the recommendation would be to install `yamllint` in you custom container image.
   </Expandable>
3. Ensure image versions are correctly specified
4. Try rebuilding in recovery mode to debug the issue

## Next Steps

* Explore the full [Dev Container specification](https://containers.dev/implementors/spec/) for advanced configurations
* Check out the [Dev Container Feature catalog](https://containers.dev/features) for additional tools and utilities
* Learn about [Gitpod projects](/flex/projects) to manage multiple environments


# Dotfiles
Source: https://www.gitpod.io/docs/gitpod/configuration/dotfiles/overview

Dotfiles are a way to customize your developer environment according to your personal needs.

Dotfiles are a way to customize your developer environment according to your personal needs. This guide explains how to configure and troubleshoot dotfiles in Gitpod.

## What are dotfiles?

Dotfiles are configuration files that customize your shell, editor, and other applications. They're called "dotfiles" because they typically begin with a dot (`.`) in Unix-like systems. Common examples include `.zshrc`, `.vimrc`, and `.gitconfig`.

## Why use dotfiles with Gitpod?

Gitpod standardizes developer environments to ensure consistency across your team - every colleague gets the same environment configuration when they start a new environment. This is great as it means you have everything you need to start coding on a project. However, because it's shared by all colleagues you might be missing some of the customizations you're used to when working locally on your own machine.

This is where dotfiles come in. They allow you to customize your standardized Gitpod environment according to your personal needs and preferences, making you feel right at home while still maintaining the benefits of a consistent base environment. When you configure dotfiles with Gitpod, your personal customizations are automatically applied every time you start a new environment, regardless of the repository you're working on.

## Setting up your dotfiles repository

To configure Gitpod to use your dotfiles for all your environments:

1. Create a Git repository with your dotfiles. If you're unfamiliar with dotfiles, check out [GitHub's dotfiles guide](https://dotfiles.github.io) or [awesome-dotfiles](https://github.com/webpro/awesome-dotfiles) for inspiration and examples.
2. Navigate to [Settings > Preferences][dotfiles-preferences]
3. Enter the URL of your dotfiles repository

When you start a new environment, Gitpod will:

1. Clone your dotfiles repository to `~/dotfiles`
2. Execute the first of the following files:
   * `install.sh` or `install`
   * `bootstrap.sh` or `bootstrap`
   * `setup.sh` or `setup`

## Best practices for dotfiles in Gitpod

For the best experience with dotfiles in Gitpod:

* Keep your install script lightweight to minimize environment startup time. Smaller repositories and simpler scripts lead to faster environment creation.
* Ensure your install script runs without requiring user interaction, otherwise the environment creation will hang (see troubleshooting section for more details).
* Don't store secrets in your dotfiles repository. Use Gitpod's [secret feature](https://app.gitpod.io/settings/secrets) instead for sensitive information.
* Remember that you're limited to one dotfiles repository per user.

## Managing changes to your dotfiles

When you make changes to your dotfiles repository:

* Changes will be automatically applied when creating new environments
* Existing running environments won't automatically pick up the changes
* To apply changes to an existing environment, you'll need to manually `git pull` and re-run your installation script, e.g. `(cd ~/dotfiles && git pull && ./bootstrap.sh)`

If you're actively iterating on your dotfiles, then the following workflow can be helpful:

* Create a new environment from your dotfiles repository
* Make changes to your files and run your install script to validate the changes
* If you need to reset the environment, e.g. if you're iterating on something that changes the state of the environment such as installing tools, then you can run `gitpod environment devcontainer rebuild` to remove any manual modifications you've made.

## Troubleshooting

### My dotfiles failed to install

Dotfiles are installed during dev container creation. If your dotfiles failed to apply, check the environment logs section "Creating dev container" for any errors or messages that can help you debug the issue.

### Failed to clone

If it failed to clone your dotfiles, you should see an error message like the one below:

```
fatal: repository 'https://github.com/mads-hartmann/gitpod-dotfiles-does-not-exist/' not found
```

Please validate that the repository URL you have configured points to an existing repository.

### Failed to install

If it manged to clone your dotfiles, but failed while running your install script, then you likely won't see much information in the logs. Instead you can try to reproduce the error by manually running the install script

```sh
cd ~/dotfiles
# Replace install.sh with the install script you have in your dotfiles repository
./install.sh
```

If you're seeing failures in some repositories but not other it could be because your dotfiles have system dependencies that are not covered in the dev container configuration of the repository. In that case, you can make your dotfiles self-contained by having them check for the existence of the dependencies and install them if they're missing.

Here's an example where [fzf](https://github.com/junegunn/fzf) is installed only if it doesn't exist already:

```sh
FZF_VERSION="0.60.3"
if ! command -v fzf >/dev/null 2>&1; then
    echo "Installing fzf..."
    curl -L https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_amd64.tar.gz | tar xzvf -
    sudo mv fzf /usr/local/bin
    echo "fzf installation completed"
else
    echo "fzf is already installed"
fi
echo "Configuring fzf..."
echo "source <(fzf --zsh)" >> $HOME/.zshrc
```

### My dotfiles cause the environment to hang during startup

Your install script is executed in a non-interactive shell without a TTY. This means that commands which require user interaction or expect an interactive terminal can cause the dev container creation to hang.

Make sure your install script can run non-interactively without requiring terminal input. You may need to modify commands that assume an interactive terminal is available, like `read` prompts or interactive installers.

The easiest way to resolve this is to:

1. Remove your Dotfiles repository from [Settings > Preferences](https://app.gitpod.io/settings/preferences)
2. Start a fresh environment
3. Manually clone your Dotfiles repository and run your install script to see where it's getting stuck
4. Resolve the issues, commit and push your changes to your Dotfiles repository
5. Re-add your Dotfiles repository URL in [Settings > Preferences](https://app.gitpod.io/settings/preferences)
6. Start a new environment to see if the issue is resolved

## FAQs

### How do I configure the default shell?

You can use the `chsh` command to change the login shell for your user by adding the following to your dotfiles install script. The example below sets the default shell to `zsh` for the active user.

```sh
sudo chsh "$(id -un)" --shell "/usr/bin/zsh"
```

The `chsh` command modifies the user's login shell in `/etc/passwd` which persists across sessions since `/etc/passwd` defines the default shell.

[dotfiles-preferences]: https://app.gitpod.io/settings/preferences


# Migrate from Gitpod Classic to Gitpod
Source: https://www.gitpod.io/docs/gitpod/configuration/migrate-from-classic



Gitpod uses [Dev Containers](/flex/configuration/devcontainer) and [Automations](/flex/configuration/automations) as its core configuration elements. Migration involves converting your `.gitpod.yml` into a `devcontainer.json` and `automations.yml` setup.

## Migrate the configuration

Create a new Gitpod environment for your existing repository and run the migration command:

```sh
gitpod env migrate
```

This command generates two key files:

* `.devcontainer/devcontainer.json`: Defines your development environment by setting the workspace folder, image, user, and other settings, aligned with Gitpod Classic experience.
* `.gitpod/automations.yml`: Contains tasks extracted from `.gitpod.yml`, maintaining their dependency order.

## Test the configuration

1. Deploy the `automations.yml` file using the following command:

   ```sh
   gitpod automations update .gitpod/automations.yml
   ```

2. Use the following command to rebuild your workspace with the new devcontainer.json:

   ```sh
   gitpod environment devcontainer rebuild
   ```

3. The default workspace folder in Dev Container differs from Gitpod Classic (`/workspaces` vs `/workspace`). VS Code may not open the correct folder automatically after rebuilding. To fix this:

   * Use the "Open File" option in VS Code to select the `/workspace/<project>` folder.

## Customize the configuration

While `gitpod env migrate` creates these baseline files, you need to make manual adjustments to match your requirements.
Note, for instance, that the default Dev Container image differs from the Gitpod Classic workspace image. You'll need to create a custom image for a more optimized environment.

Refer to the following resources to learn more about the configuration options:

* [Dev Containers](/flex/configuration/devcontainer)
* [Automations](/flex/configuration/automations)


# Multi-Repository Environments
Source: https://www.gitpod.io/docs/gitpod/configuration/multi-repository

Learn how to work with multiple repositories in a single Gitpod environment

Gitpod supports working with multiple repositories in a single environment, enabling you to work on projects that span across different repositories. This guide explains how to set up multi-repository environments using either Dev Container configuration or Gitpod Automations.

## Using Dev Container Configuration

The Dev Container `onCreateCommand` allows you to clone additional repositories when your environment starts. This method is particularly useful when you want to maintain the repository setup as part of your Dev Container configuration.

Add an `onCreateCommand` entry to your `.devcontainer/devcontainer.json` file:

```json
{
  "name": "One extra repository",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "onCreateCommand": "git clone https://github.com/organization/second-repo.git"
}
```

For multiple repositories:

```json
{
  "name": "Multiple repositories",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "onCreateCommand": "git clone https://github.com/organization/second-repo.git && git clone https://github.com/organization/third-repo.git"
}
```

## Using Gitpod Automations

Alternatively, you can use Gitpod's [Automations](/flex/configuration/automations/overview) to clone additional repositories. This approach offers more flexibility and can be combined with other automation tasks.

Add a task to your `automations.yaml` file:

```yaml
tasks:
    build:
        name: Clone additional repositories
        command: |
            git clone https://github.com/organization/second-repo.git
            git clone https://github.com/organization/third-repo.git
        triggeredBy: ['postDevcontainerStart']
```

## Best Practices

When working with multiple repositories, consider the following best practices:

* Use SSH keys or personal access tokens for authentication with private repositories
* Organize repositories in a consistent directory structure
* Configure Git identity globally to ensure consistent commits across repositories

## Troubleshooting

Common issues you might encounter:

* **Authentication failures**: Ensure you have the correct permissions and authentication method
* **Path issues**: Use absolute paths when necessary
* **Repository not found**: Verify repository URLs and access permissions

## Working with Multiple Repositories

Once your environment is set up:

1. Navigate between repositories using the file explorer or terminal
2. Make changes in each repository independently
3. Commit and push changes to each repository separately

Example workflow:

```bash
cd ~/workspace/second-repo
# Make changes
git add .
git commit -m "Update feature X"
git push

cd ~/workspace/third-repo
# Make changes
git add .
git commit -m "Fix bug Y"
git push
```


# OpenID Connect (OIDC)
Source: https://www.gitpod.io/docs/gitpod/configuration/oidc

Guide to using OpenID Connect (OIDC) in Gitpod

You can use OIDC authentication to connect Gitpod environments to cloud providers or third parties such as AWS, Azure, GCP, or secret management services like Vault. OIDC integration eliminates the need to manually distribute access credentials, secrets, and other key material via environment variables or other methods.

## What is OIDC?

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol, which allows clients to verify identity.

OIDC leverages a JWT (JSON Web Token) that contains claims about the caller. Claims are statements that can include information such as name, email address, or repository metadata.

OIDC provides a reliable way to establish a user's identity, including authentication and basic profile information. It gives third-party applications a standardized, secure, and scalable method to authenticate and authorize users. When used with Gitpod, it helps automate secure access to third-party services that your environments might need to interact with.

## Setting up OIDC Authentication with a third party

Setting up OIDC Authentication generally involves three main steps:

1. **Establish Trust**: Register Gitpod with your OIDC-supported third party (like AWS, Google, etc.). This third party becomes the audience in your JWT token generated in Gitpod.

2. **Setup Trust Rules**: Configure what the JWT claims must contain to be exchanged for a valid auth token. Here you can implement fine-grained access controls.

3. **Exchange the JWT token**: Once trust and trust rules are established, use the JWT tokens generated by the `gitpod idp token` command to authenticate with the third party.

## Provider specific guides

* [AWS](/flex/integrations/aws)

**Read more:**

* [\[Auth0 docs\] OpenID Connect Protocol](https://auth0.com/authenticate/protocols/openid-connect-protocol)

## Gitpod CLI integration

You can retrieve a JWT token for OIDC using `gitpod idp`. To retrieve the OIDC token for the current environment, run `gitpod idp token`.

For example, to request a new OIDC JWT for example.org, execute:

```bash
$ gitpod idp token --audience example.org
eyJhbGciOiJSUzI1NiIsImtpZCI6ImlkLTE2ODQ3NTc4MDY...
```

To decode the output, use the `--decode` flag:

```bash
$ gitpod idp token --audience example.org --decode
```

Once decoded, the result will resemble this JSON object:

```json
{
	"Claims": {
		"aud": "example.org",
		"exp": 1740517845,
		"iat": 1740514245,
		"iss": "https://app.gitpod.io",
		"org": "0191e223-1c3c-7607-badf-303c98b52d2f",
		"sub": "org:0191e223-1c3c-7607-badf-303c98b52d2f/prj:019527e4-75d5-704d-a5a4-a2b52cf56198/env:019527e4-75d5-704d-a5a4-a2b52cf56196"
	},
	"Header": [
		{
			"KeyID": "k0",
			"JSONWebKey": null,
			"Algorithm": "RS256",
			"Nonce": "",
			"ExtraHeaders": null
		}
	]
}
```

## Access Control Examples

### Granting access to anyone in the organization

Depending on the Principal using the system, the `sub` claim will have the following format:

* Users: `sub: "org:<orgID>/user:<userID>"`
* Runners: `sub: "org:<orgID>/rnr:<runnerID>"`
* Environments without a Project: `sub: "org:<orgID>/env:<environmentID>"`
* Environments from a Project: `sub: "org:<orgID>/prj:<projectID>/env:<environmentID>"`

### Granting access to anyone in the organization

You can configure your third-party service to grant access based on the `org:<orgID>` prefix.

### Granting access to an Environment created from a specific project

You can grant your third-party service access to an environment created from a specific project by matching the `org:<orgID>/prj:<projectID>` prefix.

### Grant access to a specific Environment

You can grant your third-party service access to a specific environment by matching the `org:<orgID>/prj:<projectID>/env:<environmentID>` prefix.


# Overview
Source: https://www.gitpod.io/docs/gitpod/configuration/overview



Gitpod empowers you to fully automate your development environment, ensuring consistency and efficiency across your team. Through the use of Dev Containers and Automations, you can define, customize, and version-control your entire development setup, giving you reproducible one-click development environments.

* [Dev Container](/gitpod/configuration/devcontainer/overview)
* [Automations](/gitpod/configuration/automations/overview)
* [Dotfiles](/gitpod/configuration/dotfiles/overview)


# Container Registry Secret
Source: https://www.gitpod.io/docs/gitpod/configuration/secrets/container-registry-secret



Container Registry Secrets allow you to use private Docker images as Dev Containers in your environment by providing authentication credentials for private container registries.

These container registry credentials will also be automatically available inside your environment when you include the `docker` CLI in your Dev Container image, allowing you to interact with private registries directly from your environment. If your Dev Container image does not include the `docker` CLI, you will see a warning in your environment creation page.

## When to use Container Registry Secrets

Use Container Registry Secrets when you need to:

* Pull Dev Container images from private registries
* Authenticate with container registries during your development workflow
* Work with private container images in your environment

> Currently, basic authentication (username/password) is supported for most registry types. AWS ECR is also supported through runner-native authentication when using AWS EC2 runners.

## Creating a Container Registry Secret

To create a Container Registry Secret:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets > New Secret** for Project secrets
* **Settings > Secrets > New Secret** for User secrets

2. Select **Container Registry Basic Auth** from the type dropdown
3. Configure the following fields:
   * **Type of secret**: Select **Container Registry Basic Auth** from the dropdown. Once created, the type cannot be changed.
   * **Name**: A unique identifier (3-127 characters, only alphanumeric characters, underscores, and hyphens)
   * **Registry hostname**: The hostname of your container registry (cannot be changed after creation)
   * **Registry username**: Your username for the container registry
   * **Registry password**: Your password or access token for the container registry

<Frame caption="Secrets Create Registry">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-create-registry.png" />
</Frame>

#### Common Registry Hostnames

* Docker Hub: `https://index.docker.io/v1/` (note the https\:// prefix)
* GitHub Container Registry: `ghcr.io`
* GitLab Container Registry: `registry.gitlab.com`
* Azure Container Registry: `[registry-name].azurecr.io`
* Google Container Registry: `gcr.io`
* AWS ECR: \[account-id].dkr.ecr.\[region].amazonaws.com (with runner-native support on EC2 runners)

## Using AWS ECR with IAM authentication

Gitpod now supports AWS ECR registries with IAM based authentication when using AWS EC2 runners. This means you can access private ECR repositories without manually managing credentials.

### Prerequisites

* You must be using AWS EC2 runners for your Gitpod environments
* Your ECR registry and EC2 runners must be in the same AWS account or have appropriate cross-account access configured

### Setting up ECR Registry Access

* Navigate to Project > Secrets > New Secret in your Gitpod dashboard
* Select Container Registry Basic Auth from the type dropdown
* For the Registry hostname, enter your ECR registry hostname in the format: \[account-id].dkr.ecr.\[region].amazonaws.com
* When you enter an ECR registry hostname, the username and password fields will automatically be filled with runner-native to indicate that native runner authentication will be used
* Click Add

<Frame caption="ECR Registry Secret Setup">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-create-ecr-registry.png" />
</Frame>

### Configuring IAM Permissions

To enable your EC2 runners to access your ECR repositories, you need to configure the appropriate IAM permissions:

* Locate your runner environment's IAM role from your CloudFormation stack outputs
* Attach appropriate ECR permissions to this role to allow it to pull images from your ECR repositories
* Update the repository policy of your ECR repository to allow access from the runner's IAM role
* Ensure the IAM role's permission boundaries (if configured) include the required ECR permissions

Here's an example policy you can attach to your runner's IAM role:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ],
      "Resource": "arn:aws:ecr:[region]:[account-id]:repository/[repository-name]"
    }
  ]
}
```

You'll also need to update the repository policy of your ECR repository to allow the runner's IAM role to access it. Here's an example ECR repository policy:

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGitpodRunnerPull",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[account-id]:role/[runner-role-name]"
      },
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchCheckLayerAvailability"
      ]
    }
  ]
}
```

### Limitations

* ECR runner-native registry support is only available for AWS EC2 runners
* Your EC2 runners and ECR registry must have properly configured IAM permissions
* Existing environments must be recreated to apply changes to ECR permissions

## Accessing Container Registry Secrets

Once created, container registry secrets serve two purposes:

1. They authenticate with private registries to pull images for your Dev Container during environment creation.

2. If your Dev Container image includes the `docker` CLI, Gitpod automatically runs `docker login` inside your environment to enable continued access to the registry.

<Note>
  For AWS ECR registries, we don't automatically log you into the registry from the environment. You'll need to authenticate as part of your workflows using either [AWS native authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html) setup or [Gitpod OIDC](/gitpod/configuration/oidc).
</Note>

If authentication fails inside your environment, you'll see a warning in your environment creation dashboard. This won't prevent your environment from starting but will limit your ability to pull additional private images from within your environment.

## Updating a Container Registry Secret

You can update the username and password of a Container Registry Secret at any time:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets** for Project secrets
* **Settings > Secrets** for User secrets

2. Find your Container Registry Secret and click the `Edit` button
3. Update the username and/or password
4. Click `Save`

<Frame caption="Secrets Update Registry">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-update-registry.png" />
</Frame>

When you update a Container Registry Secret:

* **New environments** will use the updated credentials
* **Existing running environments** will continue to use the old credentials until they are restarted
* **Registry hostname** cannot be modified after creation
* To apply updates to running environments, you must restart them

## Deleting a Container Registry Secret

To delete a Container Registry Secret:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets** for Project secrets
* **Settings > Secrets** for User secrets

2. Find your Container Registry Secret and click the `Delete` button
3. Confirm the deletion

After deletion:

* New environments launched from the project will no longer have access to the secret
* Existing environments that already have the secret will retain it until those environments themselves are deleted
* This may cause image pull failures if your environment depends on images from that registry

**Note:** When a project is deleted, all its secrets are automatically deleted as well.


# Environment Variables
Source: https://www.gitpod.io/docs/gitpod/configuration/secrets/environment-variables



Environment variables allow you to store and manage configuration settings that your application needs at runtime. These variables are accessible to your application's processes as standard environment variables, enabling you to:

* Configure your application for different environments (development, staging, production)
* Store configuration settings separate from your code
* Manage API keys and other configuration values

Environment Variable secrets you create in the Gitpod dashboard become accessible as system environment variables in your environment. The name you provide for the secret becomes the environment variable name.

## When to use Environment Variables

**Security Consideration**: For sensitive data (passwords, API tokens, private keys), we strongly recommend using [**files**](/flex/secrets/files) instead of environment variables.

### Comparison: Files vs Environment Variables

| Files                                           | Environment Variables                      |
| ----------------------------------------------- | ------------------------------------------ |
| Support complex structures (JSON, certificates) | Limited to simple string values            |
| Not visible in process listings                 | Visible via `ps auxe` commands             |
| Not included in crash reports or logs           | Often dumped in logs and error reports     |
| Explicitly used by processes                    | Automatically inherited by child processes |

Use environment variables for non-sensitive configuration like feature flags, API endpoints, or application modes.

## Creating an Environment Variable Secret

To create an Environment Variable Secret:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets > New Secret** for Project secrets
* **Settings > Secrets > New Secret** for User secrets

2. Select **Environment Variable** from the type dropdown
3. Configure the following fields:
   * **Type of secret**: "Environment Variable" (cannot be changed after creation)
   * **Name**: A unique identifier (3-127 characters, only alphanumeric characters, underscores, and hyphens)
   * **Value**: The value to be stored (maximum size: 4KB)

<Frame caption="Secrets Create Environment">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-create-envvar.png" />
</Frame>

## Accessing Environment Variables

Once created, environment variables are automatically available in your Gitpod environment as system environment variables by the name you provided. No special code is required to access them.

## Updating an Environment Variable Secret

You can update the value of an environment variable at any time:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets** for Project secrets
* **Settings > Secrets** for User secrets

2. Click the `Edit` button
3. Update the value
4. Click `Save`

<Frame caption="Secrets Update Environment">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-update-envvar.png" />
</Frame>

When you update a secret value:

* **New environments** will receive the updated value
* **Existing running environments** will continue to use the old value until they are restarted
* To apply updates to running environments, you must restart them

## Deleting an Environment Variable Secret

To delete an environment variable:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets** for Project secrets
* **Settings > Secrets** for User secrets

2. Click the `Delete` button
3. Confirm the deletion

After deletion:

* New environments launched from the project will no longer have access to the secret
* Existing environments that already have the secret will retain it until those environments themselves are deleted

**Note:** When a project is deleted, all its secrets are automatically deleted as well.


# Files
Source: https://www.gitpod.io/docs/gitpod/configuration/secrets/files



File secrets mount sensitive data as actual files in your Gitpod environment at a specified location. These files are automatically created when your environment starts, allowing your applications to read them like any other file on the filesystem.

## When to use File Secrets

File secrets are the recommended choice for:

* **Complex data structures** - JSON configurations, certificates, or other multi-line content
* **Sensitive credentials** - API keys, authentication tokens, and passwords
* **Binary data** - Certificates, keystore files, or other non-text content
* **Configuration that applications expect in file format** - Many applications look for specific configuration files

## Creating a File Secret

To create a File Secret:

1. Navigate to secret managent in your Gitpod dashboard

* **Project > Secrets > New Secret** for Project secrets
* **Settings > Secrets > New Secret** for User secrets

2. Select **File** from the type dropdown
3. Configure the following fields:
   * **Type of secret**: "File" (cannot be changed after creation)
   * **Name**: A unique identifier (3-127 characters, only alphanumeric characters, underscores, and hyphens)
   * **Value**: The content to be stored in the file (maximum size: 4KB)
   * **Mount Path**: The filepath where the secret will be mounted in your environment (cannot be changed after creation)

<Frame caption="Secrets Create File">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-create-filepath.png" />
</Frame>

## Accessing File Secrets

Once created, the file secret is automatically mounted at the specified path in your Gitpod environment. Your application can read it like any other file on the filesystem. No special code is required to access the file beyond normal file system operations.

## Updating a File Secret

You can update the content of a file secret at any time, although the mount path cannot be changed once the secret is created.

1. Navigate to the **Project > Secrets** page in your Gitpod dashboard
2. Click the `Edit` button
3. Update the value
4. Click `Save`

<Frame caption="Secrets Update File">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-update-filepath.png" />
</Frame>

When you update a secret value:

* **New environments** will receive the updated file content
* **Existing running environments** will continue to use the old file content until they are restarted
* To apply updates to running environments, you must restart them
* The mount path cannot be changed after creation

## Deleting a File Secret

To delete a file secret:

1. Navigate to the **Project > Secrets** page in your Gitpod dashboard
2. Click the `Delete` button
3. Confirm the deletion

After deletion:

* New environments launched from the project will no longer have access to the secret
* Existing environments that already have the secret will retain it until those environments themselves are deleted

**Note:** When a project is deleted, all its secrets are automatically deleted as well.


# Overview
Source: https://www.gitpod.io/docs/gitpod/configuration/secrets/overview

Learn how to configure secrets in Gitpod

Secrets allow you to securely store and inject sensitive data into your environments. These include API keys, access tokens, credentials, and certificates that your applications need but shouldn't be exposed in your source code.

Secrets are configured at three levels: organization, project, or user. They are automatically made available to any environment launched from that project. This ensures consistent and secure access to sensitive data across your development workflow.

## Secret Precedence

When secrets with the same name exist at different levels, they follow a strict precedence order:

1. **User Secrets** - Highest precedence
2. **Project Secrets** - Middle precedence
3. **Organization Secrets** - Lowest precedence

This means:

* User secrets override both project and organization secrets with the same name and mount
* Project secrets override organization secrets with the same name
* Organization secrets have the lowest priority

Learn more about managing [organization secrets](/flex/organizations/organization-secrets), [project secrets](/flex/projects/project-secrets), or [user secrets](/flex/configuration/secrets/user-secrets).

## Encryption of Secrets

All secrets you create are protected with industry-standard encryption. Secrets can only be retrieved by environments created from your projects (for Project secrets) or your user (for User secrets).

We use `AES256-GCM` to encrypt all secrets at rest in the database, with an additional layer of protection through AWS RDS encryption. This dual-layer approach ensures your sensitive data remains secure both at the application level and infrastructure level. In transit, all secrets are encrypted using TLS.

**Gitpod employees do not have access to the encryption keys and cannot decrypt your secrets.**

## Types of Secrets

Gitpod supports multiple types of secrets to accommodate different needs:

* [Files](/flex/configuration/secrets/files): Securely store and inject entire files into your environment
* [Environment Variables](/flex/configuration/secrets/environment-variables): Key-value pairs injected into your environment's process space
* [Container Registry Secrets](/flex/configuration/secrets/container-registry-secret): Authentication credentials for private container registries

Each type of secret serves a specific purpose in your development workflow. Click the links above to learn more about how to use each type effectively.


# User Secrets
Source: https://www.gitpod.io/docs/gitpod/configuration/secrets/user-secrets

Learn how to configure user secrets in your Gitpod Project

User secrets are a type of secret that are specific to a user. They are used to store sensitive data that is specific to a user, such as API keys, access tokens, and credentials which are shared across all projects and environments of a user.

**User secrets have the highest precedence** in the secrets hierarchy. This means they will override any project or organization secrets with the same name, allowing you to customize your environment without affecting other team members.

To manage your user secrets, navigate to the **Settings  > My account > Secrets** page in your Gitpod dashboard.

<Frame caption="Secrets List">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-user-list.png" />
</Frame>

## Secret Types

User secrets support the following types:

* [Environment Variables](/flex/configuration/secrets/environment-variables)
* [Files](/flex/configuration/secrets/files)
* [Container Registry Secrets](/flex/configuration/secrets/container-registry-secret)

## Creating a User Secret

To create a user secret, navigate to the **Settings > My account > Secrets** page in your Gitpod dashboard and click the **New Secret** button.

## Updating a User Secret

To update a user secret, navigate to the **Settings > My account > Secrets** page in your Gitpod dashboard and click the **Edit** button.

## Deleting a User Secret

To delete a user secret, navigate to the **Settings  > My account > Secrets** page in your Gitpod dashboard and click the **Delete** button.


# Cursor
Source: https://www.gitpod.io/docs/gitpod/editors/cursor



[Cursor](https://www.cursor.com/) uses the same extension as VS Code. Most of [VS Code documentation](/flex/editors/vscode) is applicable to Cursor. When reaching out to support, please specify that you are using Cursor as your editor.

## Opening an Environment

You can select Cursor from the editor selector dropdown by clicking on the dropdown arrow next to the editor button on the action bar.

<Frame caption="Open from the Action Bar">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/cursor/open_action_bar.png" />
</Frame>


# JetBrains
Source: https://www.gitpod.io/docs/gitpod/editors/jetbrains

Integrate JetBrains IDEs with Gitpod

Gitpod seamlessly integrates with JetBrains IDEs including IntelliJ IDEA Ultimate, GoLand, PhpStorm, PyCharm, RubyMine, WebStorm, Rider, CLion, and RustRover.

This guide will walk you through the setup process and provide tips for managing your development environments.

<Frame caption="Gitpod Website in WebStorm">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/ide-overview.png" />
</Frame>

## Prerequisites

Before starting, ensure that you have:

1. [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/) installed on your system

> **Tip**: Keep JetBrains Toolbox for the best experience.

## Opening an Environment

1. Start an environment in Gitpod
2. Select your preferred JetBrains IDE (e.g., "Open IntelliJ IDEA Ultimate") from the action bar

<Frame caption="Open from Environment Details">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/open-ide-button.png" />
</Frame>

### First-time Setup

On your first environment open, the setup process will:

1. Launch JetBrains Toolbox
2. Install the Gitpod plugin when prompted

<Frame caption="Plugin Installation">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/plugin-install.png" />
</Frame>

3. Request authentication with your Gitpod account

<Frame caption="Authentication">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/auth-prompt.png" />
</Frame>

### Connection Process

After authentication, Toolbox will:

1. Download and provision the IDE backend

<Frame caption="Installing JetBrains IDE Backend">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/installing-ide-backend.png" />
</Frame>

2. Start your local IDE client

<Frame caption="Installing JetBrains IDE Client">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/installing-ide-client.png" />
</Frame>

3. Connect to your environment automatically

<Frame caption="Connection Progress">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/connection-progress.png" />
</Frame>

## Limitations

* The version of JetBrains IDEs cannot be changed.
* JetBrains IDE settings and plugins cannot be customized.

## Managing Authentication

To change your Gitpod account or sign out from JetBrains Toolbox:

1. Open JetBrains Toolbox
2. Go to Settings → Providers → Gitpod
3. Click "Sign Out"
4. Click "Sign In" to authenticate with a different account

<Frame caption="Signing Out">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/sign-out.png" />
</Frame>

## Managing Environments

Toolbox list shows only recent environments you've previously opened. Open new environments from Gitpod directly.

<Frame caption="Recent Environments">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/recent-environments.png" />
</Frame>

## Rebuilding Dev Containers

When rebuilding a devcontainer:

1. Close your current IDE window
2. Wait for rebuild to complete
3. Return to Gitpod
4. Select the IDE in the action bar to reconnect

## Troubleshooting

### Connection Issues

If your IDE doesn't connect:

1. Verify JetBrains Toolbox is running
2. Ensure your environment is running in Gitpod
3. Try closing the IDE and reopening from Gitpod

### Collecting Toolbox Logs

For persistent issues:

1. Open JetBrains Toolbox
2. Navigate to Settings → About
3. Click "Show log files"
4. Locate `toolbox.log`
5. Send to [support@gitpod.io](mailto:support@gitpod.io)

<Frame caption="Collecting Toolbox Logs">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/collecting-toolbox-logs.png" />
</Frame>

<Warning>Do **NOT** share logs publicly as they may contain sensitive information</Warning>

### Collecting IDE Logs

For persistent issues:

1. Open JetBrains Toolbox
2. Navigate to your environment
3. Click on the three dots next to the IDE entry in the installed IDE list
4. Click "Show log files"
5. Send to [support@gitpod.io](mailto:support@gitpod.io)

<Frame caption="Collecting IDE Logs">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/jetbrains/collecting-ide-logs.png" />
</Frame>

<Warning>Do **NOT** share logs publicly as they may contain sensitive information</Warning>


# Overview
Source: https://www.gitpod.io/docs/gitpod/editors/overview

Learn how to integrate Gitpod with other tools and services. Gitpod works with any editor that uses SSH to connect to a remote backend.

* [VS Code](/flex/editors/vscode)
* [VS Code Browser](/flex/editors/vscode-browser)
* [Cursor](/flex/editors/cursor)
* [JetBrains](/flex/editors/jetbrains)
* [Zed](/flex/editors/zed)


# Visual Studio Code
Source: https://www.gitpod.io/docs/gitpod/editors/vscode



Gitpod seamlessly integrates with VS Code, allowing you to connect to your environments.
This guide will walk you through the setup process and provide tips for managing, troubleshooting, and recovering environments within VS Code.

<Frame caption="VS Code">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vs-code-desktop.png" />
</Frame>

## Prerequisites

Before starting, ensure that you have the following:

1. [VS Code](https://code.visualstudio.com/download) installed.
2. The [Gitpod Flex](https://marketplace.visualstudio.com/items?itemName=gitpod.gitpod-flex) extension for VS Code installed and enabled.
3. The [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension installed and enabled in VS Code.

> **Tip**: Keep your VS Code and extensions updated for the best experience.

## Opening an Environment

### VS Code

1. Start an environment in Gitpod

2. Open in **VS Code**

   * While the environment is starting, you can click the **Open in VS Code** button on the action bar. This button is available at any stage—even when the environment is not fully running yet.

     <Frame caption="Open from the Action Bar">
       <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/open_action_bar.png" />
     </Frame>

   * Alternatively, use the **VS Code** icon from the sidebar to launch the environment.

     <Frame caption="Open from the Side Bar">
       <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/open_sidebar.png" />
     </Frame>

3. VS Code should open or you should see a dialog asking you to open. See **Prerequisites** if you cannot open VS Code.

   <Frame caption="VS Code Open Dialog">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/open_dialog.png" />
   </Frame>

### VS Code Insiders

You can select **VS Code Insiders** from the editor selector dropdown by clicking on the dropdown arrow next to the editor button on the action bar.

<Frame caption="VS Code Insiders">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/select_vscode_insiders.png" />
</Frame>

## Install and Sign In

#### 1. Install the Gitpod Flex Extension

After opening, VS Code will prompt you to install the **Gitpod Flex** extension if it's not already installed.

* Click **Allow** when prompted.

  <Frame caption="Extension Installation Prompt">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/install_extension.png" />
  </Frame>

> **Note**: The extension will make changes to your local SSH configuration to enable a smooth experience. This allows for seamless connectivity between VS Code and your environments.

#### 2. Install Remote Development Extensions

The integration requires both the **Remote - SSH** extension to function. If this is not already installed, VS Code will notify you to add it.

* Click **Install** to add this dependency.

  <Frame caption="Install Prompt for Remote Development Extensions">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/install_remote_dev.png" />
  </Frame>

#### 3. Authenticate with Gitpod

VS Code will then ask you to authenticate with your Gitpod account:

1. Click **Open** when prompted to navigate to the Gitpod authentication page.
   <Frame caption="Authentication Prompt">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/open_auth.png" />
   </Frame>
2. Follow the authentication process to complete the sign-in.
   <Frame caption="Complete Authentication Page">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/complete_auth.png" />
   </Frame>
3. After signing in, you will be redirected back to VS Code and the page can be closed.

> **Note**: If you encounter any issues during the sign-in process, it may be helpful to sign out and try again.

## Workspace Trust

When connecting to a new environment, VS Code may prompt you to trust the workspace. This is a standard security measure for potentially untrusted code. For more information, refer to the [VS Code documentation](https://code.visualstudio.com/editor/workspace-trust).

Gitpod environments always run in isolated VMs, ensuring that code doesn't access secrets outside the environment. The environment remains secure regardless of how you access it. If you're familiar with the repository, you can safely click **Trust Folder & Continue**.

<Frame caption="Workspace Trust Prompt">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/workspace_trust.png" />
</Frame>

## Managing Your Environment

Once connected, you can manage your environment directly from VS Code:

### Viewing Environment Details

* Check the status, active branch, and logs using the **Environment Details** panel.
* If you closed the panel, re-open it using the `Gitpod Flex: Show Environment Details` command from the Command Palette.

<Frame caption="Environment Details in VS Code">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/details_view.png" />
</Frame>

> **Note**: Clicking on **details** while opening the environment will also open the **Environment Details** panel.

<Frame caption="Environment Details from Notification">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/openning.png" />
</Frame>

### Accessing Commands

* Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) and type `Gitpod Flex` to view commands such as:
  <Frame caption="Gitpod Commands">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/command_palette.png" />
  </Frame>

* Clicking on the **remote indicator** in the bottom-left corner of the remote window also shows a quick menu of Gitpod commands.
  <Frame caption="Remote Indicator">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/remote_indicator.png" />
  </Frame>

### Rebuild

Rebuilding is necessary to apply changes made to `.devcontainer.json`, `Dockerfile`, or `docker-compose.yml` files to the container. This process ensures that your development environment reflects the latest configuration updates.

To rebuild the container, you have two options:

1. **Command Palette**: Use `Gitpod Flex: Rebuild Container`
2. **Rebuild Prompt**: VS Code detects changes and prompts

   <Frame caption="Rebuild Prompt">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_notification.png" />
   </Frame>

While the container is rebuilding, you will be disconnected and automatically reconnected when it's finished. You can inspect the details view to learn about the progress and inspect logs.

<Frame caption="Rebuild Logs">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_logs.png" />
</Frame>

## Troubleshooting

### Limitations

Currently there are a couple limitations related to the devcontainer specification:

* Port forwarding does not work for hosts other than `localhost`. For instance, forwarding ports from other services specified in a docker-compose.yml  .
  * ✅ Workaround: Use `network_mode: host` in your docker-compose.yml for the services you want to port forward.
* `remoteEnv` environment variables values are not applied unless the devcontainer is rebuilt.

### Build Issues

If the initial build or a rebuild fails, you will enter recovery mode.

When a build failure occurs:

1. A modal will appear notifying you of the failure.
   <Frame caption="Rebuild Failure">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_failed.png" />
   </Frame>
2. Pay close attention to the error messages in the details view.
   <Frame caption="Rebuild Failure Details">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_failed_details.png" />
   </Frame>
3. Inspect the logs as necessary to understand the root cause of the failure.
   <Frame caption="Rebuild Failure Logs">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_failed_logs.png" />
   </Frame>
4. Make the required changes to the `.devcontainer.json` file to address the issue.
5. Trigger a rebuild using the `Gitpod Flex: Rebuild Container` command.

> **Important**: The recovery mode is not stable for development. Always aim to fix the configuration and successfully rebuild the container.

### Authentication Issues

If you're experiencing authentication issues or need to switch accounts:

1. Use the `Gitpod Flex: Sign Out` command to sign out.
2. Confirm the sign-out when prompted.
3. You can then sign in again with the same or a different account.

### General Issues

If you encounter unexpected problems:

1. Check the `Gitpod Flex` output view for any useful information.
2. Check your network settings, sometimes the VPN or firewall settings can interfere with the connection.
3. When sharing reports with us:
   * Use `Developer: Set Log Level...` command to Trace, it would give us more insights. Remember to set it back to Info afterwards.
   * In your VS Code settings, set `remote.SSH.logLevel` to `trace`.
   * Use the `Gitpod Flex: Export all logs` command from the problematic window. This will contain all relevant logs.

> **Note**: Be cautious when sharing logs on the internet, as they may contain sensitive information.

## Uninstalling

When uninstalling the Gitpod Flex extension, simply removing the extension from VS Code is not sufficient for a complete uninstall. Using the `Uninstall Extension` command ensures that all associated configurations, including SSH settings, are properly cleaned up.

1. Use the `Gitpod Flex: Uninstall Extension` command to initiate the uninstallation process.
2. Follow the prompts to complete the uninstallation process.

If you've already uninstalled the extension without using the command, you can install it again and then use the uninstall command.


# Visual Studio Code Browser
Source: https://www.gitpod.io/docs/gitpod/editors/vscode-browser



You can connect to your environments using VS Code in the browser, providing a zero-install, “ready to code” experience.
This guide will walk you through the setup process and provide tips for managing and troubleshooting within VS Code Browser.

<Frame caption="VS Code Browser">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/vscode_browser.png" />
</Frame>

## Opening an Environment

1. Start an environment in Gitpod

2. Open in **VS Code Browser**

   * While the environment is starting, you can click the **Open in VS Code Browser** button on the action bar, which is possible even when the environment is not fully running yet. VS Code Browser should open in a new tab.

     <Frame caption="Open from the Action Bar">
       <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/open_action_bar.png" />
     </Frame>

3. VS Code Browser will then ask you to authenticate with your Gitpod account:

   1. Click **Allow** when prompted to sign in to navigate to the Gitpod authentication page.

   <Frame caption="Authentication Prompt">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/open_auth.png" />
   </Frame>

   2. Follow the authentication process to complete the sign-in.

   <Frame caption="Complete Authentication Page">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/complete_auth.png" />
   </Frame>

   3. After signing in, you will be redirected back to VS Code and the page can be closed.

> **Note**: If you encounter any issues during the sign-in process, it may be helpful to sign out and try again.

## Managing Your Environment

Once connected, you can manage your environment directly from VS Code in the Browser:

### Viewing Environment Details

* Check the status, active branch, and logs using the **Environment Details** panel.
* If you closed the panel, re-open it using the `Gitpod Flex: Show Environment Details` command from the Command Palette.

<Frame caption="Environment Details in VS Code">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/details_view.png" />
</Frame>

### Accessing Commands

* Open the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) and type `Gitpod Flex` to view commands such as:
  <Frame caption="Gitpod Commands">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/command_palette.png" />
  </Frame>

* Clicking on the **remote indicator** in the bottom-left corner of the window also shows a quick menu of Gitpod commands.
  <Frame caption="Remote Indicator">
    <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode-browser/remote_indicator.png" />
  </Frame>

### Rebuild

Rebuilding is necessary to apply changes made to `.devcontainer.json`, `Dockerfile`, or `docker-compose.yml` files to the container. This process ensures that your development environment reflects the latest configuration updates.

To rebuild the container, you have two options:

1. **Command Palette**: Use `Gitpod Flex: Rebuild Container`
2. **Rebuild Prompt**: VS Code detects changes and prompts

   <Frame caption="Rebuild Prompt">
     <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_notification.png" />
   </Frame>

While the container is rebuilding, you will be disconnected and automatically reconnected when it's finished. You can inspect the details view to learn about the progress and inspect logs.

<Frame caption="Rebuild Logs">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/vscode/rebuild_logs.png" />
</Frame>

### Settings Sync

Enable Settings Sync to sync all your extensions and other preferences from VS Code Desktop in VS Code Browser, read more about over at the [offical Settings Sync documentation](https://code.visualstudio.com/docs/configure/settings-sync#_turning-on-settings-sync).

## Troubleshooting

### Limitations

The following limitations are present in addition to the [limitations listed for VS Code Desktop](/flex/editors/vscode#limitations):

* For environments using a Docker Compose configuration, it's required to set `network_mode: "host"` on the main service in your Docker Compose file for VS Code Browser to successfully connect to the environment.
* VS Code Browser is not supported for [local environments](/gitpod-desktop/overview#local-environments) created using Gitpod Desktop.

### Authentication Issues

If you're experiencing authentication issues or need to switch accounts:

1. Use the `Gitpod Flex: Sign Out` command to sign out.
2. Confirm the sign-out when prompted.
3. You can then sign in again with the same or a different account.

### General Issues

If you encounter unexpected problems:

1. Check the `Gitpod Flex` output view for any useful information.
2. When sharing reports with us:
   * Use `Developer: Set Log Level...` command to Trace, it would give us more insights. Remember to set it back to Info afterwards.
   * Use the `Gitpod Flex: Export all logs` command from the problematic window. This will contain all relevant logs.

> **Note**: Be cautious when sharing logs on the internet, as they may contain sensitive information.


# Windsurf
Source: https://www.gitpod.io/docs/gitpod/editors/windsurf



[Windsurf](https://windsurf.com/) uses the same extension as VS Code. Most of [VS Code documentation](/flex/editors/vscode) is applicable to Windsurf. When reaching out to support, please specify that you are using Windsurf as your editor.

## Opening an Environment

You can select Windsurf from the editor selector dropdown by clicking on the dropdown arrow next to the editor button on the action bar.

<Frame caption="Open from the Action Bar">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/windsurf/open_action_bar.png" />
</Frame>


# Zed
Source: https://www.gitpod.io/docs/gitpod/editors/zed



## Connecting an environment to Zed

Gitpod works with any remote and SSH compatible editor, including [Zed](https://zed.dev/download).

### Step 1 - Install the CLI and setup your SSH configuration

The easiest way to setup SSH configuration is by installing the [Gitpod CLI](/flex/integrations/cli).

Once installed, run `gitpod env ssh-config` to update your **local** SSH configuration.

To validate ensure the directory `~/.ssh/gitpod` is created on your local machine.

### Step 2 - Find the host for your environment

You can find the host name on your started environment details page.

The host format is: `<environment-id>.gitpod.environment`

For example: `01922350-2462-79da-8c80-770fe4275aa2.gitpod.environment`

<Frame caption="copying host id from app">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/copy-host.png" />
</Frame>

> **Note:** You do not need the `ssh` command when connecting to JetBrains.

### Step 3 - Connect with your environment

In Zed open the remote projects dialogue with `cmd-shift-p remote`. - Add a connection. - Insert the SSH host from above.

<Frame caption="connect via zed">
  <img src="https://www.gitpod.io/images/docs/flex/integrations/zed-connection.png" />
</Frame>

See [zed documentation](https://zed.dev/remote-development) for more.


# Archive & Auto-delete
Source: https://www.gitpod.io/docs/gitpod/environments/archive-auto-delete

Automatically manage inactive environments to optimize storage costs

Archive & Auto-delete automatically manages inactive environments through a two-stage lifecycle: archival after 7 days of inactivity, then auto-deletion based on configurable policies.

## How it works

1. **Automatic archiving**: After 7 days of inactivity (fixed)
2. **Configurable auto-deletion**: After 1, 2, or 4 weeks, or never

### Environment lifecycle

```mermaid
graph LR
    A[Active] -->|7 days inactive| B[Archived]
    B -->|After 1w, 2w, or 4w| C[Auto-deleted]
    B -->|Unarchive| A
    B -->|Delete| D[Deleted]
```

## Automatic archiving

Environments are archived when stopped for 7 consecutive days (fixed period).

Archived environments:

* Move to a separate archive view
* Can be unarchived or deleted

## Accessing archived environments

<Frame caption="The Archive button in the sidebar shows a badge when you have archived environments">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/archive_badge.png" alt="Archive button with badge indicator" />
</Frame>

Click the **Archive** button in your sidebar to view archived environments. The button shows a badge when environments are archived. Press `Escape` to return to the main view.

<Frame caption="The Archive view shows all archived environments">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/archive_environments.png" alt="Archive view showing all archived environments" />
</Frame>

## Managing archived environments

### Archive view organization

Environments are grouped by when they were archived:

* **1 week ago**
* **2 weeks ago**
* **1+ month ago**

### Available actions

<Frame caption="Hover over an archived environment to see available actions">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/archive_unarchive_button.png" alt="Archive view showing environment actions" />
</Frame>

#### Unarchive an environment

Hover over the environment and click the restore button to unarchive. The environment returns to your main list immediately.

#### Delete an environment

Hover over the environment and click the delete button to delete. Confirm in the dialog.

<Warning>
  Deleting an environment permanently removes all content, including code, configurations, and data. This action cannot be undone.
</Warning>

#### Delete all archived environments

<Frame caption="The Delete All button appears at the bottom of the archive view">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/archive_delete_all.png" alt="Delete All button at bottom of archive view" />
</Frame>

Click the **Delete All** button at the bottom and confirm to delete all archived environments.

## Auto-delete configuration

### Setting your preference

<Frame caption="Configure your auto-delete preference using the dropdown in the archive view">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/archive_auto_delete_settings.png" alt="Auto-delete dropdown showing available options" />
</Frame>

Select your auto-delete preference from the dropdown:

* **After 1 week**: 14 days total from last use
* **After 2 weeks**: 21 days total from last use
* **After 4 weeks**: 35 days total from last use
* **Never**

### Organization policies

Organization policies override user preferences when more restrictive. Disabled options in the dropdown indicate policy restrictions.

## Best practices

* **Before archiving**: Commit and push important work
* **Team coordination**: Align deletion timelines with your workflow needs

## Frequently asked questions

**When are environments archived?**
After 7 days of inactivity (fixed period).

**Can I recover deleted environments?**
No, deletion is permanent. Only archived environments can be recovered.

**Why are some auto-delete options disabled?**
Your organization policy may enforce maximum retention periods.

**Do running environments get archived?**
No, only stopped environments are archived.

## Troubleshooting

**Can't change auto-delete preference**: Check for organization policy restrictions.


# Configure a dev environment
Source: https://www.gitpod.io/docs/gitpod/getting-started/configure-dev-environment



With Gitpod, you have a fully configured development environment that starts in a single-click. We achieve this through configuring a Dev Container and Automations. This guide takes you through configuring your first environment.

<Note>
  {' '}

  **Pre-requisites** <br /> Install [Gitpod Desktop or the AWS Runner](/flex/getting-started)
  before completing this guide.
</Note>

{/* <!-- <Frame caption="">
  <img src="https://www.gitpod.io/images/docs/flex/projects/create-env.png" />
  </Frame> --> */}

{/* <!-- TODO: Image --> */}

**Steps**

* [Configure development environment](#configure-development-environment)
  * [Create an environment](#create-an-environment)
  * [Configure your Dev Container](#configure-your-dev-container)
  * [Configuring Automations](#configuring-automations)
  * [Publishing your project](#publishing-your-project)
  * [What next?](#what-next)

## Create an environment

Start by choosing a repository and environment class to launch your first environment. Once launched we'll then configure the environment and save it as a project. This will mean that you've created a blueprint so your team can also self-serve a one-click experience for their own fully prepared development environment.

<Frame>
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/select-environment-class.png" />
</Frame>

## Configure your Dev Container

Let's get started with Dev Container to eliminate the need to manually install tools and dependencies. If you don't have an existing devcontainer in your repository Gitpod will create a basic example file for you in your environment.

A basic Dev Container example stored in `.devcontainer/devcontainer.json`

```json
{
	"name": "Node.js Dev Container",
	"image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",
	"customizations": {
		"vscode": {
			"settings": {},
			"extensions": ["dbaeumer.vscode-eslint"]
		}
	},
	"remoteUser": "node"
}
```

As you make changes you can rebuild your environment by running:

`gitpod environment devcontainer rebuild`.

See [devcontainer](/flex/configuration/devcontainer) for more.

## Configuring Automations

Automations go beyond Dev Container and are a powerful way to define, automate and share common workflows that you perform with your development environment

Automations are defined in configuration YAML files and updated via the Gitpod CLI that comes preinstalled in your environment.

For example:

* Seeding a database
* Running a unit test.

See [automations - examples](/flex/configuration/automations/examples) for many more automation examples.

An example Automations file example stored in `.gitpod/automations.yaml`

```yaml
services:
    database:
        name: PostgreSQL
        commands:
            start: docker run postgres
tasks:
    run-unit-tests:
        name: Runs unit tests
        command: go test -v ./...
    install-dependencies:
        name: Install dependencies
        command: npm install
        triggeredBy:
            - postDevcontainerStart
            - manual
```

When you’re done run `gitpod automations update` to register your Automations with Gitpod.

See [automations](/flex/configuration/automations) for more.

## Publishing your project

When done commit both your devcontainer and automation configuration files and hit publish on your project in Gitpod. You’ve now set up a fully-configured project that is your blueprint for a fully-configured development environment and it’s now shared with your team inside your Gitpod organization.

## What next?

Now that you're done, why not take a look at:

{/* <!-- TODO: Add link for Gitpod Desktop --> */}

* Setting up an [AWS Runnner](/flex/runners/aws) or [Gitpod Desktop]() (if you haven't already)
* Further [optimizing your devcontainer](/flex/configuration/devcontainer/optimizing-startup-times)
* Exploring an [integration](/flex/integrations)


# Gitpod Desktop
Source: https://www.gitpod.io/docs/gitpod/getting-started/create-dev-environment-desktop-app

Run Gitpod environments locally on your Apple silicon Mac with Gitpod Desktop

Gitpod Desktop is the fastest and easiest way to run and recreate cloud development environments locally on your Apple silicon Mac. It provides a seamless development experience with the benefits of local computing resources.

## Benefits of Gitpod Desktop

* **Local Performance:** Harness the full power of your Apple silicon Mac.
* **Cost Efficiency:** Use your local machine resources without incurring additional cloud computing costs.
* **Work Offline:** Continue working in already-running environments even when you lose internet connectivity.
* **Resource Isolation:** Run development environments in isolation from your host system for improved security and dependency management.
* **Easy Setup:** One-click environment setup without complex virtualization configuration.
* **Consistent Experience:** Enjoy the same reliable, reproducible environments whether working locally or in the cloud.

## Prerequisites

* **Operating System**: macOS Sonoma or later
* **CPU**: Apple M1 chip or newer (Apple silicon)
* **RAM**: 16GB or more
* **Architecture**: Apple silicon (ARM-based Macs)

## Download and Install

1. Visit [app.gitpod.io](https://app.gitpod.io/) and look for the download link in the navigation bar
2. Alternatively, download directly from [gitpod.io/gitpod-desktop/download](https://www.gitpod.io/gitpod-desktop/download)
3. Install the application on your Mac

<Frame caption="Download link in the app.gitpod.io navigation bar">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/download-desktop-app.png" />
</Frame>

## First-Time Setup

When you first launch Gitpod Desktop, the application will:

1. Verify and configure the macOS runner
2. Set up the file system (this may take several minutes)
3. Display installation progress
4. Prompt you to authenticate with your Gitpod account
5. Guide you through Git authentication setup

## Create Your Environment

Once the setup is complete:

1. In the sidebar, click **Create an environment**
2. Paste a public or private repository URL
3. Click **Create environment**

<Frame caption="Enter your repository URL to create a new environment">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/insert-repository-url.png" />
</Frame>

## Choose Gitpod Desktop

To run your environment locally:

1. When prompted to select an environment class, choose **Gitpod Desktop**
2. Your local Gitpod Desktop application will begin setting up the environment
3. The setup process will pull necessary container images and configure your workspace

<Frame caption="Select Gitpod Desktop as your environment class">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/select-environment-class.png" />
</Frame>

## Git Authentication

For accessing repositories (especially private ones), Gitpod Desktop provides several authentication options:

1. **Automatic detection**: The runner checks your local credential manager for existing Git tokens
2. **Manual token entry**: If no token exists, you'll be prompted to provide a Personal Access Token (PAT)
3. **Token management**: Manage your PATs under Settings → Git Authentication
4. **Token refresh**: Authentication tokens are automatically refreshed when environments restart

For self-hosted source control providers, organization administrators must configure them in organization settings first.

## Features and Limitations

### Key Features

* Uses your local machine resources at no additional cloud cost
* Built-in Linux virtualization optimized for Apple Silicon
* One-click setup with full workload isolation
* Limited offline capabilities for already-running environments
* Organization administrators can disable local runners

### Limitations

* No port sharing available (unlike cloud runners)
* Currently only available for Apple silicon Macs

## Troubleshooting

If you encounter issues with Gitpod Desktop:

* **Runner installation failures**: Verify system requirements and macOS version
* **Account switching issues**: Only one runner can be active at a time, tied to a single organization
* **Git authentication problems**: Check your credentials or generate a new PAT
* **Unexpected runner failures**: Restart the application or reset the runner

For persistent issues:

1. Collect logs through Help → Troubleshooting → Collect Logs and Diagnostics
2. Contact support through the support chat
3. If needed, perform a clean uninstall by following the instructions in the support documentation

## Advanced Configuration

* **Organization settings**: Administrators can control local runner usage through Settings → Runners → Gitpod Desktop
* **Repository access**: Administrators can configure repository access to source control providers
* **Git authentication**: Users can configure and manage Git authentication settings
* **Cache management**: Clear shared cache for Docker images and builds as needed
* **Preview builds**: Advanced users can switch between Stable and Insiders (preview) builds

## Next Steps

* Learn about [environment configuration](/flex/configuration) to customize your development setup
* Explore [VS Code extensions](/flex/vscode-extensions) to enhance your development environment
* Check out how to [switch between local and cloud environments](/flex/switching-environments) for different workflows

For additional help, visit the [Gitpod Community](https://community.gitpod.io/) or [contact support](https://www.gitpod.io/contact).


# Self-host Linux runner
Source: https://www.gitpod.io/docs/gitpod/getting-started/create-dev-environment-linux-runner

Run Gitpod environments on your own Linux machine

The Linux runner enables you to run Gitpod environments directly on your own Linux machine. This gives you full control over your infrastructure while enjoying Gitpod's collaborative features.

## Benefits of self-hosting

Self-hosting a Linux runner offers several advantages:

* **Full infrastructure control**: Maintain complete control over your hardware and environment configurations
* **Fixed costs**: Only pay for your own hardware with no usage-based billing
* **Network access**: Direct access to your local network services and resources
* **Resource allocation**: Support for up to 10 concurrent environments on a single runner
* **Security**: Keep your code and development activities within your own infrastructure
* **Customization**: Tailor hardware resources to your specific development needs

## Prerequisites

Before setting up a Linux runner, ensure your system meets these requirements:

* A Linux machine with AMD64/x86\_64 architecture
* Hardware virtualization support (KVM)
* Minimum 2GB RAM per environment you plan to run
* Root/sudo access for initial setup
* Admin access to your Gitpod organization

For detailed system requirements, see the [requirements documentation](/flex/runners/linux/requirements).

## Security considerations

When self-hosting a Linux runner:

* The runner requires root access during installation but runs with reduced privileges
* Environments run in isolated containers but can access the host network
* Consider network isolation if running on shared infrastructure
* Regularly update the runner for security patches

## Limitations

* Maximum of 10 concurrent environments per runner
* No built-in high availability options

## Installation and setup

To set up your Linux runner:

1. [Set up your Linux runner](/flex/runners/linux/setup)
2. [Configure environment classes](/flex/runners/linux/setup#environment-classes)
3. [Set up repository access](/flex/runners/linux/setup#repository-access)

For detailed information about Linux runners, including maintenance and troubleshooting, see the [Linux runners documentation](/flex/runners/linux).


# AWS Runner
Source: https://www.gitpod.io/docs/gitpod/getting-started/create-dev-environment-self-hosted-aws-runner

Deploy a Gitpod runner in your AWS account to create secure, cloud-based development environments for your entire team

Deploy a Gitpod runner in your AWS account to create secure, cloud-based development environments for your entire team. Unlike Gitpod Desktop which is installed per user, an AWS runner is deployed once and can be used by multiple team members.

## Benefits of the AWS Runner

* **Team-wide deployment**: Install once, benefit the entire team
* **Enhanced security**: Development environments run within your own AWS infrastructure
* **Resource efficiency**: Centralized management of compute resources
* **VPC integration**: Securely access internal services and resources within your AWS network
* **Customizable performance**: Configure environment classes to match your development needs
* **Scalability**: Support for multiple team members without individual installations

## Prerequisites

* **Admin role** in your Gitpod organization
* An AWS account with permissions to create CloudFormation stacks
* Basic knowledge of AWS networking concepts (VPC, subnets)

## Steps to set up an AWS runner

### 1. Create a runner configuration

1. Visit [app.gitpod.io](https://app.gitpod.io/)
2. Open your organization settings
3. Click **Runners** in the navigation
4. Click **Setup an AWS runner**

<Frame caption="Runners configuration page in Gitpod">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runners-settings.png" />
</Frame>

**Note:** A runner is associated with an organization. You can have multiple runners, each restricted to a single AWS region.

### 2. Connect the runner to AWS

1. Ensure you're logged into the correct AWS account
2. Click **Continue on AWS**

<Frame caption="Runner configuration ready for AWS deployment">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-aws-config-complete.png" />
</Frame>

> If you don't have direct AWS access, you can copy the runner details from this page and share them with your AWS account administrator.

3. Complete the CloudFormation form with the **required** fields:
   * VPC
   * Availability zone
   * Subnet

If you're unsure which values to use, select the [default networking](https://docs.aws.amazon.com/vpc/latest/userguide/default-vpc.html) options, which should auto-populate in the form.

<Frame caption="AWS CloudFormation parameters configuration">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-parameters-configuration.png" />
</Frame>

4. Click **Create stack**

The CloudFormation stack typically takes about 3 minutes to deploy.

### 3. Configure source control access

1. Return to the runner configuration page where your runner should now show as **Online**
2. Configure repository access by selecting a provider (such as GitHub)
3. Enable OAuth or [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) access

<Frame caption="Configure source control providers in Gitpod">
  <img src="https://www.gitpod.io/images/docs/flex/runners/repository-provider.png" />
</Frame>

### 4. Configure environment classes (Optional)

You can configure available environment classes for your runner. An environment class defines the performance profile (CPU, memory) for development environments on this runner.

<Frame caption="Add environment class in Gitpod">
  <img src="https://www.gitpod.io/images/docs/flex/runners/add-env-class.png" />
</Frame>

### 5. Create your development environment

1. Click **Create an environment** in the navigation bar
2. Paste a repository URL (public or private)
3. Click **Create environment**
4. Select an environment class from your AWS runner

<Frame caption="Select environment class for your new environment">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/select-environment-class.png" />
</Frame>

## Troubleshooting

### Common issues

* **CloudFormation deployment fails**: Ensure you've selected a valid VPC and subnet. The most common error is forgetting to select these required fields.
* **Runner shows as offline**: Check your AWS console to verify the EC2 instances are running correctly.
* **Cannot access private repositories**: Verify your OAuth or PAT configuration has the correct permissions for repository access.

## Next steps

After setting up your AWS runner and creating your first environment:

* Learn more about [projects](/flex/projects/overview)
* See [AWS Runner](/flex/runners/aws) for more detailed information.


# Overview
Source: https://www.gitpod.io/docs/gitpod/getting-started/overview

Learn the different ways to run Gitpod development environments

Gitpod provides flexible options for running your development environments, either locally on your machine or securely in your own cloud infrastructure (VPC) or hardware.

## Deployment Options

Choose the option that best fits your workflow and infrastructure requirements:

| Option             | Description                                                 | Best for                                                         |
| ------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| **Gitpod Desktop** | Run environments locally with built-in Linux virtualization | Individual developers or teams without cloud infrastructure      |
| **AWS Runner**     | Run in your own AWS VPC with full control                   | Teams needing enterprise-grade compute resources and GPU support |
| **Linux Runner**   | Run directly on your Linux machine with simple setup        | Small teams wanting direct local network access                  |

## Detailed Comparison

### Gitpod Desktop

* **Infrastructure**: Runs locally on your machine using built-in virtualization
* **Cost**: No additional infrastructure costs
* **Compute Resources**: Limited to your local hardware
* **Collaboration**: Project sharing only available with other Gitpod Desktop users
* [**Get Started with Gitpod Desktop →**](/gitpod/getting-started/create-dev-environment-desktop-app)

### AWS Runner (Bring Your Own Cloud)

* **Infrastructure**: Runs securely in your own AWS VPC
* **Cost**: Pay only for the AWS resources you use (can be covered by AWS free tier)
* **Compute Resources**: Scale up to 896 vCPUs and 12TB RAM with GPU support
* **Collaboration**: Environments can be shared with everyone in your organization
* [**Get Started with AWS Runner →**](/gitpod/getting-started/create-dev-environment-self-hosted-aws-runner)

### Linux Runner (On Your Hardware)

* **Infrastructure**: Runs directly on your Linux machine
* **Cost**: Fixed costs based on your existing hardware
* **Compute Resources**: Support for up to 10 concurrent environments
* **Collaboration**: Direct local network access for your team
* [**Get Started with Linux Runner →**](/gitpod/getting-started/create-dev-environment-linux-runner)

## Next Steps

After selecting your deployment option:

1. [Configure your development environment](/gitpod/getting-started/configure-dev-environment)
2. Set up authentication (via Personal Access Token or OAuth)
3. Configure maintenance and update strategies


# Gitpod Desktop
Source: https://www.gitpod.io/docs/gitpod/gitpod-desktop/overview



Gitpod Desktop is the fastest and easiest way to run and recreate cloud development environments locally. It is currently available for Apple silicon users.

<Frame caption="Getting Started">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/getting_started.png" />
</Frame>

## Benefits

* Run Dev Containers locally, replacing Docker Desktop for local development optimized for Apple Silicon, providing native-like Linux development without the overhead.
* One-click setup, full workload isolation, and the ability to "break it, forget it" - iterate quickly without fear of polluting your system.
* Leverage your local machine's resources for free
* Easily share your configured environments across your team to benefit from the automation and standardization of cloud development environments on your own hardware.
* Through Automations, get an optimized developer experience to launch environments and common development workflows through Gitpod Automations.
* Stay productive with offline capability and built-in disaster recovery support, seamlessly switching between local and cloud development as needed.

## Setup

### Download

1. Download Gitpod Desktop for Apple Silicon [here](https://www.gitpod.io/gitpod-desktop/download)
2. Open `Gitpod.dmg` and drag `Gitpod.app` into the Applications folder
3. Launch Gitpod Desktop from the Applications folder

You can also find it in the Gitpod dashboard at [app.gitpod.io](https://app.gitpod.io).

<Frame caption="Download Gitpod Desktop">
  <img src="https://www.gitpod.io/images/docs/flex/getting-started/download-desktop-app.png" />
</Frame>

### Install Runner

When you first launch Gitpod Desktop, it will guide you through a simple setup process:

1. The app will verify and configure the macOS runner (used to run [environments locally](#local-environments))
2. Wait for the installation to complete
   * Note: The "Setting up file system" step may take several minutes
   * The progress will show you the current status

<Frame caption="Install macOS runner">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/installation.png" />
</Frame>

<Tip>
  {' '}

  If you have trouble installing, please check the [troubleshooting guide](#runner-installation-failure).{' '}
</Tip>

## Authentication

To use Gitpod Desktop, you'll need to connect it with your Gitpod account:

1. When you first open the app, click **Sign into Gitpod** in the prompt window. This will open your default browser.
   <Frame caption="Authentication Prompt">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/auth.png" />
   </Frame>

2. Sign in using your Gitpod account credentials.
   <Frame caption="Complete Authentication Page">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/auth_complete.png" />
   </Frame>

3. Once signed in, you can close the browser window and return to Gitpod Desktop.

4. Gitpod Desktop should open or you should see a dialog asking you to open.
   <Frame caption="Gitpod Desktop Open Dialog">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/open.png" />
   </Frame>

<Tip>
  {' '}

  If you have trouble signing in, try to [sign out completely and try again](#switching-accounts).{' '}
</Tip>

## Local Environments

Gitpod Desktop automatically starts a macOS runner for the current organization, managing local environments.

### Git Authentication

Local environments require Git access to clone repositories. Here's how authentication works:

1. **Git Credentials:** The runner automatically checks your local credential manager for an existing Git token. If found, it's used immediately. Tokens are automatically refreshed when environments restart to maintain access.
2. **Personal Access Token (PAT):** If no token exists, Gitpod will prompt you to provide a PAT when creating an environment first time. You can manage your PAT under `Settings` -> `Git Authentication`. Click `Authenticate and Create` to proceed.
   <Frame caption="Gitpod Desktop Open Dialog">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/git_auth.png" />
   </Frame>
3. **Connect to Source Control:** Gitpod Desktop will initiate a connection to your source control provider (e.g., GitHub). Follow along the instructions to grant access to your repositories.
   <Frame caption="Connect to GitHub">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/github_connect.png" />
   </Frame>
4. **Self-Hosted SCM Providers:** If you use a self-hosted source control provider, administrators must configure it in the organization settings. Members can then authenticate using PATs. See [Configuring Repository Access](#configuring-repository-access).

<Tip>
  {' '}

  If you encounter Git access issues, try to [invalidate Git authentication](#invalidate-git-authentication).{' '}
</Tip>

### Runner Lifecycle

Each macOS runner is tied to a single organization, and only one runner can be active at a time.

Here's how it works:

* **Stopping the Runner:** Stops all associated local environments.
* **Quitting Gitpod Desktop:** Automatically stops the runner.
* **Switching Organizations:** The current organization's runner is stopped. The new organization's runner is started.
* **Restarting Gitpod Desktop:** Starts the runner again.
* **Restarting Environments:** Upon restarting Gitpod Desktop, you can start local environments again.

### Shared Cache

Local environments use a shared cache for Docker images and builds stored on your local machine. This cache speeds up the creation of new environments and the rebuilding of existing ones.

To clear the cache, select "Help" > "Troubleshooting" > "Clear Cache and Restart" from the menu bar.

Clearing the cache can be useful if the caches are corrupted or you want to start fresh.

## Organization Settings

### Disabling Local Environments

Organization administrators can control the use of local runners (Gitpod Desktop) across their organization:

1. Navigate to Settings -> Runners -> Gitpod Desktop in your organization settings
2. Use the toggle to enable or disable local runners for your organization

<Tip>
  {' '}

  Disabling local runners will immediately stop all running environments on Gitpod
  Desktop and prevent members from starting new local environments. Before disabling,
  notify organization members as they will lose access to any active work in local
  environments.{' '}
</Tip>

### Configuring Repository Access

Administrators can configure repository access to source control providers for local runners:

1. Navigate to Settings -> Runners -> Gitpod Desktop
2. Configure authentication for source control providers:
   * `github.com` and `gitlab.com` are configured by default
   * For self-hosted SCM providers, administrators must add them here before members can authenticate
   * Members can then use **Personal Access Tokens** (PAT) to authenticate with configured providers, if they don't have existing Git credentials on their machine

See [Source Control](/flex/source-control) for more information on configuring source control providers.

<Frame caption="Desktop Settings">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/desktop_settings.png" />
</Frame>

## Updating

Gitpod Desktop releases new versions weekly, delivering the latest improvements and features. While the application updates automatically, you can manually check for updates by selecting "Gitpod" > "Check for Updates..." from the menu bar.

<Frame caption="Check for Updates">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/check_for_updates.png" />
</Frame>

After downloading a new version, Gitpod Desktop will prompt you to restart the application to apply the update.

### Checking Your Version

To check your current version, select "Gitpod" > "About Gitpod Desktop" from the menu bar.
Click "Copy" to save the version information to your clipboard, which can be helpful when [seeking support](#report-issue).

<Frame caption="About Gitpod Desktop">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/about.png" />
</Frame>

### Switching to Insiders

<Warning>
  {' '}

  Switching to Insiders is an advanced feature that may cause instability or break
  your Gitpod Desktop installation. Only proceed if you understand the risks.{' '}
</Warning>

Gitpod Desktop provides nightly builds for testing and feedback purposes. While we recommend using the stable version, accessing Insiders builds can be useful when you want to preview upcoming features before their official release.

To switch to Insiders:

1. Quit Gitpod Desktop
2. Open your terminal and run: `echo "{\"quality\":\"insider\"}" > ~/Library/Gitpod/argv.json`
3. Launch Gitpod Desktop
4. Check for updates to install the latest version
5. Verify the installation by [checking your version](#checking-your-version). You should see "Insider" in the version information.

### Switching to Stable

To return to the stable version from Insiders, follow these steps:

1. Quit Gitpod Desktop
2. Open your terminal and run: `echo "{\"quality\":\"stable\"}" > ~/Library/Gitpod/argv.json`
3. Launch Gitpod Desktop
4. Check for updates to install the latest version
5. Verify the installation by [checking your version](#checking-your-version). You should not see "Insider" in the version information.

To switch back to the stable version, you must wait for a newer stable release to become available, as Gitpod Desktop does not support downgrading to previous versions.

To revert to a previous stable version:

1. [Uninstall](#uninstall) your current version of Gitpod Desktop
2. If experiencing compatibility issues, perform a [clean uninstall](#clean-uninstall)
3. [Setup](#setup) Gitpod Desktop again

## Uninstall

To uninstall Gitpod Desktop, select "Help" > "Troubleshooting" > "Uninstall" from the menu bar.
This action removes both the local runner and the application.
For a complete removal of all Gitpod Desktop data, including local environments and settings, perform a [clean uninstall](#clean-uninstall).

### Clean Uninstall

<Warning>
  {' '}

  Performing a clean uninstall will remove all Gitpod Desktop data, including your
  local environments and settings.{' '}
</Warning>

1. Begin by [resetting Gitpod Desktop data](#reset-data).
2. When Gitpod Desktop restarts, do not proceed with the installation. Instead, [uninstall](#uninstall) the application.

## Troubleshooting

### Report Issue

If you encounter any issues:

1. Ensure you are [up-to-date](#updating).
2. Restart Gitpod Desktop, as some errors may be temporary.
3. If you don't have any sensitive local environments, try to [reset the data](#reset-data). This can sometimes resolve issues.
4. If the issue persists, collect diagnostics using "Help" > "Troubleshooting" > "Collect Logs and Diagnostics". Review them for system-specific problems.
5. Start a support chat with us using the bubble icon in the bottom right corner of the application. If it's not available in Gitpod Desktop, use Gitpod from the browser.
   <Frame caption="Report Issue">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/report_issue.png" />
   </Frame>
6. Describe what happened, what you did, and what you expected. Upload the logs and diagnostics, and include any relevant screenshots.

<Warning>
  {' '}

  Be cautious when sharing logs online, as they may contain sensitive information.{' '}
</Warning>

### Reset Data

Resetting data permanently removes all Gitpod Desktop data, including local environments and user settings.
This action is helpful when Gitpod Desktop is not functioning correctly or when you want to start with a clean installation.

To reset data, select "Help" > "Troubleshooting" > "Reset and Restart" from the menu bar.

### Runner Installation Failure

If you encounter installation errors:

1. Check the error message details
2. Make any required system adjustments
3. Restart the installation process
4. If problems continue, [submit an issue report](#report-issue)

<Frame caption="Installation Failure">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/installation_failure.png" />
</Frame>

### Switching Accounts

To switch to a different Gitpod account, follow these steps:

1. Logout from Gitpod Desktop
2. Logout from your current Gitpod account in your default browser
3. Launch Gitpod Desktop and complete the authentication process with your new account credentials
4. If problems continue, [submit an issue report](#report-issue)

### Invalidate Git Authentication

If you're experiencing Git authentication issues, try these steps:

1. Verify if you are using a Personal Access Token (PAT) for runner authentication in `Settings` > `Git Authentication`.
2. If using PAT, invalidate it by clicking `Remove`. Remember to also revoke the PAT in your source control provider, e.g. GitHub.
   <Frame caption="Invalidate PAT">
     <img src="https://www.gitpod.io/images/docs/flex/desktop/git_auths.png" />
   </Frame>
3. If not using PAT, verify your Git credentials by attempting to clone the repository on your local machine. Update credentials if authentication fails.
4. Restart your local environment to apply the changes.

### Unexpected Runner Failure

If your runner unexpectedly fails:

1. Check the error message for specific details
2. Restart Gitpod Desktop to attempt automatic recovery
3. If the issue persists, try [resetting the data](#reset-data)
4. If problems continue, [submit an issue report](#report-issue)

<Frame caption="Unexpected Runner Failure">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/unexpected_failure.png" />
</Frame>


# Browser Extension
Source: https://www.gitpod.io/docs/gitpod/integrations/browser-extension



The browser extension adds a Gitpod button to GitHub, GitLab, Bitbucket and Azure DevOps repository interfaces, whether managed or self-hosted to allow you to quickly create environments.

<Frame caption="The Gitpod button on a GitHub repository, created by the browser extension">
  <img src="https://www.gitpod.io/images/docs/browser-extension-repo.png" />
</Frame>

**Caption:** The Gitpod button shown on a GitHub repository, created by the browser
extension

<br />

The extension is available for the following browsers:

1. [Chrome](https://chromewebstore.google.com/detail/gitpod/dodmmooeoklaejobgleioelladacbeki) (including Edge, Brave and other Chromium-based browsers)
2. [Firefox](https://addons.mozilla.org/firefox/addon/gitpod/)

## Access the extension settings

You can access the extension settings by clicking on the Gitpod icon in the browser toolbar. In the resulting popup you can find a comprehensive view of all possible customization.

<img className="shadow-medium w-full rounded-xl max-w-3xl mt-x-small" alt="Gitpod browser extension configuration in Google Chrome" src="https://www.gitpod.io/images/docs/browser-extension-settings.webp" />

## Enabling the browser extension on self-hosted SCM providers (e.g. GitLab CE/EE and Bitbucket Datacenter)

By default, the browser extension automatically is automatically enabled for the domains of GitHub (`github.com`), GitLab (`gitlab.com`) and Bitbucket (`bitbucket.org`) and Azure DevOps (`dev.azure.com`). If the `run on all sites` option is disabled, all other domains must be configured manually.

To add a custom SCM domain, open the Gitpod extension's context menu. Opening the context menu can be achieved by either right clicking the extension icon in the browser toolbar or revealing it by clicking on a kebab menu \[Chrome] / cog wheel \[Firefox] in the extensions dropdown.

| Chrome                                                                                                              | Firefox                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| ![Screenshot of the context menu in Chrome](https://www.gitpod.io/images/docs/browser-extension/chrome-context.png) | ![Screenshot of the context menu in Firefox](https://www.gitpod.io/images/docs/browser-extension/firefox-context.png) |

## Use a custom Gitpod instance URL

If you are using a custom Gitpod instance (e.g., [Gitpod Enterprise](https://www.gitpod.io/contact/enterprise-self-serve)) you can still use the browser extension by configuring it with your instance URL.

After you've installed the extension, open its options (see chapter [Access the extension settings](#access-the-extension-settings)) and enter your custom Gitpod instance URL. Then, simply click "Save" and approve the browser's request for new permissions.

## Source Code

Gitpod's browser extension is open source, meaning that you can check out its [source code](https://github.com/gitpod-io/browser-extension).


# Gitpod CLI
Source: https://www.gitpod.io/docs/gitpod/integrations/cli



The Gitpod CLI is a powerful tool that allows you to interact with your Gitpod environments and manage your development workflow directly from the terminal. Whether you're starting new environments, managing existing ones, or configuring your workspace, the CLI provides a streamlined interface for all your Gitpod operations.

## Installation

Getting started with the Gitpod CLI is straightforward. You have two options:

### Option 1: Quick Install (UNIX Systems - macOS, Linux)

This one-line installation method works for macOS and Linux systems:

```bash
curl -o gitpod -fsSL "https://releases.gitpod.io/cli/stable/gitpod-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/\(arm64\|aarch64\)/arm64/')" && \
chmod +x gitpod && \
sudo mv gitpod /usr/local/bin
```

### Option 2: Direct Download

Choose the appropriate version for your system:

* macOS: [x86\_64](https://releases.gitpod.io/cli/stable/gitpod-darwin-amd64) | [arm64](https://releases.gitpod.io/cli/stable/gitpod-darwin-arm64)
* Linux: [x86\_64](https://releases.gitpod.io/cli/stable/gitpod-linux-amd64) | [arm64](https://releases.gitpod.io/cli/stable/gitpod-linux-arm64)
* Windows: [x86\_64](https://releases.gitpod.io/cli/stable/gitpod-windows-amd64.exe) | [arm64](https://releases.gitpod.io/cli/stable/gitpod-windows-arm64.exe)

After downloading, you'll need to:

1. Make the binary executable:

   ```bash
   chmod +x gitpod
   ```

   Move it to your PATH:

   ```bash
   sudo mv gitpod /usr/local/bin
   ```

<Note>
  {' '}

  **Note for macOS users:** When first running a downloaded binary, you may see
  a security warning.
</Note>

You can resolve this by either:
Approving the app in *System Settings* → *Privacy & Security*

Or removing the quarantine attribute via terminal:

```bash
xattr -d com.apple.quarantine gitpod
```

The binary's signature can be verified using:

```bash
codesign -v gitpod -vvv
```

### Verifying Download Integrity

For security, verify the integrity of your downloaded CLI binary using SHA256 checksums from our release manifest:

```bash
# Get the checksums for the current release
curl https://releases.gitpod.io/cli/stable/manifest.json -L
```

#### Verification Steps

1. **Get the expected checksum** for your platform:
   ```bash
   # Extract checksum for your platform (requires jq)
   curl -sL https://releases.gitpod.io/cli/stable/manifest.json | jq -r '.downloads["<platform>"].digest'

   # Examples:
   # macOS Intel:        .downloads["darwin-amd64"].digest
   # macOS Apple Silicon: .downloads["darwin-arm64"].digest  
   # Linux x86_64:       .downloads["linux-amd64"].digest
   # Windows x86_64:     .downloads["windows-amd64"].digest
   ```

2. **Calculate your file's checksum**:
   ```bash
   # macOS/Linux
   shasum -a 256 gitpod

   # Windows PowerShell
   Get-FileHash gitpod-windows-amd64.exe -Algorithm SHA256
   ```

3. **Compare the checksums** - they must match exactly.

<Note>
  **Security Warning:** If the checksums don't match, do not use the binary and re-download from the official source.
</Note>

#### Without jq

If you don't have `jq` installed, view the full manifest and manually find your platform's digest:

```bash
curl https://releases.gitpod.io/cli/stable/manifest.json -L
```

## Getting started with Gitpod CLI

### Authentication

The Gitpod CLI supports multiple authentication methods:

#### Automated Authentication (in Gitpod Environments)

When using the CLI in a Gitpod environment, it automatically authenticates using the environment's token. Check your authentication status:

```bash
gitpod whoami
```

The output shows your access level:

* `PRINCIPAL_ENVIRONMENT`: Limited access to current environment only
* Your username: Full access to all features and environments

#### Browser-based Authentication

```bash
gitpod login
```

This is the simplest method that will:

* Open your default browser for authentication
* Create a new context for your session
* Store your credentials securely

#### Personal Access Token Authentication

For headless environments or automation scenarios, you can authenticate using a [Personal Access Token](./personal-access-token):

```bash
gitpod login --token
```

You can also provide the token directly:

```bash
gitpod login --token "your-token-here"
```

#### Environment Variables

Set the `GITPOD_TOKEN` environment variable before logging in:

```bash
export GITPOD_TOKEN="your-token-here"
gitpod login
```

### CLI in Gitpod Environments

#### Pre-installed CLI

Every Gitpod environment comes with the CLI pre-installed as `gitpod`. The CLI is automatically authenticated with limited access to the current environment's context, allowing you to:

* Stop the current environment (`gitpod environment stop`)
* View environment logs (`gitpod environment logs`)
* Rebuild the development container (`gitpod devcontainer rebuild`)

#### Upgrading Environment Access

To access additional features like managing other environments or organization resources, you'll need to create a new, fully authenticated context:

1. From within your environment, run:

   ```bash
   gitpod login
   ```

2. After authentication, the new context will automatically activate, giving you access to:
   * All environment management commands
   * Organization settings
   * Project management
   * Automation controls
   * Secret management

Remember that this upgraded access persists only for the current environment session. You'll need to re-authenticate if you restart the environment.

### Access Levels and Authentication Scope

Depending on how you're logged in, you may have different access levels. You can always change your authentication method or scope using the `gitpod login` command.

#### Default Environment Access (Pre-authenticated)

* View current environment status
* Basic environment operations
* Local development container management
* Port forwarding

#### Full Authentication Access (After Login)

* Create and manage all environments
* Organization management
* Project creation and configuration
* Secret management
* Automation control
* Runner management
* Cross-environment operations

### Basic Commands

Here are some essential commands to get you started:

```bash
# View your user information
gitpod whoami

# List your environments
gitpod environment list

# Create a new environment
gitpod environment create <repository-url>

# Start an existing environment
gitpod environment start <environment-id>

# Stop an environment
gitpod environment stop <environment-id>

# Delete an environment
gitpod environment delete <environment-id>
```

### Machine-readable Output

For scripting and automation, you can get machine-readable output in JSON or YAML format:

```bash
gitpod environment list -o json
gitpod environment list -o yaml
```

## Core Features

### Environment Management

#### Creating Environments

```bash
gitpod environment create <repo-url> [flags]

# Common flags:
--class-id        # Specify environment class
--editor          # Choose your preferred editor
--interactive     # Use interactive mode
--set-as-context  # Set as active context
```

#### Working with Running Environments

```bash
# SSH into an environment
gitpod environment ssh <environment-id>

# View environment logs
gitpod environment logs <environment-id>

# List environment ports
gitpod environment port list

# Open a port
gitpod environment port open <port-number>

# List available editors
gitpod environment list-editors

# Open with an editor
gitpod environment open <environment-id> --editor <editor-name|editor-id>
```

### Automation Management

The CLI provides comprehensive automation management capabilities:

```bash
# Initialize new automation
gitpod automations init

# Update automations of an environment
gitpod automations update automations.yaml

# Update the default automation file of an environment
gitpod automations update -s .gitpod/automations.yaml

# List automation tasks
gitpod automations task list

# Start a task
gitpod automations task start <task-reference>

# View task logs
gitpod automations task logs <task-reference>

# List automation services
gitpod automations service list

# Start a task
gitpod automations service start <service-reference>

# View task logs
gitpod automations service logs <service-reference>
```

## Advanced Features

### SSH Configuration

Set up native SSH access to your environments:

```bash
gitpod environment ssh-config
```

After configuration, connect directly using:

```bash
ssh <environment-id>.gitpod.environment
```

### Project Management

```bash
# List projects
gitpod project list

# Get project details
gitpod project get <project-id>

# Create a new project
gitpod project create <repo-url>
```

### Port Management

```bash
# Open a port with a custom name
gitpod environment port open <port> --name "my-service"

# Close a port
gitpod environment port close <port>
```

### Context Management

```bash
# List available contexts
gitpod config context list

# Switch contexts
gitpod config context use <context-name>

# Modify context settings
gitpod config context modify <context-name>
```

### Global Configuration

The CLI configuration file is located at `~/.gitpod/configuration.yaml`. You can modify settings using:

```bash
gitpod config set [flags]

# Common configuration options:
--autoupdate        # Enable/disable automatic updates
--release-channel   # Set release channel (stable/latest)
--host              # Set Gitpod instance host
```

## Best Practices

1. **Context Management**

   * Use separate contexts for different projects or organizations
   * Name contexts meaningfully for easy identification

2. **Environment Lifecycle**

   * Stop unused environments to conserve resources
   * Use `--dont-wait` flags for batch operations
   * Set appropriate timeouts for long-running operations

3. **Automation**

   * Initialize automation files in your project root
   * Use descriptive task names
   * Monitor task logs for debugging

4. **Security**
   * Regularly rotate access tokens
   * Use environment-specific SSH keys
   * Keep the CLI updated for security patches

## Troubleshooting

Common issues and solutions:

### Authentication Issues

```bash
gitpod login --non-interactive  # For environments without browser access
gitpod login --token "<your-token>"  # Use a token directly
gitpod config context modify --token "<your-token>"  # Update token manually
```

### Connection Problems

```bash
gitpod environment logs --include-system-logs --raw # View detailed logs
gitpod environment ssh --verbose  # Debug SSH connections
ssh -vvv <environment-id>.gitpod.environment  # Debug SSH connections
```

### Too Many SSH Authentication Failures

If you encounter `too many authentication failures` when connecting to a Gitpod environment, it may be due to multiple SSH keys being offered by an agent (e.g., 1Password). The server rejects connections after six failed attempts.

**Solutions:**

1. Stop the SSH agent to prevent other keys from being offered.
2. Ensure only the CLI key is used by adding `IdentitiesOnly yes` to your `~/.ssh/gitpod/config` under the `Host *.gitpod.environment` section.

#### Testing:

Re-enable your SSH agent and test the connection:

```bash
ssh -vvv <environment-id>.gitpod.environment
```

Ensure the correct key (`Offering public key:`) is used.

## Shell Completion

Enable shell completion for easier CLI usage:

```bash
# Bash
gitpod completion bash > /etc/bash_completion.d/gitpod

# Zsh
gitpod completion zsh > "${fpath[1]}/_gitpod"

# Fish
gitpod completion fish > ~/.config/fish/completions/gitpod.fish

# PowerShell
gitpod completion powershell | Out-String | Invoke-Expression
```

## Updates and Maintenance

Keep your CLI up to date:

```bash
# Check version
gitpod version

# Update CLI
gitpod version update

# Force update (even if version is up-to-date)
gitpod version update --force
```

## Additional Resources

* Use `gitpod help` for comprehensive command documentation
* Add `-h` or `--help` to any command for specific usage information
* Use `--verbose` flag for detailed logging when troubleshooting
* Check the configuration file at `~/.gitpod/configuration.yaml` for custom settings

Remember that the CLI is constantly evolving with new features and improvements. Keep your installation updated and refer to the official documentation for the latest information.


# Gitpod URL
Source: https://www.gitpod.io/docs/gitpod/integrations/gitpod-url



You can open a Gitpod environment directly using a URL. The simplest way to start an environment is by using the format:

```
https://app.gitpod.io/#<repository-url>
```

This provides an alternative to creating environments with the [browser extension](/gitpod/integrations/browser-extension).

## URL Structure

The URL consists of the Gitpod instance URL followed by `#` and the full repository URL.

### Examples

* `https://app.gitpod.io/#https://github.com/gitpod-io/empty`
* `https://app.gitpod.io/#https://gitlab.com/gitpod-io/empty`
* `https://app.gitpod.io/#https://bitbucket.org/gitpod-io/empty`

## Choosing a Runner and Environment Class

When you open a repository in Gitpod, you will be prompted to choose a runner and environment class.

To configure a default for the environment class and runner for a repository, create a Project with your preferred configuration. When a project exists on a repository users in your organization are trying to open, it will be selected automatically.

## Next Steps

* Configure your [user settings](/gitpod/account/user-settings) to set default preferences such as your preferred editor
* Learn about [organization policies](/gitpod/organizations/policies) for team-wide configurations such as requiring users to use a project when creating an environment


# Overview
Source: https://www.gitpod.io/docs/gitpod/integrations/overview



Gitpod is designed to integrate with your existing development workflow and tools.

* [Port Sharing](/flex/integrations/ports): Learn how to expose ports from your Gitpod environment to the internet or just to team members, enabling easy access to web servers, databases, and other services running in your workspace.
* [Personal Access Tokens](/flex/integrations/personal-access-token): Discover how to generate and use personal access tokens to securely integrate Gitpod with headless systems and automate workflows.
* [CLI](/flex/integrations/cli): Learn how to use the Gitpod CLI to interact with your environment and manage your development workflow from the terminal.
* [Software Development Kits (SDKs)](/flex/integrations/sdk): Explore Gitpod's SDKs for programmatically interacting with Gitpod services and automating your development workflow.
* [Amazon Web Services (AWS)](/flex/integrations/aws): Discover how to integrate Gitpod with AWS using OpenID Connect (OIDC) for secure access to AWS resources.


# Personal Access Tokens
Source: https://www.gitpod.io/docs/gitpod/integrations/personal-access-token



Personal access tokens (PATs) provide a way to authenticate and authorize programmatic access to Gitpod. You can use PATs as an alternative to using your password for authentication when using the Gitpod CLI or API.

## Creating a PAT

To create a personal access token:

1. Go to [Personal access tokens in the settings](https://app.gitpod.io/projects#/settings/personal-access-tokens)
2. Click "New Token"
3. Enter a description for your token
4. Select an expiration period (30, 60, or 90 days)
5. Click "Create"
6. Copy the generated token immediately. For security reasons, you won't be able to see it again.

## Using a PAT

You can use a personal access token to authenticate with the Gitpod CLI:

```sh
gitpod login --token <your-token>
```

## Token Permissions

Personal access tokens currently have the same permissions as your user account. They cannot be scoped down to specific actions or resources.

## Managing PATs

You can view and manage your personal access tokens at [https://app.gitpod.io/projects#/settings/personal-access-tokens](https://app.gitpod.io/projects#/settings/personal-access-tokens).

From this page, you can:

* View existing tokens
* Create new tokens
* Remove/Revoke tokens

## Security Considerations

* Treat personal access tokens like passwords. Do not share them or store them in insecure locations.
* Use the shortest expiration period that meets your needs.
* Revoke tokens that are no longer needed.
* Actions performed using a PAT will be logged in the audit logs, referencing the token ID.

## Example Use cases for PATs

### CI/CD Integration

Use a PAT to authenticate your CI/CD pipeline with Gitpod. This allows your automated workflows to create, manage, or interact with Gitpod environments without requiring manual authentication.

Example:

```yaml
name: Gitpod Integration
on: [push]
jobs:
    create-environment:
    runs-on: ubuntu-latest
    steps:
        - name: Create Gitpod Environment
        env:
            GITPOD_TOKEN: ${{ secrets.GITPOD_PAT }}
            GITPOD_CLASS: some-class-id
        run: |
            gitpod login --token $GITPOD_TOKEN
            gitpod environment create --class-id $GITPOD_CLASS https://github.com/your-repo
```

### Scripted Environment Management

Write scripts to manage your Gitpod environments programmatically. This is useful for tasks like bulk operations or scheduled maintenance.

Example:

```python
import subprocess
import json

GITPOD_PAT = "your_personal_access_token"

def run_gitpod_command(*args):
    result = subprocess.run(
        ["gitpod"] + list(args),
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout.strip()

# Login to Gitpod CLI using PAT
run_gitpod_command("login", "--token", GITPOD_PAT)

# List all environments
environments_json = run_gitpod_command("environment", "list", "-o", "json")
environments = json.loads(environments_json)

# Stop all running environments
for env in environments:
    if env['status']['phase'] == 'ENVIRONMENT_PHASE_RUNNING':
        print(f"Stopping environment {env['id']}")
        run_gitpod_command("environment", "stop", env['id'])

print("All running environments have been stopped.")
```

### Third-Party Tool Integration

Integrate Gitpod with third-party development tools or services that need to access your Gitpod account. The PAT allows these tools to authenticate and perform actions on your behalf using the Gitpod CLI.

Example (using a hypothetical code review tool):

```python
import subprocess
from code_review_tool import CodeReviewClient

# Initialize code review client
cr_client = CodeReviewClient(api_key="code_review_api_key")

# Gitpod PAT
GITPOD_PAT = "your_gitpod_pat"

# When a new code review is created
def on_new_review(review):
    # Login to Gitpod CLI using PAT
    subprocess.run(["gitpod", "login", "--token", GITPOD_PAT], check=True)

    # Create a Gitpod environment for the review
    result = subprocess.run(
        ["gitpod", "environment", "create", review.repo_url, "--dont-wait"],
        capture_output=True,
        text=True,
        check=True
    )

    # Extract the environment ID from the CLI output
    env_id = result.stdout.strip()

    # Get the environment details
    result = subprocess.run(
        ["gitpod", "environment", "get", env_id, "-o", "json"],
        capture_output=True,
        text=True,
        check=True
    )

    import json
    env_details = json.loads(result.stdout)

    # Add the Gitpod environment URL to the review
    cr_client.add_comment(review.id, f"Gitpod environment: {env_details['url']}")
```


# Port sharing
Source: https://www.gitpod.io/docs/gitpod/integrations/ports



Port sharing allows you to expose HTTP ports from your running Gitpod environment to the internet, enabling easy sharing and collaboration. This feature is available for cloud-hosted Gitpod environments not Gitpod Desktop environments.

## How it works

When you share a port, Gitpod creates a public URL with automatic TLS termination. This allows secure access to your application or service running inside the Gitpod environment.

### Limitations

* Only HTTP traffic is supported.
* Not available on Gitpod Desktop environments.
* Subject to Gitpod's fair use policies and bandwidth limits.

### Prerequisites

To ensure port sharing works correctly, services must:

* listen on `0.0.0.0` instead of `localhost` or `127.0.0.1`
* be exposed from the Dev Container on the virtual machine using [the host network stack](/flex/configuration/devcontainer/getting-started#host-network-stack).

For example, if you're running a Node.js server, make sure to bind it to `0.0.0.0` instead of `localhost`.

```javascript
const app = express();
app.listen(3000, '0.0.0.0', () => {
	console.log('Server is running on port 3000');
});
```

### Security considerations

While port sharing is convenient, it's important to be mindful of security:

* Only share ports when necessary and unshare them when you're done.
* Be cautious about sharing ports running sensitive services or containing confidential data.
* Remember that shared URLs are public and potentially accessible by anyone with the link.

## Sharing ports

There are two ways to share ports from your Gitpod environment:

### Using the UI

In the Gitpod UI, you'll see a section labeled "Public Ports" that allows you to manage port sharing for your environment.

To share a new port:

1. Click the "Open Port" button in the "Public Ports" section.
2. A dialog will appear titled "Open a public port".
3. Enter a name for the port (optional) and the port number you wish to share.
4. Click "Open Port" to confirm.

For ports that are already open:

They will be listed in the "Public Ports" section. Each open port will show its name (if given) and port number. A green indicator next to the port signifies it's currently active and accessible.

<Warning>
  {' '}

  **Security notice**: When you open a port, it will be available on the open internet.
  Be careful when sharing the URL.
</Warning>

This interface provides an easy way to manage which ports are exposed from your Gitpod environment, allowing you to quickly share access to services or applications you're running.

### Using the CLI

Gitpod provides a set of CLI commands to manage port sharing. These commands allow you to list, open, and close ports directly from your terminal.

#### Listing ports

To view all currently open ports:

```
gitpod environment port list
```

This command will display a list of all ports that are currently open and available for sharing.

#### Opening a Port

To open and share a new port:

```
gitpod environment port open 3000 --name my-app
```

#### Closing a Port

To close a previously opened port:

```
gitpod environment port close <port-number>
```

For example, to close port 3000:

```
gitpod environment port close 3000
```

#### Examples

1. Open a port for a web server:

   ```
   gitpod environment port open 8080 --name webserver
   ```

2. Open a port for an API server:

   ```
   gitpod environment port open 4000 --name api
   ```

3. List all open ports:

   ```
   gitpod environment port list
   ```

4. Close a port that's no longer needed:
   ```
   gitpod environment port close 4000
   ```

These CLI commands provide a quick and efficient way to manage port sharing directly from your terminal, especially useful for scripting or when you prefer command-line interactions.

## Use cases

Port sharing enables various scenarios that enhance development workflows and collaboration:

1. Demonstrating work-in-progress: Quickly share your application with teammates or clients without deploying to a staging environment.

2. API testing: Expose your local API server to test integrations with external services or mobile apps.

3. Collaborative debugging: Share a running application with a colleague to troubleshoot issues together in real-time.

4. Design reviews: Make your local development server accessible so designers can review and provide feedback on UI changes.

5. Webhooks development: Test webhook integrations by exposing your local server to receive real-time events from external services.


# Gitpod SDK
Source: https://www.gitpod.io/docs/gitpod/integrations/sdk



The Gitpod SDK provides powerful tools for developers to interact programmatically with Gitpod environments. It allows you to automate environment creation, run tasks, manage automations, and scale infrastructure with Gitpod runners. Available in Python, Node/Typescript, and Go, the SDK gives developers flexibility in their choice of language.

### SDKs Available

* **[Python SDK](https://pypi.org/project/gitpod-sdk/)**: For Python developers interacting with Gitpod environments.
* **[Node/Typescript SDK](https://www.npmjs.com/package/@gitpod/sdk)**: For JavaScript and TypeScript developers.
* **[Go SDK](https://github.com/gitpod-io/gitpod-sdk-go)**: For Go developers integrating with Gitpod.

For detailed API references, consult the [Gitpod API Reference](https://www.gitpod.io/docs/api-reference).

## End-to-End Walkthrough

Watch the video below to see an end-to-end walkthrough of how to use the Gitpod SDK. The steps below are based on the video.

<div className="mux-player-container" data-playback-id="qY6SHjCM4mU76W45NtOmf7tiZ6ZMACY4whYe59blaUc" data-title="Gitpod SDK" />

<br />

### 1. **Sign Up at Gitpod**

* Go to [app.gitpod.io](https://app.gitpod.io) and sign up for a Gitpod account.
* Once logged in, generate a **Personal Access Token** for SDK authentication under your account settings at [Gitpod Personal Access Tokens](https://app.gitpod.io/settings/personal-access-tokens).

### 2. **Install the SDK**

You need to install the Gitpod SDK for your preferred language. Here’s how to do it for the three SDKs:

* **Python SDK**:
  ```bash
  pip install gitpod-sdk
  ```
* **Node/Typescript SDK**:
  ```bash
  npm install @gitpod/sdk
  ```
* **Go SDK**:
  ```bash
  go get github.com/gitpod-io/gitpod-sdk-go
  ```

### 3. **Authenticate with Gitpod**

Once you’ve installed the SDK, authenticate using your personal access token. You can either set it via the environment variable or explicitly pass it in your code.

* **Option 1**: Set the environment variable `GITPOD_API_KEY`:

  ```bash
  export GITPOD_API_KEY="your_token_here"
  ```

* **Option 2**: Authenticate directly in your code:

  * **For Python SDK**:

    ```python
    from gitpod_sdk import Gitpod

    gitpod = Gitpod(bearer_token="your_token_here")
    ```

  * **For Go SDK**:

    ```go
    package main

    import (
        "github.com/gitpod-io/gitpod-sdk-go"
    )

    func main() {
        gitpod := gitpod.NewGitpod("your_token_here")
    }
    ```

  * **For Node/Typescript SDK**:

    ```typescript
    import { Gitpod } from '@gitpod/sdk';

    const gitpod = new Gitpod({ bearerToken: 'your_token_here' });
    ```

### 4. **Run an Example**

Once authenticated, you can start experimenting with the SDK by running one of the examples. Here’s an example of how to create an environment and run a command inside it using the Python SDK:

```python
import asyncio
from gitpod import AsyncGitpod
import gitpod.lib as util

repo_url = "https://github.com/containerd/containerd"
command_to_execute = "go test -v -short ./..."

async def execute_command_in_environment():
    client = AsyncGitpod()

    machine_class_id = (await util.find_most_used_environment_class(client)).id

    create_params = {
        "machine": {"class": machine_class_id},
        "content": {"initializer": {"specs": [{"context_url": {"url": repo_url}}]}}
    }

    environment = (await client.environments.create(spec=create_params)).environment

    await util.wait_for_environment_running(client, environment.id)

    async for line in await util.run_command(client, environment.id, command_to_execute):
        print(line)

    await client.environments.delete(environment_id=environment.id)

if __name__ == "__main__":
    asyncio.run(execute_command_in_environment())
```

This example demonstrates:

* Creating a new environment initialized from a Git repository.
* Running a command inside the environment.
* Deleting the environment once the task is completed.

## Available Examples

Here are the available examples in the SDK repositories, with descriptions of what they demonstrate:

### 1. **Run a Command in an Environment**

* **Description**: Demonstrates how to initialize an environment from a Git repository and run a command inside it.
* **Location**: [Python SDK Example - Run Command](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/examples/run_command.py)

### 2. **Run a Service in an Environment**

* **Description**: Demonstrates how to run a long-lived service (such as a database or message queue) inside a Gitpod environment.
* **Location**: [Python SDK Example - Run Service](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/examples/run_service.py)

### 3. **Access the File System in an Environment**

* **Description**: Shows how to access and interact with the file system inside a Gitpod environment programmatically.
* **Location**: [Python SDK Example - File System Access](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/examples/fs_access.py)

### 4. **Use the Anthropic Tool in a Gitpod Environment**

* **Description**: Demonstrates how to use the Anthropic tool within a Gitpod environment and interact with the **Model Context Protocol (MCP)**.
* **Location**: [Python SDK Example - Anthropic Tool Use](https://github.com/gitpod-io/gitpod-sdk-python/tree/main/examples/anthropic_tool_use.py)

### 5. **MCP Server Example**

* **Description**: Demonstrates the integration of the **Model Context Protocol (MCP)** in a Gitpod environment, used for managing model contexts.
* **Location**: [Go SDK Example - MCP Server](https://github.com/gitpod-io/gitpod-sdk-go/tree/main/examples/mcp-server)


# Automations
Source: https://www.gitpod.io/docs/gitpod/introduction/automations



Automations enable programmable tasks and services that integrate directly into your development environment. They let you create self-service actions for various development workflows:

* **Setup**: Seed databases, provision infrastructure, or authenticate with cloud accounts
* **Operations**: Transform runbooks into one-click self-service actions
* **Editor interfaces**: Start servers such as Jupyter notebooks
* **Policies**: Execute security or scanning tools
* **AI workflows**: Configure AI agents or code assistants

<Frame caption="Environment details with Automations">
  <img src="https://www.gitpod.io/images/docs/flex/introduction/environment-details.png" />
</Frame>

## Configuration

Automations are defined in a YAML file located at `.gitpod/automations.yaml` in your repository. This file can live alongside your source code, in another repository, or any location accessible from the development environment.

Automations are organized into two categories:

* **Services**: Long-running processes that provide functionality to your environment
* **Tasks**: One-off commands that perform specific actions

## Example Configuration

Here's a simple example of an Automations configuration file:

```yaml
services:
    database:
        name: PostgreSQL
        commands:
            start: docker run postgres
tasks:
    run-unit-tests:
        name: Runs unit tests
        command: go test -v ./...
```

## Triggering Automations

Automations can be triggered in three ways:

1. **Manually through the UI**: Click on the automation in the Gitpod interface
2. **Via command line**: Execute automations using the CLI
3. **Automatically**: Trigger based on environment lifecycle events (e.g., when a Dev Container starts)

Each automation type has a corresponding UI element in the Gitpod interface, making them easily discoverable and accessible.

## Access Control

Anyone with access to an environment can create and run automations within that environment. Administrators cannot access other users' environments and therefore cannot create or run automations in those environments.

See the [examples](/flex/configuration/automations/examples) section for more detailed use cases and implementation patterns for Automations.


# Development Containers
Source: https://www.gitpod.io/docs/gitpod/introduction/devcontainer

Development Containers (or Dev Containers) allow you to use a container as a full-featured development environment. It can be used to run an application, separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud, in a variety of supporting tools and editors.

# Development Containers

<Info>
  {' '}

  "A Development Container (or Dev Container for short) allows you to use a container
  as a full-featured development environment. It can be used to run an application,
  separate tools, libraries, or runtimes needed for working with a codebase, and
  to aid in continuous integration and testing. Dev containers can be run locally
  or remotely, in a private or public cloud, in a variety of supporting tools and
  editors." - [containers.dev](https://containers.dev/)
</Info>

Gitpod offers seamless support for [Dev Containers](https://containers.dev/), allowing you to standardize and automate your development environment across teams and projects. By defining your environment in a devcontainer.json file, Gitpod ensures that everyone on your team works with the same configuration, regardless of their local setup.

## Configuration Locations

Gitpod will automatically detect your Dev Container configuration in standard locations:

* `.devcontainer/devcontainer.json`
* `.devcontainer.json`

You can also specify custom paths when configuring Projects through the Gitpod UI.

## Image build caching

Gitpod provides efficient Docker image build caching on a per-project basis to optimize development workflows and reduce build times. This caching mechanism stores built images securely and reuses them across environments, significantly speeding up workspace creation.

### How it works

When you start a new workspace, Gitpod follows an intelligent caching strategy:

1. **Check for cached image**: First looks for a previously built image that matches your devcontainer configuration
2. **Pull from cache**: If found, pulls the cached image instead of rebuilding from scratch
3. **Build and cache**: If no cache exists, builds the image and stores it for future use
4. **Automatic management**: Cached images are automatically managed and cleaned up over time

### Key features

* **Project-Based Caching**: Images are cached per project, ensuring team members benefit from shared builds
* **Security & Isolation**: Each project has its own secure cache, preventing cross-project access
* **Automatic Operation**: Works transparently without requiring any configuration
* **Docker Layer Optimization**: Reuses Docker layers efficiently to minimize storage and transfer time

The caching system is particularly effective for teams working with similar devcontainer configurations, where subsequent workspace launches can be significantly faster by leveraging previously built images.

## Integration with Automations

Building on Dev Containers, Gitpod adds a powerful framework for running [Automations](/flex/introduction/automations) in your development environments. While Dev Containers define your base environment, we recommend using Automations instead of Dev Container lifecycle commands for setup tasks and workflows.

Automations allow you to set up self-service actions like seeding databases, automating testing, managing external infrastructure lifecycle, or launching AI assistants securely within your development environment.

## Example Dev Container

```json
{
	"name": "Node.js Dev Container",
	"image": "mcr.microsoft.com/devcontainers/javascript-node:18",
	"customizations": {
		"vscode": {
			"extensions": ["dbaeumer.vscode-eslint"]
		}
	}
}
```

{/* For detailed information about Dev Container configuration options, best practices, migration from Gitpod Classic, and troubleshooting, see our [Dev Containers Guide](/flex/reference/dev-containers). */}


# Editors & IDEs
Source: https://www.gitpod.io/docs/gitpod/introduction/editor



Gitpod development environments are accessible through your preferred editor or CLI. You can connect your favorite code editor to Gitpod environments, allowing you to work in a familiar interface while leveraging Gitpod's cloud infrastructure.

## Connecting Your Editor

Gitpod supports multiple ways to connect your editor to development environments:

* **Direct Launch**: VS Code, VS Code Browser, Cursor, and JetBrains IDEs can be launched directly from the Gitpod user interface. Use the "Open in VS Code" button for VS Code, or buttons like "Open IntelliJ IDEA Ultimate" for JetBrains IDEs.

* **SSH Configuration**: Editors like Zed can connect via SSH. Simply run `gitpod env ssh-config` to set up the SSH configuration for your environment.

Gitpod works with any editor that supports SSH connections to remote backends, giving you flexibility to use your preferred development tools.

## Supported Editors

Gitpod officially supports these editors:

* **VS Code**: Launches directly from the Gitpod interface with required extensions automatically installed
* **VS Code Browser**: Launches directly in the Browser without the need to install additional tools
* **Cursor**: Similar to VS Code with direct integration through the Gitpod interface
* **JetBrains IDEs**: Connect through JetBrains Toolbox
* **Zed**: Connect using SSH configuration

## Prerequisites

Each editor has specific requirements:

* **VS Code/Cursor**: Requires extensions (Gitpod, Remote-SSH, Dev Containers) which are automatically installed when launching from Gitpod
* **JetBrains IDEs**: Requires [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/) installed
* **SSH-based editors**: Requires running `gitpod env ssh-config` to configure the connection

See [the integrations](/flex/editors) page for detailed setup instructions for each supported editor.


# Overview
Source: https://www.gitpod.io/docs/gitpod/introduction/overview



<Note>
  Looking for **Gitpod Classic** documentation? [Take me there](/classic/user/introduction/overview)
</Note>

<Frame caption="Gitpod dashboard">
  <img src="https://www.gitpod.io/images/gitpod-app-screenshot.webp" />
</Frame>

# What is Gitpod?

Gitpod is a **zero-trust platform** that provides automated and standardized development environments **in your own infrastructure**—whether on your local machine, in your cloud account (VPC), or on-prem. It streamlines coding workflows and boosts collaboration by letting teams **spin up secure, preconfigured dev environments** quickly and consistently.

## High-Level Overview

* **Run in Your Cloud or VPC**: Deploy Gitpod in your preferred environment — AWS, on-prem servers, or via a local desktop app.
* **Consistent Environments**: Use Dev Containers to ensure every environment has the same dependencies, tools, and configurations.
* **Automations**: Automate tasks like DB seeding, environment setup, or testing.
* **Zero-Trust Architecture**: Keep code and secrets in your cloud; you control access.
* **Scalable**: Expand across multiple infrastructure footprints or keep it lightweight for smaller teams.

## Key Benefits for CTOs & Engineering Leaders

* **Security & Compliance**

  * Gitpod cannot access your source code or credentials, they all remain private and under your control.
  * Centralized security policies, single sign-on, and advanced compliance.
  * Full audit logs to track environment and user actions.

* **Flexible Cost & Infrastructure**

  * Host dev environments where it makes sense—in your private VPC, existing cloud accounts, or local resources.
  * Seat-based pricing for predictable budgeting, plus the option to use your own infrastructure investments.

* **Accelerated Onboarding & Collaboration**
  * New devs can start coding in minutes—no manual install or environment setup.
  * Shared, prebuilt project configurations eliminate "works on my machine" issues.
  * Multiple dev environments can run side by side for different tasks.

## Key Benefits for Developers & Engineers

* **Instant, Ready-to-Code Environments**

  * Dev Containers handle language runtimes and build tools automatically.
  * Automations run tasks (build, test, seed DB) on environment startup.

* **Code From Anywhere**

  * Launch an environment on your laptop, or in your VPC with powerful cloud servers.
  * Switch seamlessly between local resources and your organization's infrastructure.

* **Reduced Context Switching**

  * Keep separate environments for each feature branch or bug fix.
  * Easily revert to a clean environment without reinstalling dependencies.

* [Runners](/gitpod/introduction/runners)

* [Dev Container](/gitpod/introduction/devcontainer)

* [Automations](/gitpod/introduction/automations)

* [Zero-trust](/gitpod/introduction/zero-trust)

* [Editor](/gitpod/introduction/editor)


# Runners
Source: https://www.gitpod.io/docs/gitpod/introduction/runners



Runners are flexible orchestrators of remote development environments that operate within your infrastructure. This "bring your own cloud" model provides you with complete control over where your development environments run while Gitpod manages the administration complexity.

## What are Runners?

Runners are responsible for key operational tasks within your infrastructure:

* Environment provisioning and scaling
* Backup management
* Local caching
* Source code management (SCM) integration
* Environment security

While runners operate in your infrastructure, they connect to Gitpod's management plane, which handles user authentication, identity management, and runner coordination. This hybrid approach gives you data control without the operational burden.

## Runner Types

Gitpod offers multiple runner options to fit your infrastructure needs:

1. **AWS Runner**

   * Deployed in your AWS account via CloudFormation
   * Supports horizontal scaling up to 400 concurrent environments
   * Minimal base cost (approximately \$8/month, often covered by AWS free tier)
   * Available in any AWS region or availability zone
   * Support for GPU-enabled environments

2. **Linux Runner**

   * Runs directly on your Linux machine with AMD64/x86\_64 architecture
   * Supports up to 10 concurrent environments
   * Provides direct local network access
   * Requires hardware virtualization support (KVM)

3. **Gitpod Desktop**
   * Run Dev Containers locally with built-in Linux virtualization
   * No infrastructure costs—everything runs locally
   * Currently available for Apple silicon users

## Runner Architecture

Runners work in conjunction with the Gitpod management plane:

* **Management Plane** (hosted by Gitpod): Handles database, SSO, identity management, user management, and runner coordination
* **Runner** (in your infrastructure): Manages environment provisioning, SCM authentication, and SCM context parsing
* **Environments** (created by runners): Provide security boundaries, secrets resolution, and automations execution

## Key Benefits

* **Infrastructure control**: Keep sensitive code and data within your own infrastructure
* **Private networking**: Access internal resources without exposing them to the public internet
* **Geographical flexibility**: Deploy runners close to your team to minimize latency
* **SCM integration**: Connect to private repositories on GitHub, GitLab, Bitbucket, or Azure DevOps
* **Resource optimization**: Use your own cloud resources and leverage committed spend
* **Team sharing**: Runners are shared across developers in your organization
* **Multiple deployment options**: Run as many runners as needed in different regions or availability zones

## Administration

* Runners require admin role in your Gitpod organization to create or modify
* Runners update automatically approximately once per week with no downtime
* Runners can be monitored using Prometheus
* Connection between users and environments is direct, secured with SSH keys
* Each runner can support up to 400 concurrent environments with no limit on total users

Organizations can deploy multiple runners across different regions and even mix runner types to best support global teams, data sovereignty requirements, and specific workloads.

For specific setup instructions, refer to the runner-specific documentation sections:

* [AWS Runner Setup](/flex/runners/aws)
* [Linux Runner Setup](/flex/runners/linux)
* [Gitpod Desktop](/flex/gitpod-desktop)


# Zero-trust environments
Source: https://www.gitpod.io/docs/gitpod/introduction/zero-trust



With Gitpod your source code, secrets, and internal network are isolated within your network perimeter. Gitpod's architecture is deployed in your infrastructure, providing full control over networking setup.

## How zero-trust principles protect your environments

Gitpod's architecture adheres to core zero-trust principles:

* **No implicit trust** — No user, device, or network is automatically trusted, whether inside or outside your architectural perimeter
* **Least privilege access** — Each component only has access to the resources it needs to function
* **Continuous validation** — Every request is authenticated, authorized, and validated before granting or maintaining access
* **Comprehensive identity model** — All actions are tied to specific identities (users, environments, runners, or accounts)

## Architecture that keeps you in control

Gitpod consists of two main components:

* **Management plane** (hosted by Gitpod) — Handles authentication, administrative functions, and policy management
* **Runners** (deployed in your VPC or "bring your own cloud") — Orchestrate development environments while keeping sensitive assets within your network boundaries

<Frame caption="Gitpod Architecture">
  <img src="https://www.gitpod.io/images/docs/flex/introduction/flex-architecture.png" />
</Frame>

{/* <!-- Insert architecture diagram showing security boundaries */}

## Data residency and compliance

Environments can be deployed across supported regions in AWS or on Linux machines:

* **AWS US regions**: `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`
* **AWS APAC regions**: `ap-southeast-1`, `ap-southeast-2`, `ap-northeast-1`
* **AWS EU regions**: `eu-west-1`, `eu-central-1`
* **AWS Other regions**: `sa-east-1`, `ca-central-1`

This flexibility helps organizations meet data residency requirements and compliance needs. Gitpod is SOC 2 Type 2 compliant.

## Comprehensive security audit trail

Every create/write/update operation on the management plane is logged through a centralized logging system, providing a comprehensive audit trail accessible via API. This enables:

* Complete visibility into all system activities
* Ability to trace any action back to a specific identity
* Support for compliance and security investigations

## Secret management

Gitpod's secret management system offers comprehensive encryption to protect your sensitive data:

* **Industry-standard encryption** — Secrets are encrypted using AES256-GCM at rest in the database
* **Multi-layered protection** — The database is additionally secured with AWS RDS encryption
* **Zero access by Gitpod** — Gitpod employees do not have access to encryption keys and cannot decrypt your secrets

Secrets can be configured as:

* **Files** — Mounted in the environment at a path of your choosing (recommended for sensitive data)
* **Environment Variables** — Accessible as standard environment variables

Files are recommended for sensitive information as they avoid common security issues with environment variables such as process visibility, logging exposure, and unintended inheritance by child processes.

Secrets are configured at the project level and automatically made available to environments launched from that project.

## Learn more

For a deeper technical dive into Gitpod's zero-trust architecture, including how identities are attested and how multi-tenancy is implemented, read our [blog post on building a zero-trust architecture for cloud development environments](https://www.gitpod.io/blog/how-we-built-it-zero-trust-architecture).


# Create or join an organization
Source: https://www.gitpod.io/docs/gitpod/organizations/create-organization



If you're signing in for the first time, Gitpod will prompt you to create a new organization, where you'll automatically be the *admin*.

## Create a new organization

When creating a new organization, you need to specify its name. You can change the name later in the Settings.

Select the option 'Anyone with a “*yourdomain.org*” domain can join' to allow users with the same email domain to join when they sign up.

<Frame caption="Create organization">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/create-organization.png" />
</Frame>

## Join an organization

If other users have already created organizations that allow you to join, you'll see a list of them. You can select 'Join' to become a *member* of one of those organizations.

<Frame caption="Join organization">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/join-organization.png" />
</Frame>

<Frame caption="Join organization menu">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/join-organization-menu.png" />
</Frame>

You can access the `Join or create an organization` dialog from the account drop-down menu at any time.


# Environment inventory
Source: https://www.gitpod.io/docs/gitpod/organizations/environment-inventory



This settings page allows you, as the admin of the current organization, to view all environments within the organization. You can see details such as the owner, project, runner, and status of each environment. Use the filters at the top of the page to find the specific data you're looking for.

<Frame caption="Active Environments">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/active-environments.png" />
</Frame>

In the Danger Zone, you'll find options to stop or delete any environment in your organization. Select the appropriate option from the drop-down menu.

<Frame caption="Active Environments options">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/environment-options.png" />
</Frame>


# Insights
Source: https://www.gitpod.io/docs/gitpod/organizations/insights



## Overview

Insights provide organization administrators with powerful analytics to track environment usage across their organization. This feature helps identify usage patterns, optimize cloud infrastructure costs, and monitor adoption across teams.

<Frame caption="Insights">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/insights.webp" />
</Frame>

Available exclusively for organizations on the **Enterprise** billing tier, Insights offers detailed metrics on environment usage, active users, and resource consumption.

## Key Benefits

* **Usage Analysis**: Track environment runtime hours across projects and users
* **Cost Optimization**: Identify opportunities to reduce cloud infrastructure expenses
* **Adoption Monitoring**: Measure user engagement and feature adoption

## Accessing Insights

Insights are available to all administrator users of organizations on the Enterprise billing tier.

1. Navigate to [https://app.gitpod.io](https://app.gitpod.io)
2. Select **Insights** from the left navigation menu

## Using the Insights Dashboard

### Time Range Selection

The Insights dashboard allows you to select different time ranges to analyze your data:

* Last Day
* Last Week
* Last 14 Days
* Last Month
* Last 6 Months
* Last Year

### Available Metrics

The Insights dashboard provides several key metrics:

#### Active Users

Shows the number of unique users who started at least one environment during the selected time period. Includes:

* Weekly active users: Users with at least one started environment in the previous 7 days
* Weekly active users w/2+ days: Users with environments started on two or more different days in the past 7 days

<Note>
  The "Last Day" view is not available for weekly active user statistics, as
  these metrics require daily aggregation.
</Note>

#### Environments

Displays the total number of environments started during the selected period.

#### Total Time

Shows the accumulated environment runtime hours for the selected period. Environment runtime is calculated from the time an environment was started until it finished stopping.

### Detailed Views

The dashboard includes three detailed sections:

1. **Most Active Users**

   * Lists users with the highest environment usage time
   * Shows total runtime hours per user

2. **Top Projects**

   * Ranks projects by total environment usage time
   * Helps identify which projects consume the most resources

3. **Top Environment Classes**
   * Displays resource consumption by environment class (Large, Regular, etc.)
   * Helps identify optimal environment configurations for cost management
   * Aggregates all local runners for easier comparison with shared remote runners

## Frequently Asked Questions

### Will I be able to view data from before I upgraded my organization to Enterprise?

Yes, you will be able to view all environment usage data after May 16, 2025, regardless of what tier your organization was on before you upgraded.

### Does this include my deleted environments?

Yes, environment usage data is unaffected by changes made to their corresponding environments. Data for deleted environments is still included in your Insights.

### How far back does the data go?

Currently, Insights data is available from May 16, 2025, onwards.

## Limitations

* Time granularity is automatically selected based on the time range and cannot be manually adjusted (e.g. it's currently impossible to view hourly data for the last week)


# Manage members
Source: https://www.gitpod.io/docs/gitpod/organizations/manage-members



As an admin of your organization, you can manage the organization's members. This includes:

* Changing a member's role.
* Removing members from the organization.
* Inviting teammates by generating invite links.

You can also view any user's environments by selecting 'View Environments' from the drop-down menu.

<Frame caption="Manager org members">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/members-list-options.png" />
</Frame>

## User roles

Members of an organization can have of the following roles:

* Admin - an admin is a privilidged member who can manage other members, create remote Runners, view all resources and administer the organization.
* Member - a regular user who can only a use a Local Runner, or a Runner that's been shared with them by an Admin.

## Permissions table

The following table outlines the specific permissions for each role in Gitpod:

| Permission                              | Admin | Member               |
| --------------------------------------- | ----- | -------------------- |
| **Organization Management**             |       |                      |
| Create and manage organization          | ✅     | ❌                    |
| Invite members                          | ✅     | ❌                    |
| Manage member roles                     | ✅     | ❌                    |
| View all organization members           | ✅     | ✅                    |
| Configure organization policies         | ✅     | ❌                    |
| View organization audit logs            | ✅     | ❌                    |
| Configure SSO                           | ✅     | ❌                    |
| **User**                                |       |                      |
| Create Personal Access Token            | ✅     | ✅                    |
| **Projects**                            |       |                      |
| Create projects                         | ✅     | Depends on policy    |
| Share projects within organization      | ✅     | ❌                    |
| View and use existing projects          | ✅     | ✅                    |
| **Runners**                             |       |                      |
| Create remote runners                   | ✅     | ❌                    |
| Use remote runners                      | ✅     | When shared by admin |
| Use Gitpod Desktop (if enabled)         | ✅     | ✅                    |
| **Environments**                        |       |                      |
| Create environments from any repository | ✅     | Depends on policy    |
| View all organization environments      | ✅     | ❌                    |
| **Secrets**                             |       |                      |
| Manage project secrets                  | ✅     | ❌                    |
| Manage personal secrets                 | ✅     | ✅                    |

To change a user's role, select 'Change Role' from the drop-down menu. This will open a modal where you can update their role.

<Frame caption="Change role">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/change-role.png" />
</Frame>

<Frame caption="Change member role">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/change-member-role.png" />
</Frame>

## Create an invite link

Select the 'Invite Members' button at the top of the list to open the 'Invite Members' page, where you can copy the invite link to share with your team. If you need to deactivate a link, click 'Reset Invite Link' to invalidate any previously created links.

<Frame caption="Invite members">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/invite-members.png" />
</Frame>


# Manage organization
Source: https://www.gitpod.io/docs/gitpod/organizations/manage-organization



If you are an admin of the current organization, you can modify the general settings. This includes:

* Changing the display name of your organization.
* Adjusting the email domains of users who can discover and join your organization.

In the Danger Zone, you have the option to delete the organization.

<Frame caption="Delete organization">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/delete-organization.png" />
</Frame>

## Allowed email domains

You can allow others to join your organization if their email address matches one of the allowed email domains in organization settings. Gitpod enforces a validation rule that only permits email domains provided by the identity provider (IdP) during sign-in. This means you can't add domains to the list unless they are used by members of your organization.

<Frame caption="Type the email domain and confirm by pressing the Enter key.">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/allowed-email-domains.png" />
</Frame>

<br />

<Frame caption="Now the input field changed to a tag.">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/selected-email-domains.png" />
</Frame>

<br />

<Frame caption="Select Update to validate and update the email domains. Here it is rejected because no existing user shares this email domain.">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/failed-email-domain-update.png" />
</Frame>


# Organization Secrets
Source: https://www.gitpod.io/docs/gitpod/organizations/organization-secrets

Learn how to configure Organization-wide secrets in your Organization

Organization secrets are a type of secret scoped to the organization level. They are used to store sensitive data such as API keys, access tokens, and credentials which are shared across all environments in the organization.

**Organization secrets have the lowest precedence** in the secrets hierarchy. They can be overridden by both project secrets and user secrets with the same name. This makes them ideal for setting organization-wide defaults while still allowing projects and individual users to customize as needed.

To manage your organization secrets, navigate to the **Settings > Organization > Secrets** page in your Gitpod dashboard.

<Frame caption="Secrets List">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-organization-list.png" />
</Frame>

## Secret Types

Organization secrets support the following types:

* [Environment Variables](/gitpod/configuration/secrets/environment-variables)
* [Files](/gitpod/configuration/secrets/files)
* [Container Registry Secrets](/gitpod/configuration/secrets/container-registry-secret)

## Creating an Organization Secret

To create an organization secret, navigate to the **Settings > Organization > Secrets** page in your Gitpod dashboard and click the **New Secret** button.

## Updating an Organization Secret

To update an organization secret, navigate to the **Settings > Organization > Secrets** page in your Gitpod dashboard and click the **Edit** button.

## Deleting an Organization Secret

To delete an organization secret, navigate to the **Settings > Organization > Secrets** page in your Gitpod dashboard and click the **Delete** button next to the corresponding secret.


# Overview
Source: https://www.gitpod.io/docs/gitpod/organizations/overview

Organizations represent groups you can join within an account. They let users share resources like remote runners and projects to collaborate easily.

Organizations give administrators control and insight into resources. Administrators can manage shared projects and environments, as well as create shared runners to be used by all members.

Organizations help teams collaborate effectively by providing a shared space for development resources and controls. They represent distinct groups within your account, each with their own isolated set of resources and permissions.

For personal use, you can create an Organization for yourself.

## Key Benefits

* Resource Sharing: Share runners, projects and secrets across your team
* Access Control: Manage who can access what through role-based permissions
* Standardization: Create organization-wide projects
* Cost Management: Track and control of resource usage in your Organization

## Organization Resources

Organizations act as containers for:

* Projects: Standardized development environment configurations
* Runners: Self-hosted infrastructure for running environments
* Members: Users with varying levels of access and permissions
* Settings: Organization-wide configurations and policies

## Isolation

Organizations represent hard boundaries - resources cannot be shared or transferred between organizations. Organizations are isolated from each other through strong access controls.

Each organizational resource belongs to exactly one organization - runners, projects and environments. Users can be members of multiple organizations but must switch between them explicitly

## Getting Started

* [How to create an organization](/flex/organizations/create-organization)


# Organization Policies
Source: https://www.gitpod.io/docs/gitpod/organizations/policies

Control how Gitpod is used in your organization with powerful policy settings that help manage resources, control costs, and ensure consistency.

<Warning>
  Organization policies are only available on Core and Enterprise plans. Free tier organizations will not have access to these features.
</Warning>

## What are Organization Policies?

Organization policies give administrators control over how Gitpod is used within their organization. With these policies, you can:

* Set limits on resource usage to control costs
* Enforce consistent development environments
* Implement security restrictions
* Streamline the user experience for your team

This guide explains each available policy and how to use them effectively.

## Getting Started with Policies

### Where to Find Policies

1. Ensure you have selected your organization
2. Navigate to [Settings > Organization > Policies](https://app.gitpod.io/settings/policies)

<Frame caption="Organization Policies">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/organization-policies.png" />
</Frame>

### Who Can Access Policies?

Only organization **administrators** can view and modify policies. Regular **members** do not have access to organization policies.

### How Policies Work

* Most policies apply to all organization members
* Changes take effect immediately for new actions
* Existing environments are not affected by policy changes
* Administrators can override certain policies (like environment creation restrictions)

## Available Policies

### Local Environments using Gitpod Desktop

Control whether team members can use the Gitpod Desktop application to create environments using local compute resources.

This policy helps you:

* Enforce the use of remote runners for all environments
* Ensure consistent computing resources across your team
* Maintain centralized control over environment creation

**Configuration**

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Toggle the switch next to `Allow local environments using Gitpod Desktop` option to enable or disable Gitpod Desktop usage for your organization

> **Note:** For more information about the Gitpod Desktop application and how it works, see the [Gitpod Desktop documentation](https://www.gitpod.io/docs/flex/gitpod-desktop/overview).

<Frame caption="Enable or disable local environments">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/gitpod-desktop-toggle.png" />
</Frame>

**Effect on users**

* Desktop application environments are disabled by organization policy
* Local Desktop runners will not appear in the Environment class selection list
* Users attempting to create local environments will see a policy restriction message
* Existing environments will continue running to allow for clean commit and shutdown
* Administrators can monitor and manage any running local environments via [Settings > Environments](https://app.gitpod.io/settings/environments)

### Editor Restrictions

This policy lets you standardize which code editors your team can use, creating consistency across development environments, enforcing company standards, and simplifying onboarding with standardized tools. You can also set a default editor that will be pre-selected for all users.

**Configuration**

1. In your [Organization Policies](https://app.gitpod.io/settings/policies) page, click on `Manage Editors` button
2. Select the editors you want to allow from the list
3. Choose a default editor that will be pre-selected for users
4. Save your changes

> **Remember:** You must keep at least one editor selected.

<Frame caption="You can toggle the editors you want to limit your organization from using and choose an org default">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/available-editors.png" />
</Frame>

**Effect on users**

* Users will only see the allowed editors in the editor selection dropdown
* The default editor you selected will be pre-selected automatically
* Attempts to use a non-allowed editor (for example: via CLI) will be met with an error indicating the reason

### Maximum Environment Timeout

Limit the auto-stop timeout options that users can select for their environments to prevent unnecessary resource usage and control computing costs.

**Configuration**

1. In your [Organization Policies](https://app.gitpod.io/settings/policies) page, click on dropdown under `Maximum timeout duration` option
2. Choose from the following available maximum values:
   * 30 minutes
   * 1 hour
   * 3 hours
   * 8 hours
   * No Max Timeout (all options available, including `Never` Timeout)

<Frame caption="You can choose what is the maximum timeout that is available to the users">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/maximum-timeout-duration.png" />
</Frame>

**Effect on users**

* Users will only see timeout options up to the maximum allowed by your policy in the dropdown menu
  For example, if you select "3 hours" as the maximum timeout, users will only see these options when starting an environment:
  * 30 minutes
  * 1 hour
  * 3 hours
* If you select "No maximum," users will see all timeout options including "Never."

<Frame caption="The policy will limit what users see as available timeout options">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/max-timeout-limited.png" />
</Frame>

### Environment Creation Restrictions

<Note>
  This is one of the policies that only affects organization members and not organization admins.
</Note>

This policy controls whether regular organization members can create environments directly from repository URLs or if they are restricted to only creating environments from pre-defined projects.

This policy ensures that regular members work only within approved projects that administrators have set up, maintaining organizational control over which repositories are used for development.

**Configuration**

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Check "Environments can only be created from projects" option under `Environment creation restrictions` to enable this restriction

<Frame caption="Environment creation restrictions">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/members-require-project.png" />
</Frame>

**Effect on users**

* Organization Members:
  * Can only create environments within existing projects
  * Will see "Create Environment" button restricted to existing projects only
  * Cannot create new projects
  * Will receive a policy notification when attempting to use repository URLs directly

* Organization Administrators:
  * Can create environments from any source, including direct repository URLs
  * Have exclusive permission to create new projects
  * Retain full access to all environment creation features

### Port Sharing Restrictions

This policy controls whether organization members can share ports from their environments to make services publicly accessible on the internet. If enforced, this restriction prevents users from exposing any ports from their Gitpod environments.

This policy helps you:

* Maintain security by preventing unauthorized exposure of development services
* Ensure compliance with organizational security policies
* Prevent accidental exposure of sensitive applications or data
* Control network access patterns within your organization

**Configuration**

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Check "Disable port sharing" option under `Port sharing restrictions` to prevent users from sharing ports

<Frame caption="Port sharing restrictions">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/port-sharing-restrictions.png" />
</Frame>

**Effect on users**

* Users will not be able to share ports using either the UI or CLI methods
* Attempts to use `gitpod environment port open` CLI commands will be blocked with a policy restriction message
* Users will not be able to use VS Code Browser
* Users will see a notification explaining that port sharing is disabled by organization policy

> **Note:** For more information about port sharing functionality, see the [Port sharing documentation](https://www.gitpod.io/docs/gitpod/integrations/ports#port-sharing).

### Maximum Concurrent and total environments a user can have

<Note>
  {' '}

  This policy only applies to remote environments. Local environments created with Gitpod Desktop are not affected by these limits and can still be created if local environments are enabled for your organization.
</Note>

This policy helps administrators manage resource usage and control costs by setting two important limits:

* **Maximum total environments per user**: Limits how many total environments (running or stopped) each user can have
* **Maximum running environments per user**: Limits how many environments each user can have running simultaneously

By setting reasonable limits, you can:

* Prevent resource overuse that might impact your organization's infrastructure
* Control cloud computing costs, especially with AWS EC2 runners
* Encourage users to clean up environments they're no longer using
* Ensure resources are distributed fairly across your team

**Configuration**

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Set appropriate values for both `Maximum concurrent environments` and `Maximum total environments`
   * Both values must be between 1 and 100
3. These are set to 10 and 50 respectively by default

<Frame caption="Restrict maximum environments a user can have running or in total">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/max-environments-limit.png" />
</Frame>

**Effect on users**

* A notification will appear when they attempt to create a new remote environment beyond the limit
* The notification will explain the policy limit and suggest stopping unused environments
* **Local environments** created with Gitpod Desktop are **not affected by these limits** and can be created without restriction

<Warning>
  If you are using EC2 runners, note that undeleted environments (running or stopped) will incur usage costs as per AWS pricing.
</Warning>

<Frame caption="A warning received due to the policy enforcement">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/max-environments-reached.png" />
</Frame>

### Default Environment Image

This setting controls the default devcontainer configuration that Gitpod automatically generates when users open repositories without existing devcontainer configurations, or when starting blank environments. Administrators can customize this organization-wide template to:

* Provide a standard starting point for new environments
* Replace Gitpod's system defaults with organization-specific standards
* Ensure consistency across your organization
* If your runner network limits public Internet access, you will be able to start configuring devcontainer with images available in your network

**Configuration:**

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Enter a valid container image reference under `Default environment image` option (for example: `mcr.microsoft.com/devcontainers/base:ubuntu-24.04`)

If no value is provided, the system default (`mcr.microsoft.com/devcontainers/base:ubuntu-24.04`) will be used.

> **Using private images?** Make sure to [set up proper access](/gitpod/configuration/devcontainer/getting-started#using-private-container-images) for your container registry.

<Frame caption="Set default devcontainer image">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/default-image.png" />
</Frame>

**Effect on users**

* The configured image will be used automatically when repositories don't specify an image
* Users won't need to take any additional action

### Auto-delete Archived Environments

Set the maximum retention period for archived environments across your organization.

* Environments archive after 7 days inactive (fixed)
* This policy sets when they're auto-deleted
* Overrides user preferences when more restrictive

**Configuration:**

<Frame caption="Set organization-wide auto-delete policy for archived environments">
  <img src="https://www.gitpod.io/images/docs/flex/configuration/policy_auto_delete.png" alt="Auto-delete policy configuration" />
</Frame>

1. Go to your [Organization Policies](https://app.gitpod.io/settings/policies) page
2. Under "Auto-delete rules", select the maximum retention period from the dropdown:
   * **1 week**: Delete 7 days after archiving
   * **2 weeks**: Delete 14 days after archiving
   * **4 weeks**: Delete 28 days after archiving
   * **Never**: Keep archived environments indefinitely

Users can select equal or shorter retention periods than the organization policy. Options exceeding the policy appear disabled in the dropdown.

**Example:** If organization policy is "2 weeks", users can select "1 week" or "2 weeks" but not "4 weeks" or "Never".

For more information about the Archive & Auto-delete feature, see the [complete documentation](/gitpod/configuration/archive-auto-delete).

## Tracking Policy Changes

All policy changes are automatically recorded in your organization's audit logs. This gives you:

* A complete history of who changed which policies and when
* Records of any policy violation attempts
* Visibility into how policies are being enforced

To review policy-related activities, check your [organization's audit logs](/gitpod/audit-logs/overview).

## Best Practices for Managing Policies

### Start Gradually

* Begin with moderate limits and adjust based on actual usage
* Inform your team before implementing new restrictions
* Use [audit logs](/gitpod/audit-logs/overview) to see how policies affect workflow

### Optimize Resource Management

* Set limits appropriate for your team size and available resources
* Regularly review usage patterns and adjust as needed
* Consider creating a policy review schedule (quarterly or after significant team changes)

### Balance Security and Productivity

* Choose editor restrictions that align with security requirements without hampering productivity
* Consider limiting local desktop access only for highly sensitive projects
* Use project-based environment creation to maintain organization without excessive restrictions

## Common Questions

### What happens to existing environments when I change a policy?

Existing environments aren't affected by policy changes. The new rules only apply to new environments or actions.

### Will users lose work when hitting a policy limit?

No. When users reach a policy limit (like maximum concurrent environments), they'll see a message explaining the limit and suggesting actions they can take, such as stopping unused environments.

### Can I set different policies for different teams?

Currently, policies apply to the entire organization. Team-specific policies aren't available yet.

### Do administrators have to follow these policies too?

Some policies, like environment creation restrictions, don't apply to administrators. Others, like resource limits, apply to everyone.

### How can I make a temporary exception to a policy?

The policy system doesn't include built-in exceptions. To make a temporary exception, adjust the policy temporarily and then change it back when no longer needed.

### What happens if I downgrade from Pro/Enterprise to Free tier?

If you downgrade to the Free tier, your policy settings will be preserved but will become inactive and non-editable until you upgrade again.

### Can policies be enforced retroactively?

Most policies only affect new actions or environments. Existing environments will continue to operate under the settings they were created with.

## Getting Help

If you have questions about organization policies:

* Contact [Gitpod support](https://www.gitpod.io/contact-support)
* Enterprise customers: Reach out to your account representative


# View members
Source: https://www.gitpod.io/docs/gitpod/organizations/view-members



As a regular member of an organization, you can view other members in the Settings. However, you cannot change anyone's membership. You do have the option to leave the organization via the drop-down menu.

<Frame caption="Member options">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/members-options.png" />
</Frame>

If you choose to leave the organization, another one of your organizations will be selected automatically, or you’ll be prompted to create a new one.

<Frame caption="Leave organization">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/leave-organization.png" />
</Frame>


# Projects
Source: https://www.gitpod.io/docs/gitpod/projects/overview



Projects in Gitpod allow you to create standardized development environments across your organization. By defining consistent settings for repositories, runners, and environments, projects enable team members to create fully configured environments with just one click.

## What are Projects?

A project in Gitpod serves as a blueprint for development environments, connecting a specific repository with predefined configurations. This ensures all team members work with the same standardized setup, eliminating "works on my machine" problems.

Projects provide several key benefits:

* **One-click environment creation** with consistent configuration
* **Standardization** of development environments across your organization
* **Automatic secret and environment variable management**
* **Time savings** by eliminating manual environment setup
* **Team collaboration** through shared project configurations

## Prerequisites

Before creating a project, ensure you have:

* Organization administrator permissions
* At least one runner set up in your organization

## Creating a Project

To create a new project:

1. Navigate to your organization dashboard at [https://app.gitpod.io](https://app.gitpod.io)
2. If you have no existing projects, you'll see the "No projects" screen
3. Click **Create project**

<Frame caption="No projects screen">
  <img src="https://www.gitpod.io/images/docs/flex/projects/no-projects.png" alt="No projects screen showing a Create project button" />
</Frame>

4. Enter the repository URL for your project
5. Provide a descriptive project name
6. Click **Continue**

<Frame caption="Create project - Initial setup">
  <img src="https://www.gitpod.io/images/docs/flex/projects/create-project.png" alt="Project creation screen with repository URL and name inputs" />
</Frame>

7. Configure your project settings:
   * Select an **Environment Class** (determines the compute resources)
   * Choose a **Dev Container configuration** or set up **Automations**
   * Click **Create project**

<Frame caption="Configure project settings">
  <img src="https://www.gitpod.io/images/docs/flex/projects/configure-project.png" alt="Project configuration screen with environment class selection" />
</Frame>

## Project Configuration Options

### Repository URL

The Git repository that will be cloned when an environment is created from this project.

### Environment Class

Defines the compute resources (CPU, memory, storage) allocated to environments. Each runner can have multiple environment classes configured, but a project can currently only use one environment class.

### Dev Container Configuration

Specifies how the development container should be configured, including:

* Base image
* Extensions
* Environment variables
* Port forwarding rules

### Automations

Powerful tools that go beyond Dev Container configuration to define, automate, and share common workflows:

* Run services (long-running processes) and tasks (one-off actions)
* Automate database provisioning, test runs, or cloud authentication
* Define complex workflows in YAML configuration files
* Update via the Gitpod CLI

## Managing Existing Projects

After creating a project, you can modify its configuration at any time:

1. Navigate to your organization's projects list
2. Select the project you want to modify
3. Use the settings panel to update configuration options including:
   * Dev Container configuration
   * Automations
   * Secrets and environment variables

You can also activate projects (to share with your organization) or deactivate them when they're no longer relevant.

## Limitations and Troubleshooting

* Projects currently support only one environment class. If you need a project to run in different regions (on different runners), you must set up multiple projects
* Projects don't yet have built-in support for multi-repo configurations, though they are supported through custom configurations

## Next Steps

After creating a project, you can:

* Create an environment from your project
* Share the project with your team
* Configure additional automations
* Add project-specific secrets

For more detailed information on specific project features, refer to the [Dev Container Configuration](/flex/configuration/devcontainer/overview) and [Automations](/flex/configuration/automations/overview) documentation.


# Project Secrets
Source: https://www.gitpod.io/docs/gitpod/projects/project-secrets



Project secrets are a type of secret that are specific to a project. They are used to store sensitive data that is specific to a project, such as API keys, access tokens, and credentials which are shared across all environments and users of a project.

**Project secrets have middle precedence** in the secrets hierarchy. They override organization secrets with the same name but can be overridden by user secrets. This allows teams to set project-specific values while still giving individual users the flexibility to customize their own environments.

To manage your project secrets, navigate to the **Project > Secrets** page in your Gitpod dashboard.

<Frame caption="Secrets List">
  <img src="https://www.gitpod.io/images/docs/flex/secrets/secret-list.png" />
</Frame>

## Secret Types

Project secrets support the following types:

* [Environment Variables](/flex/configuration/secrets/environment-variables)
* [Files](/flex/configuration/secrets/files)
* [Container Registry Secrets](/flex/configuration/secrets/container-registry-secret)

## Creating a Project Secret

To create a project secret, navigate to the **Project > Secrets** page in your Gitpod dashboard and click the **New Secret** button.

## Updating a Project Secret

To update a project secret, navigate to the **Project > Secrets** page in your Gitpod dashboard and click the **Edit** button.

## Deleting a Project Secret

To delete a project secret, navigate to the **Project > Secrets** page in your Gitpod dashboard and click the **Delete** button.


# Project Visibility
Source: https://www.gitpod.io/docs/gitpod/projects/project-sharing



When you create a Project, it is shared with your organization by default. Other members of your organization will see your Project and be able to launch environments.

You can change the visibility of your Project in the Project settings.

## Changing the visibility of your Project

The Project visibility can be changed in the Sharing tab within the project settings. Visibility can be toggled between all users within the organization or admins only. Projects can not be hidden from admins.

<Frame caption="Adjust project visibility settings">
  <img src="https://www.gitpod.io/images/docs/flex/projects/project-visibility-settings.png" />
</Frame>

## Launching an environment from a Project

The environment can be launched directly from the Project list view.

<Frame caption="Create environment from Project">
  <img src="https://www.gitpod.io/images/docs/flex/projects/create-env.png" />
</Frame>


# Regions and Latency
Source: https://www.gitpod.io/docs/gitpod/runners/aws/aws-regions



For the best user experience, users need low network latency between their dev environment and their local machine.
Many operations in the IDE or terminal require network packets to be sent between the local machine and dev environment.
High network latency can make the IDE and terminal feel sluggish.

Follow these steps to optimize your setup:

1. Identify regions offering the best latency for your users
2. Verify these regions are among the supported regions
3. Contact Gitpod support if you need support for additional regions

# Predicting Network Latency

Before deploying Gitpod Runners, you can measure network latency using these tools:

## Latency Testing Tools

* Third-party websites (search for "aws latency test"):
  * [CloudPing](https://www.cloudping.cloud/aws)
  * [AWS Latency Test](https://aws-latency-test.com/)
  * [AWS Speed Test](https://awsspeedtest.com/latency)

* Command-line tools:
  * `ping` command (requires ICMP support)
  * [httping](https://www.vanheusden.com/httping/) (for HTTP/HTTPS-only networks)

## Important Considerations

* Test results reflect latency from *your* location to AWS regions. If users are in different locations, have them run the same tests.
* Gitpod is designed to work with multipe regions by installing a runner in each region.
* VPN usage affects test results. Configure your connection to match your planned Gitpod usage:
  * Use VPN if you plan to connect to Gitpod through VPN
  * Disable VPN if you plan to connect directly

# Measuring Network Latency

After deploying Gitpod Runners, you can monitor latency using:

* JetBrains IDE: Check the "backend status" view when connected to a remote dev environment

# Recommended Latency Thresholds

| Latency  | Experience | Recommendation                                            |
| -------- | ---------- | --------------------------------------------------------- |
| \< 70ms  | Excellent! | Ideal for all development tasks                           |
| \< 120ms | Good       | Suitable for most development work                        |
| \< 200ms | Ok         | Users may notice some latency in IDE and terminal         |
| > 200ms  | Poor       | Not recommended. Users will experience significant delays |

# Supported AWS Regions

Gitpod AWS Runners are available in select regions across North America, Europe, Asia Pacific, and South America.

### North America

* `us-east-1` (N. Virginia)
* `us-east-2` (Ohio)
* `us-west-1` (N. California)
* `us-west-2` (Oregon)
* `ca-central-1` (Canada Central)

### Europe

* `eu-west-1` (Ireland)
* `eu-central-1` (Frankfurt)
* `il-central-1` (Israel Central)

### Asia Pacific

* `ap-southeast-1` (Singapore)
* `ap-southeast-2` (Sydney)
* `ap-northeast-1` (Tokyo)

### South America

* `sa-east-1` (São Paulo)

Need support for additional regions? Please [contact Gitpod](https://www.gitpod.io/contact/sales) for assistance.


# Costs & Budgeting for AWS Runner
Source: https://www.gitpod.io/docs/gitpod/runners/aws/aws-runner-costs



This guide outlines the costs associated with the AWS runner infrastructure. It does not include development environment costs or license fees.

<Note>
  AWS costs mentioned in this document are subject to change and may vary by
  region. Please check the latest pricing on the AWS pricing pages.
</Note>

## What is an AWS runner?

An AWS Runner is an orchestrator for development environments deployed within an AWS account.

The key characteristics of a runner are:

* Shared resource serving multiple users (not personal)
* Designed for "always-on" operation with optimized cost efficiency
* Suitable for small to medium-sized organizations with a single runner architecture
* Support for multiple runners to:
  * Enhance availability
  * Reduce latency for end users
  * Ensure data residency and compliance

## Billable AWS Resources

The following are the billable resources deployed by the AWS runner:

* **AWS::ECS::Service**: Used to manage the environments.
* **AWS::DynamoDB::Table**: Used to store state related to the reconciler of environments.
* **AWS::S3::Bucket**: Used to store user image and build Docker caches for performance.
* **AWS::ECR::Repository**: Used to store cached dev container images for faster environment startup (when [dev container image cache](/gitpod/runners/aws/devcontainer-image-cache) is enabled).
* **AWS::Logs::LogGroup**: Used to store logs related to the runner ECS task.

## Baseline Costs of a Runner

The primary cost associated with a runner is the ECS task.

* **Monthly Cost for ECS**: Less than \$8 per month, which is covered by the AWS free tier. This cost is fixed and does not vary with the number of environments.
* **Other services**: Costs for DynamoDB, S3, and CloudWatch typically account for less than 1% of the overall runner cost.

## Controls for Managing Costs

### Viewing Runner Costs

To view isolated runner costs in **AWS Cost Explorer**:

1. **Navigate to AWS Cost Explorer**.
2. **Group by Usage Type** to analyze the breakdown of costs.
3. **Filter by the CloudFormation stack** name, which can be found on your runner card in the Settings > Runners section.

   * **CloudFormation Stack**: Use the `aws:cloudformation:stack-name` tag.

     <img src="https://www.gitpod.io/images/docs/flex/runners/aws_stack_name_filter.png" alt="Stack Name Filter" width="400" />

   * **Cluster Name**: Alternatively, filter by the `aws:ecs:clusterName` tag.

     <img src="https://www.gitpod.io/images/docs/flex/runners/aws_cluster_name_filter.png" alt="Cluster Name Filter" width="400" />

### Viewing Environment Costs

To view isolated runner costs in **AWS Cost Explorer**:

1. **Navigate to AWS Cost Explorer**.
2. **Group by Usage Type** to analyze the breakdown of costs.
3. **Filter by the environment ID** using the **Name** tag:

   * **Tag**: `Name`
   * **Value**: `gitpod-environment-<ID>`
   * You can find the environment ID by selecting **Copy ID** from the environment details.

     <img src="https://www.gitpod.io/images/docs/flex/runners/aws_environment_id_filter.png" alt="Environment ID Filter" width="400" />

## EC2 Instance Tagging

All EC2 instances launched by Gitpod AWS runners automatically inherit tags from the CloudFormation template. This means:

* Any tags you add to the CloudFormation template will be propagated to the EC2 instances created for environments
* This allows for consistent resource tagging across your AWS infrastructure
* Tags can be used for cost allocation, resource grouping, and access control

### Adding Tags to EC2 Instances

To add tags to EC2 instances launched by Gitpod:

1. Navigate to the CloudFormation stack for your runner in the AWS console
2. Select **Update** from the stack actions
3. Choose **Use current template**
4. In the **Parameters** section, locate the **Tags** parameter (or add tags directly to the stack)
5. Add your desired tags in the format `Key=Value`
6. Complete the stack update process

All new EC2 instances launched after the update will include these tags.

<Note>
  When you update CloudFormation stack tags, the changes don't immediately apply to the existing runner ECS task. To force the runner to pick up the new tags immediately, you need to trigger a new deployment:

  1. In the AWS console, navigate to **Amazon ECS** > **Clusters**
  2. Select the cluster for your runner
  3. Select the runner service
  4. Click the arrow next to **Update** and select **Force new deployment**
  5. Click **Update** to apply the changes

  This will redeploy the runner service with the updated tags without affecting running development environments.
</Note>


# Capacity Planning
Source: https://www.gitpod.io/docs/gitpod/runners/aws/capacity-planning



Planning your AWS infrastructure for Gitpod requires careful consideration of your organization's network requirements and future growth. This guide helps you plan the required AWS account, regions, availability zones, and subnets for your deployment.

When planning your AWS infrastructure, consider these key objectives:

* Identify regions that offer optimal latency for your users
* Plan network capacity based on anticipated user count and growth
* Ensure system robustness through strategic availability zone selection
* Minimize future infrastructure changes by planning for scale

We'll create a planning table that will serve as input to set up your [Standard AWS Runner](/gitpod/runners/aws/standard-runner) or [Enterprise AWS Runner](/gitpod/runners/aws/enterprise-runner/overview). Enterprise Runners require additional load balancer subnet planning due to their dual-subnet architecture.

# Quick Start: Basic Setup

For a basic setup (single runner, single region, fewer than 1000 users):

1. Select your region based on the [recommended latency](/flex/runners/aws/aws-regions#recommended-latency)
2. Use the following configuration:

**Standard Runner**

| Runner Name | Max Users | Region    | Number of AZs | EC2 Subnet Size | Total Capacity |
| ----------- | --------- | --------- | ------------- | --------------- | -------------- |
| us-east     | 1000      | us-east-1 | 2             | /23 (512 IPs)   | 1019           |

**Enterprise Runner**

| Runner Name | Max Users | Region    | Number of AZs | EC2 Subnet Size | Load Balancer Subnet Size | Total Capacity |
| ----------- | --------- | --------- | ------------- | --------------- | ------------------------- | -------------- |
| us-east     | 1000      | us-east-1 | 2             | /23 (512 IPs)   | /28 (16 IPs)              | 1019           |

<Note>
  **Standard runners** use a single subnet type for EC2 instances. **Enterprise runners** require both EC2 subnets (for environments) and load balancer subnets (must be routable from your internal network).
</Note>

If this **Basic Setup** is sufficient for your needs, feel free to **skip the rest of this chapter** and proceed to setup your [Standard Runner](/gitpod/runners/aws/standard-runner) or [Enterprise Runner](/gitpod/runners/aws/enterprise-runner/setup).

# Example Planning Table

The following table demonstrates how to plan your AWS Runner infrastructure. We'll use this format to help you plan your specific deployment.

**Standard Runner Example**

| Runner Name | Users | Region    | Number of AZs | EC2 Subnet Size | Capacity |
| ----------- | ----- | --------- | ------------- | --------------- | -------- |
| us-east     | 500   | us-east-1 | 3             | /22 (1024 IPs)  | 3068     |
| us-west     | 100   | us-west-1 | 2             | /23 (512 IPs)   | 1019     |
| europe      | 300   | eu-west-1 | 2             | /21 (2048 IPs)  | 4091     |

**Enterprise Runner Example**

| Runner Name | Users | Region    | Number of AZs | EC2 Subnet Size | Load Balancer Subnet Size | Capacity |
| ----------- | ----- | --------- | ------------- | --------------- | ------------------------- | -------- |
| us-east     | 500   | us-east-1 | 3             | /22 (1024 IPs)  | /28 (16 IPs)              | 3068     |
| us-west     | 100   | us-west-1 | 2             | /23 (512 IPs)   | /28 (16 IPs)              | 1019     |
| europe      | 300   | eu-west-1 | 2             | /21 (2048 IPs)  | /28 (16 IPs)              | 4091     |

**Table Column Definitions**

* **Runner Name**: Choose a meaningful identifier for your runner
* **Users**: Maximum number of users expected to use the runner, including planned growth
* **Region**: AWS region where the runner will be deployed
* **Number of AZs**: Number of Availability Zones for the runner deployment
* **EC2 Subnet Size**: CIDR block size for EC2 subnets (where environments run)
* **Load Balancer Subnet Size (for Enterprise Runners only)**: CIDR block size for load balancer subnets. Load balancer must be routable from your internal network.
* **Capacity**: [Maximum number](#step-4%3A-plan-subnet-sizes) of dev environments the runner can support.

# Your Planning Table

Please create your own table and fill in the columns with your values.

### Infrastructure Considerations

Before creating your planning table, consider these important points:

* Gitpod AWS Runners can share AWS accounts, VPCs, regions, and subnets with other AWS runners
* Runners operate independently and can be deployed across multiple AWS accounts and VPCs
* For multiple runners, you can (but don't have to) use separate AWS accounts
  * If using multiple AWS accounts, add an "AWS Account" column to your planning table

### Step 1: Select Regions

Gitpod supports multiple runners that can be added or removed as needed. However, it's important to plan your regions carefully as you'll need appropriately sized subnets in each region.

Choose one or more [AWS Regions that provide the best latency for your users](/flex/runners/aws/aws-regions).

### Step 2: Estimate Users per Region

For each selected region, estimate the maximum number of users, considering:

* Current number of users
* Expected growth over time
* Peak usage patterns
* Geographic distribution of your team

### Step 3: Determine Availability Zones

Each AWS Runner requires at least one Availability Zone (AZ) and can utilize all AZs within a region. Key points:

* One subnet is required per AZ
* We recommend using 2-3 AZs per region for optimal availability
* More AZs provide better fault tolerance but increase complexity
* Consider your organization's high availability requirements

### Step 4: Plan Subnet Sizes

Subnet sizing is crucial for your Gitpod deployment's functionality and depends on the workload you are likely to have. Proper planning ensures you have sufficient IP addresses for your development environments while avoiding over-provisioning that wastes resources. Based on your runner type, you'll need to plan different subnet configurations.

#### EC2 Subnets (Both Standard and Enterprise Runners)

These subnets host your development environments and require careful capacity planning.

* Each environment requires one IP address
* Each AZ requires one subnet
* Management services need fewer than five IP addresses
* For Standard Runners, Environments run as EC2 instances and require routable subnets
* For Enterprise Runners, EC2 subnets can use non-routable CIDR ranges (such as CGNAT ranges) since they don't need direct access from your internal network
* Gitpod does not use Network Address Translation (NAT) for environments
* The minimum subnet size is `/28` (supports 10 environments)
* If multiple runners share subnets, they share the available IP address pool
* Maximum capacity = (Total subnet IPs × Number of AZs) - Management IPs
* **For public subnets** If using public subnets with internet gateway routing, ensure the subnet is configured to auto-assign public IP addresses. See [AWS documentation on auto-assign public IP](https://docs.aws.amazon.com/vpc/latest/userguide/subnet-public-ip.html) for configuration details.
* Note that it's best practice to choose subnet sizes generously, as expanding a subnet later can be more complex and costly than planning for growth upfront

#### Load Balancer Subnets (Enterprise Runners Only)

Enterprise Runners require additional subnets for their Network Load Balancer infrastructure, which provides direct connectivity to your environments.

* Required for Network Load Balancer deployment
* Must be routable from your internal network (unlike EC2 subnets which can use non-routable CIDR ranges)
* Typically `/28` (16 IPs) is sufficient for most deployments
* Need one subnet per AZ for high availability
* Do not affect environment capacity calculations


# Configuring Repository Access
Source: https://www.gitpod.io/docs/gitpod/runners/aws/configuring-repository-access



Repository access configuration is only required if you want to create Environments from repositories (GitHub, GitLab, etc.). If you only need to create empty Environments, you can skip this configuration. However, to launch Environments from any repository, the Runner **must** be configured with a provider that can access your repos (this includes public repositories).

Press **Add a provider** and select one of the supported providers such as GitHub:

<Frame caption="Repository provider">
  <img src="https://www.gitpod.io/images/docs/flex/runners/repository-provider.png" />
</Frame>

Configure the host, or leave the default if using github.com. If you want to support multiple hosts, you can add a separate provider for each host.

<Frame caption="GitHub OAuth">
  <img src="https://www.gitpod.io/images/docs/flex/source-control/github-enable-oauth.png" />
</Frame>

Next, choose at least one of OAuth or Personal Access Token support. You can set up an **OAuth** app to make it easy for users to sign in quickly. **Personal Access Token** allows users to provide their own PAT to sign in. Users will be prompted to authenticate before they start a new Environment on the Runner.

<Frame caption="Setup OAuth">
  <img src="https://www.gitpod.io/images/docs/flex/runners/setup-oauth.png" />
</Frame>

Press **Save** once done. You can now start Environments for repos on the specified host:

<Frame caption="AWS runner setup done">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-runner-setup-done.png" />
</Frame>

Whenever a user starts an Environment for the first time for that host, they will get prompted to authenticate first, and get the option to authenticate through the OAuth app or using a PAT token (whichever is configured in the integration). Once authenticated, the token is encrypted and stored to be remembered for the next time the user creates an Environment for this host.

When an admin disables OAuth/PAT support in an integration, or deletes an integration entirely for a host, any existing tokens obtained for the host through the disabled/deleted authentication method will get deleted and users might have to re-authenticate before they can create Environments again for that host.


# Deleting a runner
Source: https://www.gitpod.io/docs/gitpod/runners/aws/delete-runner

Learn how to delete runners in Gitpod.

To delete a runner, go to the runners page, and select **Delete** from the overflow menu.

<Frame caption="Delete a runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/delete-runner.png" />
</Frame>

This will start deletion of the runner and all its environments. The runner will move into a **Pending deletion** phase, and stop + delete any existing environments on the runner. Once all environments are deleted, the runner itself will get deleted, which can take a few more minutes.

Once deleted, you can clean up the CloudFormation stack in your AWS account associated with the runner.


# Access Requirements
Source: https://www.gitpod.io/docs/gitpod/runners/aws/detailed-access-requirements



Configure your firewall and network security groups to allow outbound connections to these endpoints for Gitpod to function properly.

<Note>
  **Enterprise Runner Proxy Support**: Enterprise runners support HTTP proxy configuration for environments behind corporate firewalls. When using a proxy, ensure that `.internal`, `169.254.0.0/16`, `app.gitpod.io`, and `.amazonaws.com` are added to the NO\_PROXY list. See the [Enterprise Runner setup guide](/gitpod/runners/aws/enterprise-runner/setup#proxy-configuration-optional) for detailed proxy configuration.
</Note>

## Gitpod Services

### Management Plane

Controls Runner and Environment orchestration by communicating with Gitpod's control plane.

* `https://app.gitpod.io`

### Gateway API Server

<Note>
  **Not required for Enterprise runners** - Enterprise runners use direct connectivity and do not require gateway endpoints.
</Note>

Provides secure connectivity between standard runners and Gitpod services through encrypted tunnels. Runners automatically select the optimal gateway (EU or US) based on latency.

**HTTPS:**

* `https://us01.gitpod.dev:8443`
* `https://*.us01.gitpod.dev:443`
* `https://eu01.gitpod.dev:8443`
* `https://*.eu01.gitpod.dev:443`

**UDP:**

* `lighthouse.us01.gitpod.dev:4242`
* `lighthouse.eu01.gitpod.dev:4242`

## VS Code

Required for VS Code IDE functionality including server downloads and extension marketplace access.

* `https://update.code.visualstudio.com/api/commits/stable/server-linux-x64-web`
* `https://update.code.visualstudio.com/api/commits/stable/server-linux-arm64-web`
* `https://update.code.visualstudio.com/commit:*/server-linux-x64/stable`
* `https://update.code.visualstudio.com/commit:*/server-linux-arm64/stable`
* `https://*.vscode-unpkg.net`
* `https://marketplace.visualstudio.com`
* `https://*.gallerycdn.vsassets.io`

## JetBrains

Required for JetBrains IDE functionality including IDE downloads and services.

* `https://download.jetbrains.com`
* `https://download-cf.jetbrains.com`
* `https://download-cdn.jetbrains.com`
* `https://data.services.jetbrains.com`

## Release Artifacts

Downloads Gitpod updates, CLI binaries, and agent components necessary for Runner and Environment operation.

* `https://releases.gitpod.io/ec2/stable/manifest.json`
* `https://releases.gitpod.io/ec2/stable/supervisor-amd64.xz`
* `https://releases.gitpod.io/ec2/stable/gitpod-ec2-runner.json`
* `https://releases.gitpod.io/ec2/stable/gitpod-ec2-runner-enterprise.json`
* `https://releases.gitpod.io/ec2/stable/gitpod-ec2-multi-org-runner.json`
* `https://releases.gitpod.io/cli/stable/manifest.json`
* `https://releases.gitpod.io/cli/stable/gitpod-linux-amd64`
* `https://releases.gitpod.io/cli/stable/gitpod-linux-amd64.exe`
* `https://releases.gitpod.io/cli/stable/gitpod-linux-amd64.sha256`
* `https://releases.gitpod.io/cli/stable/gitpod-linux-arm64`
* `https://releases.gitpod.io/cli/stable/gitpod-linux-arm64.sha256`
* `https://releases.gitpod.io/vscode/releases/*/vscode-remote.vsix`
* `https://releases.gitpod.io/vscode/releases/*/vscode-agent-amd64`
* `https://releases.gitpod.io/vscode/releases/*/vscode-agent-arm64`
* `https://releases.gitpod.io/jetbrains/releases/*/jetbrains-agent-amd64`
* `https://releases.gitpod.io/jetbrains/releases/*/jetbrains-agent-arm64`

## Container Registries

Downloads container images used by development environments and Runner infrastructure.

**Gitpod default devcontainer image:**

* `https://mcr.microsoft.com/devcontainers/base:ubuntu-24.04`

**AWS Public ECR (Runner images):**

* `https://public.ecr.aws`

## Your Infrastructure

### SCM and SSO Providers

Access to your source code repositories and authentication providers for user login and code access.

Configure access to your specific providers (complete HTTPS URLs):

* GitHub, GitLab, Bitbucket URLs
* SSO provider URLs (Okta, Azure AD, etc.)

## Optional Services

### Prometheus Remote Write

Optional metrics collection endpoint for monitoring Runner and Environment performance.

* Your metrics endpoint URL (HTTPS 443)

### Additional Container Registries

Optional access to custom container registries for pulling private or organization-specific images.

**Common registries (allow those you use):**

* `https://index.docker.io`
* `https://registry-1.docker.io`
* `https://auth.docker.io`
* `https://ghcr.io`
* Your private registry URLs (HTTPS 443)

## AWS Services

Replace `<region>` with your AWS region and `<account-id>` with your AWS Account ID.

### Instance Metadata

EC2 instance configuration and metadata required for AWS service integration.

* **Endpoint**: `169.254.169.254`
* **Protocol**: HTTP (80)

### Regional APIs

AWS service communication for EC2 management, container registry access, and other AWS operations.

* `https://ec2.<region>.amazonaws.com`
* `https://<account-id>.dkr.ecr.<region>.amazonaws.com`
* `https://s3.<region>.amazonaws.com`
* `https://ssm.<region>.amazonaws.com`
* `https://sts.<region>.amazonaws.com`
* `https://dynamodb.<region>.amazonaws.com`
* `https://cloudformation.<region>.amazonaws.com`
* `https://secretsmanager.<region>.amazonaws.com`
* `https://logs.<region>.amazonaws.com` (optional)
* `https://elasticloadbalancing.<region>.amazonaws.com` (Enterprise runners only)
* `https://acm.<region>.amazonaws.com` (Enterprise runners only)

## AMI Requirements

Both Standard and Enterprise AWS runners require access to specific AMIs. If your AWS Organization restricts AMI access, ensure your AWS account can launch EC2 instances from these AMIs.

### Required AMIs

| AMI Name                                     | Owner Account ID | Owner  | Purpose                  |
| -------------------------------------------- | ---------------- | ------ | ------------------------ |
| `bottlerocket-aws-ecs-1-x86_64`              | `149721548608`   | Amazon | Runner service           |
| `gitpod/images/gitpod-next/ec2-runner-ami-*` | `995913728426`   | Gitpod | Development environments |

### Allowlisting Recommendations

Gitpod updates AMIs regularly as part of our continuous security and feature updates. We recommend allowing access by **Owner Account ID** rather than specific AMI ID when implementing allowlisting policies.

#### Why Use Owner Account ID

* **Automatic updates**: New AMI versions are automatically accessible without policy updates
* **Security**: Ensures you always have access to the latest security patches
* **Maintenance**: Reduces administrative overhead of managing specific AMI IDs

#### Implementation

When configuring your AWS Organization's AMI access policies:

1. **Allow by Owner Account ID**: Use the Owner Account IDs from the table above
2. **Include both accounts**: Both Amazon (`149721548608`) and Gitpod (`995913728426`) accounts are required
3. **Test access**: Verify your Runner deployment account can launch instances from these AMIs

### Testing AMI Access

To verify AMI access is working correctly:

1. **Test AMI access** by attempting to launch a test instance from the required AMIs in your target region
2. **Check deployment logs** during Runner setup for any AMI access errors
3. **Monitor CloudFormation events** for AMI-related failures during stack deployment

```bash
# List available AMIs from required accounts (replace us-east-1 with your region)
aws ec2 describe-images --region us-east-1 --owners 149721548608 --filters "Name=name,Values=bottlerocket-aws-ecs-1-*"
aws ec2 describe-images --region us-east-1 --owners 995913728426 --filters "Name=name,Values=gitpod/images/gitpod-next/ec2-runner-ami-*"
```

If you encounter AMI access issues during Runner deployment, contact your AWS administrator to review and update your organization's AMI access policies.

## SSH Domain Aliases

Gitpod uses domain aliases like `<workspace-id>.gitpod.remote` and `<workspace-id>.gitpod.environment` for SSH connectivity to workspaces.

### Understanding Domain Aliases

These domain names are not actual internet domains but SSH configuration aliases that map to EC2 instance IP addresses:

* **Virtual domains**: `gitpod.remote` and `gitpod.environment` are virtual domains that exist only in your SSH configuration
* **Automatic mapping**: The Gitpod CLI updates your SSH config with the actual instance IP addresses
* **User-friendly access**: Provides clean identifiers instead of complex AWS hostnames like `ec2-18-184-202-80.region.compute.amazonaws.com`

### How They Work

1. When you connect to a workspace via SSH or VS Code, you use the alias (e.g., `abc123.gitpod.remote`)
2. Your SSH client resolves this to the actual IP address based on your SSH configuration
3. The Gitpod CLI manages these mappings automatically, fetching the current IPs from the Gitpod API

These aliases simplify connection management while hiding the complexity of the underlying dynamic cloud infrastructure.


# Dev Container Image Cache
Source: https://www.gitpod.io/docs/gitpod/runners/aws/devcontainer-image-cache

Learn how to use the dev container image cache feature for AWS runners to significantly reduce environment startup times by automatically caching built devcontainer images in AWS ECR.

The dev container image cache feature automatically stores built devcontainer images in AWS ECR (Elastic Container Registry), enabling environments with identical devcontainer configurations to reuse previously built images. This significantly reduces startup times by eliminating the need to rebuild containers from scratch.

## Overview

When you create an environment with a devcontainer configuration, Gitpod typically needs to build the container image, which can take several minutes depending on complexity. The dev container image cache stores these built images in a secure container registry, allowing subsequent environments with the same configuration to start in seconds rather than minutes.

## How it works

1. **Hash computation**: When starting an environment, Gitpod computes a hash based on your devcontainer configuration, including:
   * Contents of `devcontainer.json`
   * Contents of any referenced `Dockerfile`

2. **Cache lookup**: Gitpod checks if an image with this hash already exists:
   * If found in registry: Pulls and uses the cached image
   * If not found: Builds new image, pushes to registry, then uses it

3. **Shared caching**: The cache is shared across all users within a project. The first team member who creates an environment with a new devcontainer configuration builds and caches the image. All subsequent environments created by any team member in the same project with identical configuration use the shared cached version. When rebuilding an existing environment's dev container, it will also try to pull from the cache but won't push new images (only the initial dev container build when an environment gets created can push to the cache).

<Note>
  Non-project environments (such as those started directly from a context URL) do not use the cache.
</Note>

## Enabling and disabling the cache

### For new runners

The dev container image cache is **enabled by default** for new AWS runners.

<Note>
  Disabling the cache is only available on Core and Enterprise tiers.
</Note>

### For existing runners

To enable the cache for existing runners:

1. [Update your CloudFormation stack](/gitpod/runners/aws/update-runner#updating-infrastructure) to the latest version that supports the cache
2. Go to **Settings → Runners** in your Gitpod organization
3. Select your AWS runner
4. Toggle **Dev container image cache** to enabled
5. Click **Save**

<Warning>
  Upgrading CloudFormation templates that were applied from January 2025 or earlier will cause existing environments to no longer be accessible due to SSH port changes. Before upgrading, either stop and discard existing environments, or manually update the security group to allow access from 0.0.0.0/0 to port 22 (in addition to port 29222) after upgrading the stack.
</Warning>

<Frame caption="Configuring an AWS runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-runner-configuration.png" />
</Frame>

### Disabling the cache

To disable caching:

1. Go to **Settings → Runners** in your Gitpod organization
2. Select your AWS runner
3. Toggle **Dev container image cache** to disabled
4. Click **Save**

<Note>
  Disabling the cache prevents new images from being cached and stops existing environments from pulling from the cache on rebuild. Existing cached images remain in ECR until they expire (30 days) or are manually deleted.
</Note>

## What gets cached

The cache includes everything from a `devcontainer build` of your configuration:

* **Base image layers**: Your specified base image and any modifications
* **Dev container features**: All configured features are pre-installed
* **Build steps**: RUN commands, COPY operations, and other Dockerfile instructions
* **Tool installations**: Package managers, development tools, and dependencies

**What is NOT cached:**

* Lifecycle hooks (`onCreateCommand`, etc.) - these run after the container starts
* User-specific configurations applied at runtime
* Files that change after container creation

## Shared cache considerations

The dev container image cache is designed as a shared resource within each project to maximize efficiency and reduce build times across your team. This shared approach means:

* **Team efficiency**: Only the first team member to use a new devcontainer configuration experiences the full build time
* **Consistent environments**: All team members use identical container images, ensuring environmental consistency
* **Resource optimization**: Eliminates redundant builds across team members

### Enterprise security considerations

For organizations with strict security requirements, it's important to understand the shared nature of the cache:

* **Configuration integrity**: Images are cached based on exact configuration hashes, ensuring consistency
* **Limited push access**: Only the initial dev container build when an environment gets created can push images to the cache, and push credentials are removed from the environment afterward
* **Immutable storage**: ECR's immutability feature prevents modification of cached images once stored
* **Project isolation**: Cache access is strictly limited to the same project, preventing cross-project contamination

Organizations with enhanced security policies may choose to disable the cache to maintain complete control over container image provenance, though this comes with the trade-off of longer environment startup times.

## Security considerations

The dev container image cache implements several security measures:

### Access isolation

* **Project-scoped access**: Images are only accessible within the same project
* **Hash-based immutability**: Once pushed, images cannot be modified
* **Credential separation**: Distinct push and pull permissions

### Credential management

* **Push credentials**: Only granted during the initial dev container build when an environment gets created, then removed from the environment
* **Pull credentials**: Provided to all environments in the project, refreshed periodically
* **Temporary access**: All credentials use AWS IAM temporary credentials with minimal required permissions

### Registry security

* **Immutable repositories**: ECR repositories prevent image tampering once pushed
* **AWS IAM controls**: Access controlled through AWS session tags and IAM policies
* **Regional isolation**: Images stored in the same AWS region as your runner

## Image lifecycle

### Automatic expiry

Cached images automatically expire after **30 days** to:

* Prevent unlimited storage growth
* Ensure images are periodically rebuilt with security updates
* Reduce storage costs

### Cache invalidation

A new image is built and cached when:

* The devcontainer configuration hash changes (any modification to `devcontainer.json` or referenced `Dockerfile`)
* The cached image has expired
* The cached image is manually deleted from ECR

## Forcing a new image build

To force rebuilding and re-caching an image, you need to change the configuration hash. You can:

### Method 1: Modify devcontainer configuration

Add or modify any content in your `devcontainer.json` or `Dockerfile`, such as:

```json
{
  "name": "My Dev Container",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18",
  // Add a comment to force rebuild: 2024-01-15
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  }
}
```

### Method 2: Add a comment to Dockerfile

If using a custom Dockerfile:

```dockerfile
FROM node:18
# Force rebuild: 2024-01-15
RUN npm install -g typescript
```

### Method 3: Delete the image from ECR

1. Go to AWS ECR console
2. Navigate to your runner's repository: `gitpod-runner-{runnerID}/projects/{projectID}/image-build`
3. Delete the specific image tag
4. The next environment creation will rebuild and cache the image

## Troubleshooting

### Cache not working

If images aren't being cached:

1. **Check runner configuration**: Ensure the dev container image cache is enabled in runner settings
2. **Verify CloudFormation version**: Older CloudFormation templates don't support caching
3. **Check AWS permissions**: Ensure the runner has ECR access permissions
4. **Check runner logs**: Look for cache-related errors in the runner's CloudWatch logs
5. **Review environment logs**: Look for cache-related error messages

### Slow startup despite cache

If environments are still slow to start:

1. **Check cache hit**: Look for "Using pre-built dev container" in environment logs
2. **Verify image size**: Large images take longer to pull
3. **Check environment type**: Docker Compose-based devcontainers are not supported by the cache
4. **Review lifecycle hooks**: Lifecycle hooks (`onCreateCommand`, etc.) are not cached and may install tools that increase startup time. Consider moving these steps to the Docker build where possible
5. **Verify project-based environment**: Non-project environments do not use the cache

## Supported configurations

### Supported

* Standard devcontainer configurations with `Dockerfile` or `image` reference
* Dev container features from any registry

### Not supported

* Docker Compose-based devcontainers (due to limited devcontainer CLI support)
* Non-project environments (e.g. environments started directly from a context URL)
* Runners other than AWS EC2 runners

## Storage and costs

### Storage costs

* Images are stored in AWS ECR in your account
* Storage costs depend on image size and number of unique configurations
* 30-day automatic expiry helps manage costs
* ECR repositories inherit all tags from the CloudFormation stack (useful for cost allocation and AWS MAP programs)

### Cost optimization

* Similar devcontainer configurations share base layers, reducing storage
* Regional storage (same region as runner) minimizes transfer costs
* Automatic expiry prevents accumulation of unused images

### Repository location

Cached images are stored in ECR repositories with the naming pattern:
`gitpod-runner-{runnerID}/projects/{projectID}/image-build`

Each project gets its own repository within the runner's ECR namespace, ensuring proper isolation and organization.

## Monitoring and visibility

### Environment logs

Cache operations are logged during environment creation in the `Creating dev container` log section when a cache hit occurs:

```
⚡️ Using pre-built dev container (saved ~3m45s build time)
```

The cache provides significant performance improvements while maintaining security and cost efficiency through automated management.


# Overview
Source: https://www.gitpod.io/docs/gitpod/runners/aws/enterprise-runner/overview



<Warning>
  Enterprise Runner is exclusively available to customers on the [Enterprise tier](https://www.gitpod.io/pricing). If you're an Enterprise customer, contact your Gitpod account manager for more information.
</Warning>

The Enterprise AWS Runner provides enhanced capabilities including AI agent support and direct connectivity options. Designed for enterprise customers who need advanced features and greater control over their infrastructure with custom networking configurations.

## Key Features

* **Ona AI agent integration** - Enhanced development workflows with AI-powered assistance
* **Direct connectivity** - Bypasses Gitpod's central gateway by using your own Network Load Balancer, secured with your custom domain and SSL/TLS certificate
* **Private VPC endpoints** - Connect to Gitpod's management plane via AWS PrivateLink for enhanced security without public internet traversal
* **Enhanced security** - Fine-grained IAM policies with permission boundaries for enterprise security requirements
* **HTTP proxy support** - Custom HTTP proxy configuration for environments behind corporate firewalls
* **Custom CA certificate support** - Support for enterprise certificate authorities and custom certificate chains

<Frame caption="Enterprise Runner architecture">
  <img src="https://www.gitpod.io/images/docs/flex/runners/enterprise-runner.webp" />
</Frame>

## Prerequisites

Before deploying your Enterprise AWS Runner, ensure you have:

1. **AWS Account** with elevated permissions for enterprise features

2. **Capacity Planning** - Follow our [Capacity Planning](/gitpod/runners/aws/capacity-planning) guide to determine your infrastructure requirements

3. **AMI Access** - If your organization restricts AMI usage, allowlist the AMIs Gitpod runners and environments run on

   | AMI Name                                     | Owner Account ID | Owner  | Purpose                  |
   | -------------------------------------------- | ---------------- | ------ | ------------------------ |
   | `bottlerocket-aws-ecs-1-x86_64`              | `149721548608`   | Amazon | Runner service           |
   | `gitpod/images/gitpod-next/ec2-runner-ami-*` | `995913728426`   | Gitpod | Development environments |

   For more details, review our [AMI Requirements](/gitpod/runners/aws/detailed-access-requirements#ami-requirements) guide

4. **Domain Name** that you control with DNS modification capabilities

5. **SSL/TLS Certificate** provisioned in AWS Certificate Manager (ACM). Your SSL certificate must include both Subject Alternative Names (SANs):
   * `yourdomain.com` (root domain)
   * `*.yourdomain.com` (wildcard subdomain)

## Network Requirements

The Enterprise Runner requires a custom VPC with specific networking setup for enhanced security and direct connectivity.

<Frame caption="Network Configuration Diagram">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-networking-enterprise.webp" />
</Frame>

### AWS Infrastructure Setup

#### VPC Requirements

* Custom VPC spanning 2-3 Availability Zones for high availability
* CIDR block sized appropriately for your expected workload capacity

#### Subnet Architecture

* **EC2 instance subnets**: Private or public subnets where Runner instances will be deployed
  * Must be sufficiently large for your expected concurrent Environments
  * Can have non-routable CIDR range (e.g.: CGNAT range)
* **Load balancer subnets**: Subnets for the Network Load Balancer deployment
  * Public subnets for internet-facing deployments
  * Private subnets for internal-only access (must be routable from user networks)
  * Should span multiple Availability Zones for high availability
  * Must have a routable CIDR range

### Connectivity Requirements

This section outlines the network connectivity requirements for your Enterprise Runner deployment, including user access paths and required outbound connections.

#### User access to Environments

* Load balancer subnets must be routable from your internal network via VPN, Direct Connect, Transit Gateway, or other networking solutions
* DNS resolution for your custom domain from user networks
* Firewall rules allowing HTTP (port 80) and HTTPS (port 443) traffic to the load balancer

#### Outbound access requirements

| Endpoint                           | Purpose                           | Protocol | Port |
| ---------------------------------- | --------------------------------- | -------- | ---- |
| `app.gitpod.io`                    | Gitpod Service (management plane) | HTTPS    | 443  |
| `releases.gitpod.io/*`             | Gitpod Release Artifacts          | HTTPS    | 443  |
| `update.code.visualstudio.com/*`   | VS Code Server                    | HTTPS    | 443  |
| `*.vscode-unpkg.net`               | VS Code Extensions                | HTTPS    | 443  |
| `marketplace.visualstudio.com`     | VS Code Marketplace               | HTTPS    | 443  |
| `*.gallerycdn.vsassets.io`         | VS Code Assets                    | HTTPS    | 443  |
| `*.jetbrains.com`                  | JetBrains IDEs                    | HTTPS    | 443  |
| `public.ecr.aws`                   | Container images                  | HTTPS    | 443  |
| `*.amazonaws.com`                  | AWS API calls                     | HTTPS    | 443  |
| SCM Services                       | Source code repositories          | HTTPS    | 443  |
| (optional) Prometheus Remote write | Metrics endpoint                  | HTTPS    | 443  |
| (optional) Container Registries    | Custom container registries       | HTTPS    | 443  |

<Note>
  For more details about each of these outbound requirements, see [Detailed Access Requirements](/gitpod/runners/aws/detailed-access-requirements).
</Note>

#### VPC Endpoints (Optional)

VPC endpoints can help reduce data transfer costs and improve security by keeping traffic within the AWS network. Create VPC endpoints for all required AWS services per the [detailed access requirements](/gitpod/runners/aws/detailed-access-requirements#aws-services) guide.

For Enterprise customers with strict security requirements, you can also establish private connectivity to Gitpod's management plane using AWS PrivateLink. This eliminates the need for public internet access to communicate with Gitpod services. See the [setup guide](/gitpod/runners/aws/enterprise-runner/setup#private-vpc-endpoints-optional) for configuration details.

> Note: With standard VPC endpoints for AWS services, outbound internet access to Gitpod services is still required unless you also configure private VPC endpoints for Gitpod's management plane.

### Security Group Configuration

The CloudFormation template creates a default security group that will be associated with the Network Load Balancer with the following configuration:

* All egress traffic allowed
* Ingress from any IP (0.0.0.0/0) on ports 80 and 443

For enhanced security, you can create a custom security group and specify it in the CloudFormation template parameters to limit the load balancer access further. When creating a custom security group, ensure the following access:

**Inbound Rules:**

* Allow ports 80 and 443 from all IP ranges where your users will connect to Gitpod Environments
* Allow ports 80 and 443 from your SCM provider IP ranges (GitHub, GitLab, etc.) to enable OAuth redirects

**Outbound Rules:**

* Outbound access should allow connectivity to all the required services listed [above](#outbound-access-requirements)

## Next Steps

Ready to deploy your Enterprise Runner? Follow our comprehensive setup guide designed specifically for enterprise deployments.

<CardGroup cols={2}>
  <Card title="Set up Enterprise Runner" icon="rocket" href="/gitpod/runners/aws/enterprise-runner/setup">
    Deploy your Enterprise AWS Runner with enhanced capabilities
  </Card>

  <Card title="Troubleshooting AWS Runners" icon="wrench" href="/gitpod/runners/aws/troubleshooting-runners">
    Resolve common issues including networking problems and Runner configuration
  </Card>
</CardGroup>


# Setup
Source: https://www.gitpod.io/docs/gitpod/runners/aws/enterprise-runner/setup



<Warning>
  Enterprise Runner is exclusively available to customers on the [Enterprise tier](https://www.gitpod.io/pricing). If you're an Enterprise customer, contact your Gitpod account manager for more information.
</Warning>

Deploy your Enterprise AWS Runner using our enhanced CloudFormation template with custom ingress capabilities. This comprehensive guide walks you through the complete deployment process using the AWS Management Console.

## Prerequisites

Before starting the deployment, ensure you have:

* **Admin access** to the Gitpod organization
* **AWS Account** with appropriate permissions to create CloudFormation stacks
* **VPC and Subnets** configured in your AWS account
* **SSL/TLS Certificate** provisioned in AWS Certificate Manager (ACM) with both root domain and wildcard subdomain SANs
* **Domain Name** that you control and can modify DNS records for
* **Permissions** to deploy CloudFormation stacks with IAM resources

## Create Enterprise Runner in Gitpod

Go to Settings -> Runners, and press **Setup a new runner**:

<Frame caption="Runners in settings">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runners-settings.webp" />
</Frame>

After choosing AWS from the list of available providers, continue with the **Enterprise Runner template**.

<Frame caption="Provider selection">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-providers.webp" />
</Frame>

<Frame caption="CloudFormation Template selection">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-template-enterprise.webp" />
</Frame>

Choose the **Enterprise Runner template**, provide a **name** and select the **AWS region** to deploy the Runner into, then press **Create**. This creates the Runner reference in Gitpod.

<Note>
  Runners are regional, and can only launch Environments in the AWS region
  they are deployed in. For multi-region support we recommend setting up
  multiple Runners in different regions. The region cannot be changed once
  deployed.
</Note>

<Frame caption="Add an AWS Runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/add-runner.webp" />
</Frame>

<Frame caption="Runner details">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-details.webp" />
</Frame>

## CloudFormation Template Deployment

Next, ensure you are signed into the right AWS account in the AWS console, and then press **Open AWS CloudFormation** to start deploying the Runner into your AWS account. This will link you to the AWS console to create the CloudFormation stack:

<Frame caption="Create stack in AWS">
  <img src="https://www.gitpod.io/images/docs/flex/runners/create-stack-in-aws.png" />
</Frame>

Most parameters are auto-filled already. The template is organized into several parameter groups and has to be filled out carefully.

#### Gitpod Configuration

Core authentication and API connection settings for your Gitpod Runner.

| Parameter          | Description                                                        | Required |
| ------------------ | ------------------------------------------------------------------ | -------- |
| **Runner ID**      | Unique identifier for your Runner (auto-generated by Gitpod)       | ✅ Yes    |
| **Exchange Token** | Authentication token for the EC2 Runner (auto-generated by Gitpod) | ✅ Yes    |
| **API Endpoint**   | URL of the Gitpod API (auto-generated by Gitpod)                   | ✅ Yes    |

⚠️ **Important**: These values are automatically generated by Gitpod when you create a Runner configuration. Do not modify these values manually.

#### Network Configuration (Mandatory)

VPC and subnet settings for deploying the Runner infrastructure.

| Parameter                | Description                                                                                                    | Example Value                  | Required |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- |
| **VPC**                  | The VPC where the Runner will be deployed                                                                      | `vpc-12345abcd`                | ✅ Yes    |
| **Availability Zones**   | AZs for high availability (select 2-3)                                                                         | `us-east-1a, us-east-1b`       | ✅ Yes    |
| **EC2 Instances Subnet** | Private subnets for EC2 instances (can be non-routable from internal network). Should match the number of AZs  | `subnet-123abc, subnet-456def` | ✅ Yes    |
| **Loadbalance Subnets**  | Subnets for load balancer with CIDR ranges routable from your internal network. Should match the number of AZs | `subnet-123abc, subnet-456def` | ✅ Yes    |

**Recommendations:**

* Select 2-3 Availability Zones for high availability
* **EC2 subnets**: Use private subnets, must be sufficiently large for your expected workload
* **Load balancer subnets**: Must have CIDR ranges routable from your internal network for user access
* Ensure connectivity from user locations via VPN, Direct Connect, or Transit Gateway

#### DNS Configuration

Domain name, SSL certificate, and load balancer visibility settings.

| Parameter                    | Description                                    | Example Value                                              | Required |
| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------- | -------- |
| **Load Balancer Visibility** | Choose between `internal` or `internet-facing` | `internal`                                                 | ✅ Yes    |
| **Domain Name**              | Your domain name for Gitpod access             | `yourdomain.com`                                           | ✅ Yes    |
| **Certificate ARN**          | ARN of your SSL certificate from ACM           | `arn:aws:acm:us-east-1:123456789012:certificate/abc123...` | ✅ Yes    |

**Load Balancer Visibility Options:**

* **internal**: Load balancer is only accessible from within your VPC (recommended for private deployments)
* **internet-facing**: Load balancer is accessible from the internet (only if using public subnets)

#### Network Configuration (Optional)

Configure additional network settings for enterprise security requirements.

| Parameter                                   | Description                                                       | Example Value                     | Required                        |
| ------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- | ------------------------------- |
| **Custom Security Group for Load Balancer** | Security group to attach to the load balancer for traffic control | `sg-abcdef123`                    | ❌ Optional                      |
| **HTTP Proxy**                              | HTTP proxy server URL                                             | `http://proxy.company.com:8080`   | ❌ Optional                      |
| **HTTPS Proxy**                             | HTTPS proxy server URL                                            | `https://proxy.company.com:8080`  | ❌ Optional                      |
| **No Proxy**                                | Comma-separated list of hosts to bypass proxy                     | `.internal,169.254.0.0/16,...`    | ⚠️ Required if proxy configured |
| **Custom CA Certificate**                   | Custom certificate authority from SSM/Secrets Manager             | `{{resolve:ssm:/gitpod/ca-cert}}` | ❌ Optional                      |

**Security Group Behavior:**

* **If not provided**: An automatic security group will be created that allows all traffic (0.0.0.0/0) to ports 80 and 443
* **If provided**: You can specify a custom security group to narrow down the allowed traffic sources for enhanced security

**Proxy Configuration:**

When configuring HTTP/HTTPS proxy, NO\_PROXY must include: `.internal`, `169.254.0.0/16`, `app.gitpod.io`, and `.amazonaws.com`.

**Proxy Update Behavior:**

* **Runner infrastructure**: Changes take effect immediately after CloudFormation update
* **Component-specific timing**:
  * Content initialization: Effective after environment restart
  * Devcontainer: Effective after rebuild
  * Docker in Docker: Effective after container recreation

**Custom CA Certificate:**

Use CloudFormation dynamic references to retrieve certificates from AWS SSM Parameter Store or Secrets Manager. For syntax details, see [SSM Parameter Store](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references-ssm.html) or [Secrets Manager](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references-secretsmanager.html) documentation.

<Warning>
  Custom CA certificates work in runner, content init (SCM), and docker pull operations. However, they are **not supported** in devcontainer and devcontainer image build phases - you must add CA certificates to your images for these use cases.
</Warning>

## Review and Deploy

1. **Review Configuration**
   * Verify all parameters are correctly set
   * Review the resource summary
2. **Acknowledge Capabilities**
   * Check the box acknowledging that CloudFormation will create IAM resources
   * This is required for the stack to create necessary service roles
3. **Create Stack**
   * Click "Create stack" to begin deployment
   * Monitor the deployment progress in the Events tab

<Info>The CloudFormation stack deployment typically takes 20-25 minutes.</Info>

## Monitoring Deployment

1. **Stack Status**
   * Monitor the stack status on the CloudFormation dashboard
   * Any errors will be displayed in the Events tab
2. **Event Monitoring**
   * Click on the "Events" tab to see real-time deployment progress

## Post-Deployment DNS Configuration

### Retrieve Load Balancer DNS Name

After successful deployment:

1. **Navigate to Outputs Tab**
   * Click on your stack name
   * Go to the "Outputs" tab
2. **Locate DNS Names**
   * Find the output value: **LoadBalancerDNS**: `internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com`

### Configure DNS Records

Create DNS records in your domain registry or DNS provider for the **exact domain name** you specified in the CloudFormation parameters.

#### AWS Route 53

If you're using AWS Route 53 to manage your domain, use **alias records** for the most AWS-native configuration:

1. **Navigate to Route 53 Console**
   * Open the [AWS Route 53 Console](https://console.aws.amazon.com/route53/)
   * Select your hosted zone

2. **Create Alias Records**
   * Click "Create record"
   * **Toggle the Alias switch** to enable alias functionality
   * Configure the following records:

| Type  | Name               | Alias Target                                                                             |
| ----- | ------------------ | ---------------------------------------------------------------------------------------- |
| **A** | `yourdomain.com`   | Select "Alias to Network Load Balancer" → Choose your region → Select your load balancer |
| **A** | `*.yourdomain.com` | Select "Alias to Network Load Balancer" → Choose your region → Select your load balancer |

<Frame caption="Route 53 Create Alias Records for Network Load Balancer">
  <img src="https://www.gitpod.io/images/docs/flex/runners/route53-dns-records.jpg" />
</Frame>

**Advantages of Route 53 Alias Records:**

* No additional charges for alias queries
* Automatic health checking
* Better performance with shorter resolution times
* AWS-native integration with load balancers

#### Standard DNS Providers (CNAME Records)

For other DNS providers or if you prefer CNAME records:

| Type  | Name               | Value                                                         | TTL |
| ----- | ------------------ | ------------------------------------------------------------- | --- |
| CNAME | `yourdomain.com`   | `internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com` | 300 |
| CNAME | `*.yourdomain.com` | `internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com` | 300 |

**Example DNS Configuration:**

If you entered `yourdomain.com` as your domain name parameter, configure:

```
yourdomain.com.     CNAME   internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com.
*.yourdomain.com.   CNAME   internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com.
```

<Note>
  ⚠️ **Important**: Replace `yourdomain.com` with the exact domain name you entered in the CloudFormation parameters.
</Note>

* DNS changes typically propagate within 5-60 minutes
* You can verify DNS resolution using tools like `nslookup` or `dig`
* Test both the root domain and a wildcard subdomain

## Verification and Testing

1. **Internal Network Test**
   * Verify that the load balancer is accessible from within your VPC
   * Test from an EC2 instance in the same VPC: `curl -k https://yourdomain.com/_health`
2. **DNS Resolution Test**
   ```bash
   nslookup yourdomain.com
   nslookup test.yourdomain.com
   ```

## Important Stack Outputs

After deployment, the following outputs provide important information for integration:

| Output Name                   | Description                    | Usage                                          |
| ----------------------------- | ------------------------------ | ---------------------------------------------- |
| **LoadBalancerDNS**           | Network Load Balancer DNS name | Point your DNS records here                    |
| **EnvironmentRoleArn**        | EC2 Environment Role ARN       | Used by Gitpod Environments for all operations |
| **InstanceProfileNameOutput** | EC2 Instance Profile           | Attached to Runner EC2 instances               |

## Private VPC Endpoints (Optional)

For enhanced security, you can connect to Gitpod's management plane using AWS PrivateLink instead of traversing the public internet.

<Info>
  **Cost consideration**: VPC endpoints incur additional AWS charges (\~\$7.20/month per endpoint per AZ plus data processing fees). See [AWS PrivateLink pricing](https://aws.amazon.com/privatelink/pricing/) for details.
</Info>

<Note>
  **us-east-1 region specific**: When creating VPC endpoints in the us-east-1 region, disable cross-region support. This is due to availability zone mapping differences between AWS accounts that can prevent endpoint creation. The endpoint only needs to exist in one AZ within your VPC - clients in other AZs can still reach it via DNS.
</Note>

### Creating the VPC Endpoint

Create an Interface VPC Endpoint to connect privately to Gitpod's management plane.

<Note>
  **Before you begin**: You'll need your VPC ID, subnet IDs, and security group ID. You can find these in the AWS VPC Console or from your CloudFormation stack outputs.

  **Important**: Your VPC must have both **DNS hostnames** and **DNS resolution** enabled for private DNS names to work properly. You can check and enable these in the VPC Console under Actions → Edit VPC settings.
</Note>

#### Using AWS CLI

```bash
# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
aws ec2 create-vpc-endpoint \
    --vpc-id vpc-xxx \
    --service-name com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2 \
    --vpc-endpoint-type Interface \
    --subnet-ids subnet-xxx subnet-xxx \
    --security-group-ids sg-xxx \
    --private-dns-enabled \
    --service-region us-east-1
```

For more CLI options and examples, see the [AWS CLI reference for create-vpc-endpoint](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-vpc-endpoint.html).

#### Using AWS PowerShell

```powershell
# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
New-EC2VpcEndpoint `
    -VpcId "vpc-xxx" `
    -ServiceName "com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2" `
    -VpcEndpointType "Interface" `
    -SubnetId @("subnet-xxx", "subnet-xxx") `
    -SecurityGroupId @("sg-xxx") `
    -PrivateDnsEnabled $true `
    -ServiceRegion "us-east-1"
```

For more PowerShell options and examples, see the [AWS PowerShell reference for New-EC2VpcEndpoint](https://docs.aws.amazon.com/powershell/v4/reference/items/New-EC2VpcEndpoint.html).

#### Using AWS Management Console

1. **Navigate to VPC Console**
   * Open the [AWS VPC Console](https://console.aws.amazon.com/vpc)
   * Select "Endpoints" from the left navigation

2. **Create Endpoint**
   * Click "Create endpoint"
   * **Name tag** (optional): Enter a descriptive name like `gitpod-management-plane`
   * **Service type**: Select "Endpoint services that use NLBs and GWLBs"

3. **Service Settings**
   * **Service name**: Enter `com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2`
   * **Enable Cross Region endpoint**: Check this box to connect across regions (Note: For **us-east-1** region, leave this unchecked)
   * **Region**: Select us-east-1 as the region
   * Click "Verify service" to confirm the service is available

<Frame caption="VPC Endpoint Service Settings - Enable Cross Region Support">
  <img src="https://www.gitpod.io/images/docs/flex/runners/vpc-endpoint-service-settings.png" />
</Frame>

4. **Network Settings**
   * **VPC**: Select the same VPC where your runner is deployed
   * **Enable DNS name**: Check this box to enable private DNS names (this allows `app.gitpod.io` to resolve to the endpoint)
   * **Subnets**: Choose private subnets in available AZs (can be the same subnets as your EC2 runner instances)
   * **Security groups**: Select or create a security group that allows HTTPS traffic (port 443, inbound). Include the runner security group and the security group for environment access (you can find these in the Output section of the Runner Cloud Formation template).

<Frame caption="VPC Endpoint Network Settings - Enable DNS Names">
  <img src="https://www.gitpod.io/images/docs/flex/runners/vpc-endpoint-network-settings.png" />
</Frame>

5. **Create and Verify**
   * Click "Create endpoint"
   * Wait for the endpoint status to become "Available"

For detailed console instructions, see the [AWS documentation on creating interface endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html).

### Security Group Configuration

Your VPC endpoint security group needs these rules:

**Inbound Rules:**

* **Type**: HTTPS (443)
* **Source**: Your runner subnets CIDR or the security group attached to your runner instances
* **Description**: Allow runner access to Gitpod management plane

**Outbound Rules:**

* **Type**: All traffic
* **Destination**: 0.0.0.0/0 (or keep the default outbound rule)

### Verification

After creating the VPC endpoint:

1. **Check endpoint status** in the VPC console
2. **Verify private DNS resolution in your VPC**:
   ```bash
   nslookup app.gitpod.io
   ```
   This should resolve to private IP addresses within your VPC
3. **Confirm private connectivity in Gitpod dashboard**:
   * Navigate to Settings → Runners in your Gitpod dashboard
   * Check your runner details - the **Connection type** should show as "Private"

<Frame caption="Runner Dashboard showing Private Connection Type">
  <img src="https://www.gitpod.io/images/docs/flex/runners/vpc-endpoint-private.png" />
</Frame>

<Note>
  With private DNS enabled, `app.gitpod.io` will automatically resolve to your VPC endpoint's private IP addresses, providing seamless private connectivity.
</Note>

For more information on VPC endpoints concepts and architecture, see the [AWS PrivateLink documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html).

## Next Steps

Once your Enterprise Runner is deployed, configure your [repository access](/gitpod/runners/aws/configuring-repository-access) and [Environment classes](/gitpod/runners/aws/environment-classes).

<CardGroup cols={2}>
  <Card title="Configure Repository Access" icon="git" href="/gitpod/runners/aws/configuring-repository-access">
    Set up access to your repositories
  </Card>

  <Card title="Troubleshoot" icon="wrench" href="/gitpod/runners/aws/troubleshooting-runners">
    Resolve common issues including networking problems and Runner configuration
  </Card>
</CardGroup>


# Environment classes
Source: https://www.gitpod.io/docs/gitpod/runners/aws/environment-classes



Environment classes define the specifications of your cloud development environments run by AWS runners. They control computing resources like instance type and disk size to meet your development needs.

## Default environment classes

Gitpod comes with several pre-configured environment classes for your AWS runners. These defaults offer a range of computing resources to support different development workloads.

By default, Gitpod creates the following environment classes:

| Class Name              | Instance Type             | Disk Size | Spot Instance |
| ----------------------- | ------------------------- | --------- | ------------- |
| Small                   | M6i Large (m6i.large)     | 45 GB     | No            |
| Regular                 | M6i XLarge (m6i.xlarge)   | 80 GB     | No            |
| Large                   | M6i 2XLarge (m6i.2xlarge) | 100 GB    | No            |
| Extra Large             | M6i 8XLarge (m6i.8xlarge) | 200 GB    | No            |
| Extra Large Spot        | M7i 8XLarge (m7i.8xlarge) | 200 GB    | Yes           |
| Data Science Large      | G5 4XLarge (g5.4xlarge)   | 300 GB    | No            |
| Data Science Large Spot | G5 4XLarge (g5.4xlarge)   | 300 GB    | Yes           |

### Creating custom environment classes

You can create custom environment classes tailored to your team's specific requirements:

1. Navigate to your Gitpod organization settings
2. Select **Environment Classes** under AWS runners
3. Click **Add Environment Class**
4. Configure the following:
   * **Name**: A clear, descriptive identifier
   * **Description**: Details about the purpose or resources
   * **Disk size**: Storage capacity for the environment
   * **Instance type**: AWS EC2 instance type determining CPU and memory
     * Supports any x64 EBS-enabled instance type (e.g., t3.medium, m5.large, c5.xlarge)

## Managing environment classes

<Frame caption="Add a new environment class">
  <img src="https://www.gitpod.io/images/docs/flex/runners/add-env-class.png" />
</Frame>

### Modifying environment classes

Once an environment class is created, only its name and description can be updated. To change configuration values like disk size or instance type, you must:

1. Create a new environment class with the desired specifications
2. Optionally disable the previous class

### Disabling environment classes

When you disable an environment class:

* Existing environments using this class will continue to run
* Users cannot create new environments with this class
* Scheduled or automated processes cannot create new environments with this class

## Using environment classes

Users can select environment classes when creating new development environments by:

* Manually selecting the environment class during environment creation
* Using a project that's configured to use a specific environment class

## Supported instance types

AWS runners support any instance type that meets the following requirements:

* Any EC2 instance with EBS volume support
* X64 architecture (Intel or AMD processors)

This gives you flexibility to choose from a wide range of compute options based on your development needs, including:

* General purpose: `t3.medium`, `t3.large`, `m5.large`, `m5.xlarge`
* Compute optimized: `c5.large`, `c5.xlarge`
* Memory optimized: `r5.large`, `r5.xlarge`
* Storage optimized: `i3.large`, `d2.xlarge`

Select an instance type that aligns with your workload requirements for CPU, memory, and cost efficiency.

### Considerations

* **Regional availability**: Not all instance types are available in every AWS region
* **Quotas**: Ensure your AWS account has sufficient quota for your chosen instance types
* **Costs**: Different instance families have varying pricing models
* **Instance generations**: Newer generations generally offer better price-performance ratio
* **Storage**: Use an instance type which has more storage than RAM.

For more information, see:

* [AWS EC2 Instance Types](https://aws.amazon.com/ec2/instance-types/)
* [Amazon EC2 Instance Type Families](https://aws.amazon.com/ec2/instance-types/#Instance_Types)

## Best practices

* Be prescriptive with your environment classes to standardize resources across your organization
* Limit the environment classes to what your teams actually need
* Create specialized classes for specific workloads (e.g., data processing, frontend development)
* Review usage patterns regularly and adjust available classes accordingly


# Overview
Source: https://www.gitpod.io/docs/gitpod/runners/aws/overview



AWS Runners allow you to deploy Gitpod's runner infrastructure directly within your own AWS VPC, giving you complete control over your development environments while maintaining security and compliance requirements.

When you deploy an AWS Runner, development environments are created as EC2 instances that are automatically sized based on your environment class requirements. The runner orchestrator itself runs as an ECS service within a dedicated ECS cluster in your AWS account. The entire deployment is automated through CloudFormation templates that we provide, making setup straightforward while ensuring best practices for security and scalability.

<Frame caption="Overview of Gitpod AWS runner architecture">
  <img src="https://www.gitpod.io/images/docs/flex/runners/flex-architecture.png" />
</Frame>

## Choose Your AWS Runner

Gitpod offers two AWS runner variants to meet different security and feature requirements. For information on runners generally, see [Self-Hosted Runners](/flex/runners).

<CardGroup cols={2}>
  <Card title="Standard Runner" icon="desktop" href="/gitpod/runners/aws/standard-runner/overview">
    **Quick & Easy**: 30-minute setup with CloudFormation template. Secure connectivity through Gitpod's central gateway eliminates complex networking configuration.
  </Card>

  <Card title="Enterprise Runner" icon="shield" href="/gitpod/runners/aws/enterprise-runner/overview">
    **Advanced Features**: AI agent integration, direct connectivity with your own domain/certificates, and enhanced security controls. Enterprise tier only.
  </Card>
</CardGroup>


# Sharing runners
Source: https://www.gitpod.io/docs/gitpod/runners/aws/sharing-runners

Learn how to share runners in Gitpod.

By default, a created runner can only be used by the user who created it or any admins in the organization. You can grant access to anyone in your organization using the sharing options:

<Frame caption="Sharing a runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/sharing-runner.png" />
</Frame>


# Overview
Source: https://www.gitpod.io/docs/gitpod/runners/aws/standard-runner/overview



The Standard AWS Runner provides a complete, easy-to-deploy solution for running Gitpod Environments in your AWS infrastructure. It connects securely through our central gateway, ensuring your Environments stay protected while maintaining simplicity.

## Key Features

* Super easy setup with CloudFormation template
* Complete AWS EC2 Runner solution
* Secure connectivity through Gitpod's central gateway

<Frame caption="Standard Runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/standard-runner.webp" />
</Frame>

## Gitpod Gateway

The Standard AWS Runner uses **Gitpod Gateway** to establish secure connectivity between your Runner infrastructure and Gitpod services. Gateway is an overlay network that creates encrypted tunnels to expose Environment ports and logs, as well as OAuth redirect URLs for Runners.

This eliminates the need to configure load balancers, SSL certificates, or custom DNS settings in your AWS environment. Gateway handles secure routing and authentication automatically, allowing users to access Environment services through Gitpod-managed domains while keeping your infrastructure private.

Gitpod operates gateways in **US and EU regions**. Runners automatically select the optimal gateway based on latency to ensure the best performance. If you need to enforce a specific gateway region, you can set the **Gateway API Endpoint** parameter in the CloudFormation template to:

* **US Gateway**: `https://us01.gitpod.dev:8443`
* **EU Gateway**: `https://eu01.gitpod.dev:8443`

## Prerequisites

Before deploying your Standard AWS Runner, ensure you have:

1. **AWS Account** - Use either an existing AWS account or create a new one

2. **AMI Access** - If your organization restricts AMI usage, allowlist the AMIs that Gitpod runners and environments run on:

   | AMI Name                                     | Owner Account ID | Owner  | Purpose                  |
   | -------------------------------------------- | ---------------- | ------ | ------------------------ |
   | `bottlerocket-aws-ecs-1-x86_64`              | `149721548608`   | Amazon | Runner service           |
   | `gitpod/images/gitpod-next/ec2-runner-ami-*` | `995913728426`   | Gitpod | Development environments |

   For more details, review our [AMI Requirements](/gitpod/runners/aws/detailed-access-requirements#ami-requirements) guide.

3. **Optional IAM Role** - Configure an IAM role if needed for enhanced permissions and security

## Network Requirements

<Frame caption="Network Configuration Diagram">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-networking.png" />
</Frame>

Your Standard AWS Runner requires specific network connectivity. **This applies to both deployment options below.**

### Required Ports

**User Access:**

* Port 29222 (TCP): SSH access from your users to development Environments

**Internal Communication:**

* Port 22999 (HTTP): Gitpod Runner to Environments
* Port 9090 (HTTP): Internal healthcheck within Gitpod Runner ECS task

### Required Outbound Endpoints

Your subnets must have outbound access to these endpoints:

| Endpoint                                                                                         | Purpose                           | Protocol | Port      |
| ------------------------------------------------------------------------------------------------ | --------------------------------- | -------- | --------- |
| `app.gitpod.io:443`                                                                              | Gitpod Service (management plane) | HTTPS    | 443       |
| `*.us01.gitpod.dev:443`, `*.eu01.gitpod.dev:443`, `us01.gitpod.dev:8443`, `eu01.gitpod.dev:8443` | Gitpod Service (Gitpod gateway)   | HTTPS    | 443, 8443 |
| `lighthouse.us01.gitpod.dev:4242`, `lighthouse.eu01.gitpod.dev:4242`                             | Gitpod Service (Gitpod gateway)   | UDP      | 4242      |
| `releases.gitpod.io/*`                                                                           | Gitpod Release Artifacts          | HTTPS    | 443       |
| `update.code.visualstudio.com/*`                                                                 | VS Code Server                    | HTTPS    | 443       |
| `*.vscode-unpkg.net`                                                                             | VS Code Extensions                | HTTPS    | 443       |
| `marketplace.visualstudio.com`                                                                   | VS Code Marketplace               | HTTPS    | 443       |
| `*.gallerycdn.vsassets.io`                                                                       | VS Code Assets                    | HTTPS    | 443       |
| `*.jetbrains.com`                                                                                | JetBrains IDEs                    | HTTPS    | 443       |
| `public.ecr.aws`                                                                                 | Container images                  | HTTPS    | 443       |
| `*.amazonaws.com`                                                                                | AWS API calls                     | HTTPS    | 443       |
| SCM Services                                                                                     | Source code repositories          | HTTPS    | 443       |
| (optional) Prometheus Remote write                                                               | Metrics endpoint                  | HTTPS    | 443       |
| (optional) Container Registries                                                                  | Custom container registries       | HTTPS    | 443       |

<Note>
  For more information about each of these outbound requirements, see [Detailed Access Requirements](/gitpod/runners/aws/detailed-access-requirements).
</Note>

## Deployment Options

Choose the deployment option that best fits your needs:

### Option 1: Quick Start (AWS Default VPC)

Get a working Runner with minimal configuration in under 30 minutes.

**Requirements:**

* Uses your AWS account's **default VPC** with Internet Gateway
* **Subnets** with [auto-assign public IP address enabled](https://docs.aws.amazon.com/vpc/latest/userguide/subnet-public-ip.html)
* Internet connectivity for all required endpoints listed above

**Ready to start?** Go to [Setup](/gitpod/runners/aws/standard-runner/setup) and use the quick start options.

### Option 2: Custom VPC Setup

Full control over networking, security, and deployment architecture.

**Requirements:**

* **Capacity Planning** - Follow our [Capacity Planning](/gitpod/runners/aws/capacity-planning) guide to determine your infrastructure requirements
* **Custom VPC** with your preferred networking setup:
  * Private subnets with NAT Gateway, Transit Gateway, VPN, or other connectivity solutions
  * Outbound internet access to all required endpoints listed above
* **Optional VPC endpoints** for cost optimization

<Note>
  **Important:** If using private subnets, ensure connectivity is available to the private IP addresses of the VPC from your local machine, as you'll need to connect to the EC2 instances.
</Note>

#### VPC Endpoints (Optional)

VPC endpoints can help reduce data transfer costs and improve security by keeping traffic within the AWS network. For a complete list of supported AWS services, see the [AWS Services page](/gitpod/runners/aws/detailed-access-requirements#aws-services).

> Note: Even with VPC endpoints, outbound internet access to Gitpod services is still required.

## Security Group Configuration

The CloudFormation template automatically creates a default security group for EC2 Environments with the necessary rules for Gitpod to function. This security group controls access to your development Environments.

**Default security group includes:**

* **Inbound:** Port 29222 (TCP) from any IP address (0.0.0.0/0) - for user SSH access to Environments
* **Inbound:** Port 22999 (HTTP) within VPC - for Runner orchestrator communication
* **Outbound:** All traffic to required endpoints

### Using a Custom Security Group (Optional)

<Warning>
  **Important:** This security group is applied to EC2 Environments. Incorrect configuration can disrupt user connections to Environments or communication between the Runner orchestrator and Environments.
</Warning>

If you need to restrict access further (recommended for production), you can create your own security group and provide it as a CloudFormation template parameter.

**Your custom security group must include these rules:**

**Inbound Rules:**

* Port 29222 (TCP): Allow from your users' IP ranges (restrict as needed for production)
* Port 22999 (HTTP): Allow from VPC CIDR block or from Gitpod Runner security group

**Outbound Rules:**

* Allow all outbound traffic to the endpoints listed in the Network Requirements section above

## Next Steps

<CardGroup cols={2}>
  <Card title="Set up Standard Runner" icon="rocket" href="/gitpod/runners/aws/standard-runner/setup">
    Deploy your Standard AWS Runner with our step-by-step guide
  </Card>

  <Card title="Troubleshooting AWS Runners" icon="wrench" href="/gitpod/runners/aws/troubleshooting-runners">
    Resolve common issues including networking problems and Runner configuration
  </Card>
</CardGroup>


# Setup
Source: https://www.gitpod.io/docs/gitpod/runners/aws/standard-runner/setup



Deploy your Standard AWS Runner using our CloudFormation template. This guide covers the step-by-step process to get your Runner up and running.

### Prerequisites

* Admin access to the Gitpod organization
* AWS account with networking configured (see [Overview](/gitpod/runners/aws/standard-runner/overview) for prerequisites)
* Permissions to deploy the CloudFormation stack

## Create AWS Runner

Go to Settings -> Runners, and press **Set up a new runner**:

<Frame caption="Runners in settings">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runners-settings.webp" />
</Frame>

After choosing AWS from the list of available providers, continue with the **Standard Runner template**. If you're looking to set up a more advanced Runner with custom ingress capabilities, consider deploying an [Enterprise Runner](/gitpod/runners/aws/enterprise-runner/setup).

<Frame caption="Provider selection">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-providers.webp" />
</Frame>

<Frame caption="CloudFormation Template selection">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-template-standard.webp" />
</Frame>

Choose a **name** and select the **AWS region** to deploy the Runner into, then press **Create**. This creates the Runner reference in Gitpod. You will now need to run the CloudFormation stack to fully deploy your Runner.

<Note>
  Runners are regional, and can only launch Environments in the AWS region
  they are deployed in. For a multi-region support we recommend to set up
  multiple Runners in different regions. The region cannot be changed once
  deployed, but you can deploy multiple Runners in different regions.
</Note>

<Frame caption="Add a AWS Runner">
  <img src="https://www.gitpod.io/images/docs/flex/runners/add-runner.webp" />
</Frame>

<Frame caption="Runner details">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-details.webp" />
</Frame>

## CloudFormation Template Deployment

Next, ensure you are signed into the right AWS account in the AWS console, and then press **Open AWS CloudFormation** to start deploying the Runner into your AWS account. This will link you to the AWS console to create the CloudFormation stack:

<Frame caption="Create stack in AWS">
  <img src="https://www.gitpod.io/images/docs/flex/runners/create-stack-in-aws.png" />
</Frame>

Most parameters are auto-filled already. For **Network Configuration**, choose a VPC (e.g. the default VPC) and one or more Availability Zones and subnets. The Runner will create Environments in the selected network configuration values.

<Frame caption="Parameters configuration in AWS">
  <img src="https://www.gitpod.io/images/docs/flex/runners/aws-parameters-configuration.png" />
</Frame>

When done with configuring the stack parameters, press **Create stack**. The stack is relatively simple and includes e.g. an ECS service and DynamoDB.

<Frame caption="AWS stack capabilities">
  <img src="https://www.gitpod.io/images/docs/flex/runners/stack-capabilities-note.png" />
</Frame>

<Frame caption="AWS stack component diagram">
  <img src="https://www.gitpod.io/images/docs/flex/runners/stack-component-diagram.png" />
</Frame>

Wait until the Stack is deployed successfully, and return to Gitpod Desktop.

<Info>The CloudFormation stack should deploy between 3-10 minutes.</Info>

Once deployed you should see a screen like this:

<Frame caption="AWS Runner configuration complete">
  <img src="https://www.gitpod.io/images/docs/flex/runners/runner-aws-config-complete-standard.png" />
</Frame>

## Next Steps

Once your Standard Runner is deployed and running, configure your repository access and Environment classes.

<CardGroup cols={2}>
  <Card title="Configure Repository Access" icon="git" href="/gitpod/runners/aws/configuring-repository-access">
    Set up access to your repositories
  </Card>

  <Card title="Troubleshoot" icon="wrench" href="/gitpod/runners/aws/troubleshooting-runners">
    Resolve common issues including networking problems and Runner configuration
  </Card>
</CardGroup>


# Troubleshooting AWS runners
Source: https://www.gitpod.io/docs/gitpod/runners/aws/troubleshooting-runners

Learn how to troubleshoot AWS runners.

If you encounter any issues while setting up or operating a Runner, please follow these steps:

* Review [the common problems](#common-problems).
* If the issue persists, [reach out to support](#contacting-support).

## Contacting Support

To start a support chat, use the bubble icon located in the bottom right corner of the application. When contacting support, please include the following information:

* Any error messages and relevant screenshots.
* [Runner ID and Version](#copy-runner-id-and-version) and [AWS Region](#find-cloudformation-stack).
* [Runner Logs](#retrieve-runner-logs-ecs-task-logs).

  <Frame caption="Report Issue">
    <img src="https://www.gitpod.io/images/docs/flex/desktop/report_issue.png" />
  </Frame>

### Copy Runner ID and Version

* Navigate to **Settings > Runners**.
* Locate your Runner card.
* Click `...` in the top right corner and select `Copy ID`.
* The Runner Version is displayed as the last item in the menu.

  <Frame caption="Find Runner ID and Version">
    <img src="https://www.gitpod.io/images/docs/flex/runners/runner_id_and_version.png" />
  </Frame>

### Find CloudFormation Stack

* Navigate to **Settings > Runners**.
* Open the Runner card to find the Stack Name, URL, and region.

### Retrieve Runner Logs (ECS Task Logs)

You can adjust the log level of your Runner from the Runner Configuration section to get more detailed logs for troubleshooting. See [Setting up an AWS Runner](/flex/runners/aws/setup-aws-runners#log-level-configuration) for log level configuration options.

#### Using ECS Console

To view the logs for the Runner using the ECS console:

* Navigate to [the AWS ECS console](https://console.aws.amazon.com/ecs).
* Locate the cluster by [the stack name](#find-cloudformation-stack).
* Select the service associated with the Runner.
* Go to the **Tasks** tab and find the most recent failed or active task.
* Click the task ID to open the details.
* Check the **Logs** tab or find the CloudWatch log stream.

> Note that each task has two log groups: one for the Runner itself and another for Prometheus (monitoring); we need the former.

#### Using AWS CLI

To look up the cluster name and task ID using AWS CLI, follow these commands:

1. To list all clusters and find your cluster name by [the stack name](#find-cloudformation-stack):

```sh
aws ecs list-clusters
```

2. To list tasks in a specific cluster and find your task ID:

```sh
aws ecs list-tasks --cluster <cluster-name>
```

3. Once you have the cluster name and task ID, you can view the logs for the Runner:

```sh
aws ecs describe-tasks --cluster <cluster-name> --tasks <task-id>
```

### Monitoring and Metrics

If you have configured metrics collection, your monitoring system will receive Runner metrics. For information on configuring metrics collection, see [Setting up an AWS Runner](/flex/runners/aws/setup-aws-runners#enable-metrics-collection).

## Common Problems

Network misconfigurations are the most frequent causes of installation issues. Please refer to the [infrastructure prerequisites](/flex/runners/aws/aws-infrastructure-prerequisites) to ensure all requirements are met. Below are common problems along with their diagnostics.

### CloudFormation Stack Fails

* **Symptoms:**

  * Stack Event Status: `ROLLBACK_COMPLETE` or `ROLLBACK_IN_PROGRESS` due to missing VPC, availability zones, or subnets.
  * Stack Event Status Reasons:
    * `Parameter validation failed: parameter value for EC2RunnerInstancesSubnet does not exist.`
    * `Parameter validation failed: parameter value for parameter name EC2RunnerInstancesSubnet does not exist.`
    * `Parameter validation failed: parameter value for parameter name EC2RunnerAzs does not exist.`

* **Diagnostics:**

  * On the initial page of the CloudFormation stack creation, ensure you select a VPC, at least one availability zone, and a subnet.
  * Choose subnets across multiple availability zones for fault tolerance.

### Runner Task Fails

* **Symptoms:**

  * Stack Event Status: `CREATE_FAILED` or `ROLLBACK_IN_PROGRESS` because the [Runner task fails](#retrieve-runner-logs-ecs-task-logs) to launch or is stuck in a pending state.
  * Stack Event Status Reason: `ECS Deployment Circuit Breaker was triggered.`
  * [Runner task fails](#retrieve-runner-logs-ecs-task-logs) initialization with errors such as `ResourceInitializationError: ...`.
  * Secrets Manager or other AWS services are inaccessible to the Runner.
  * The Runner cannot pull container images or resolve DNS queries.

* **Diagnostics:**

  * Verify that the VPC has an **Internet Gateway** or **NAT Gateway** configured.
  * Update the route tables to direct public subnets to the Internet Gateway and private subnets to the NAT Gateway.
  * For private subnets, add VPC endpoints for services like Secrets Manager, S3, and ECR.
  * Confirm that security groups allow outbound traffic to the required services.

### Instance Type Not Available

If you encounter an error stating that the requested instance type is unavailable in a specific availability zone (e.g., "The selected instance type m6i.xlarge is not available in the automatically assigned zone us-east-1e"), this is often due to regional or zone-specific availability constraints within AWS.

> Some zones, like `us-east-1d` and `us-east-1e`, have been reported to experience resource shortages more frequently. If possible, avoid using these zones exclusively and instead install your runners across multiple zones or regions.

Here's how you can address this:

1. **Install a Runner to a Different Region**:

   * Some instance types may be unavailable in certain regions or zones due to resource constraints. Refer to [AWS instance type availability](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-instance-regions.html) for details. If necessary, install runners to use a different AWS region that supports your preferred instance type.

2. **Select Multiple Availability Zones**:

   * When installing a Runner using the [AWS CloudFormation Stack](/flex/runners/aws/setup-aws-runners#cloudformation-template), ensure that you select multiple subnets. For example, instead of restricting your Environment to only the subnet corresponding to `us-east-1e`, include subnets corresponding to `us-east-1a` and `us-east-1b` zones to improve availability.
     * You can also [update the existing stack parameters](/flex/runners/aws/update-runner#updating-cloudformation-parameters).

3. **Use an Alternate Instance Type**:

   * If the desired instance type (e.g., `m6i.xlarge`) is unavailable, consider using a different instance type, such as `c5.xlarge`, which may have better availability.
   * To update, [create a new Environment class](/flex/runners/aws/environment-classes) using the alternate instance type and disable the existing class.

4. **Retry Later**:

   * Instance availability can be transient. If none of the above options resolve the issue, wait and try again later, as AWS resources might become available after a brief period.

### Unexpected Costs

* **Symptoms:**

  * You notice unexpected charges in your AWS bill that you believe are related to the Runner infrastructure.
  * You continue receiving bills for resources even after deleting a Runner.

* **Diagnostics:**

  * Use the [Controls for Managing Costs](/flex/runners/aws/aws-runner-costs#controls-for-managing-costs) guide to investigate the specific AWS resources contributing to the charges.
  * After [deleting a runner](/flex/runners/aws/delete-runner), verify that the associated CloudFormation stack has been fully deleted. Additionally, check for any residual resources such as EC2 instances or EBS volumes associated with Environment IDs, and manually delete them if necessary to avoid ongoing costs.

### AWS SSM Access Requirements

* **Symptoms:**

  * New Environments fail to start with error message: `AWS account policy blocks ssm:SendCommand, which is required for starting Environments. See our docs for details on how to resolve this: https://www.gitpod.io/docs/gitpod/runners/aws/troubleshooting#aws-ssm-access-requirements`
  * Runner is marked as degraded with the above error message
  * Devcontainer build cache credentials cannot be set/refreshed, resulting in slower startup times

* **Diagnostics:**

  * Gitpod Environments require AWS Systems Manager (SSM) access to properly initialize and manage development Environments.
  * The `ssm:SendCommand` permission is used to send the initial Environment configuration and refresh devcontainer build cache credentials in Environments, and `ssm:GetCommandInvocation` to verify the result.
  * These permissions can be blocked by Service Control Policies (SCPs) at the AWS account level.
  * Check if your AWS account has Service Control Policies (SCPs) that might be blocking SSM access. The Runner role (containing `gitpodflexrunnerrole`) must be able to run these commands against EC2 instances in the account.
  * Test if SSM access is working by attempting to send a command to an EC2 instance or starting a new Environment.

* **Resolution:**

  * Contact your AWS administrator to review the current SCP that's blocking SSM access.
  * Request an exception for the Gitpod Runner's IAM role to allow:
    ```json
    {
    	"Version": "2012-10-17",
    	"Statement": [
    		{
    			"Effect": "Allow",
    			"Action": ["ssm:SendCommand", "ssm:GetCommandInvocation"],
    			"Resource": [
    				"arn:aws:ec2:*:*:instance/*",
    				"arn:aws:ssm:*:*:command/*"
    			]
    		}
    	]
    }
    ```
    Alternatively, if your existing policy denies the permission for all accounts, add an exception for your Gitpod Runner account:
    ```json
    {
    	"Version": "2012-10-17",
    	"Statement": [
    		{
    			"Effect": "Deny",
    			"Action": ["ssm:SendCommand", "ssm:GetCommandInvocation"],
    			"Resource": [
    				"arn:aws:ec2:*:*:instance/*",
    				"arn:aws:ssm:*:*:command/*"
    			],
    			"Condition": {
    				"StringNotEquals": {
    					"aws:PrincipalAccount": [
    						"<GITPOD_RUNNER_AWS_ACCOUNT_ID>"
    					]
    				}
    			}
    		}
    	]
    }
    ```

* **Security Note:**

  * The SSM commands are only used for Environment initialization and configuration.
  * They are sent over encrypted channels and follow AWS security best practices.

### Network Connectivity Issues

If you experience connectivity issues with your AWS Runner, follow these troubleshooting steps to diagnose and resolve common networking problems.

#### Common Network Issues

If you experience connectivity issues:

1. **Verify security group configurations**
   * Ensure port 29222 is open for SSH access to development Environments
   * Check that outbound rules allow HTTPS traffic to required endpoints
   * Verify internal communication on port 22999 is allowed

2. **Check route table configurations**
   * Confirm routes to internet gateway (for public subnets) or NAT gateway (for private subnets)
   * Verify default routes are properly configured

3. **Validate network ACL settings**
   * Ensure Network ACLs aren't blocking required traffic
   * Check both inbound and outbound rules

4. **Confirm DNS resolution is working**
   * Test DNS resolution for `app.gitpod.io` and `*.us01.gitpod.dev`
   * Verify VPC DNS resolution and DNS hostnames are enabled

5. **Test connectivity to Gitpod services**
   * From an EC2 instance in your Runner's subnet, test connectivity to required endpoints
   * Use tools like `curl` or `telnet` to verify connectivity

#### Health Endpoint Connectivity Test

For Enterprise Runners, test the health endpoint to verify network connectivity and load balancer functionality:

```bash
# Test health endpoint connectivity (returns HTTP 200 on success)
curl -v https://<your-domain>/_health
```

Replace `<your-domain>` with your actual domain name configured during setup. A successful response returns HTTP 200 status code, indicating that:

* DNS resolution is working correctly
* Load balancer is accessible from your network
* SSL/TLS certificate is properly configured
* Basic network connectivity is established

If this test fails, check:

* DNS configuration and propagation
* Security group rules allowing HTTPS traffic
* Load balancer health and target group status
* SSL certificate validity and domain matching

#### Required Endpoints Connectivity Test

Test connectivity to these critical endpoints from your Runner's subnet:

```bash
# Test HTTPS connectivity to Gitpod services
curl -I https://app.gitpod.io
curl -I https://api.us01.gitpod.dev

# Test connectivity to AWS services
curl -I https://public.ecr.aws
curl -I https://s3.amazonaws.com
```

#### Restarting the Runner After Networking Changes

After applying networking changes (such as security group updates, route table modifications, or VPC endpoint configurations), you may need to restart the Runner ECS task to ensure the changes take effect.

##### Using the AWS Console

1. Navigate to the [AWS ECS console](https://console.aws.amazon.com/ecs)
2. In the left sidebar, click **Clusters**
3. Locate and click on the cluster with your stack name (found in **Settings > Runners** in Gitpod)
4. In the **Services** tab, click on the service associated with your Runner
5. Click the **Update** button
6. In the **Deployment configuration** section, check the box for **Force new deployment**
7. Click **Update** at the bottom of the page
8. ECS will start a new task with the updated networking configuration and gracefully stop the old one

##### Using AWS CLI

You can also restart the Runner using the AWS CLI:

```bash
# Get your cluster name and service name
aws ecs list-clusters
aws ecs list-services --cluster YOUR_CLUSTER_NAME

# Force a new deployment
aws ecs update-service \
  --cluster YOUR_CLUSTER_NAME \
  --service YOUR_SERVICE_NAME \
  --force-new-deployment
```

#### Verification Steps

After making networking changes and restarting the Runner:

1. **Check Runner status in Gitpod**
   * Go to **Settings > Runners** in your Gitpod dashboard
   * Verify the Runner shows as "Connected"

2. **Test Environment creation**
   * Create a new Environment using the Runner
   * Verify the Environment starts successfully

3. **Monitor CloudWatch logs**
   * Check ECS task logs for any connectivity errors
   * Look for successful connections to Gitpod services


# Zscaler Compatibility Issues
Source: https://www.gitpod.io/docs/gitpod/runners/aws/troubleshooting-zscaler

Troubleshoot common issues when using Gitpod with Zscaler security solutions

Organizations using Zscaler as their security gateway may encounter various compatibility issues with Gitpod services. This guide helps identify and resolve the most common problems.

## Common Issues

### HTTP/2 Protocol Downgrade

**Symptoms:**

* Gitpod CLI requests fail unexpectedly
* Connection timeouts or protocol errors
* Performance degradation in web requests

**Root Cause:**
Zscaler downgrades HTTP/2 connections to HTTP/1.1 by default for encrypted traffic that undergoes SSL inspection, which can cause compatibility issues with Gitpod services that rely on HTTP/2.

**Solutions:**

1. **Enable HTTP/2 for SSL-Inspected Traffic (Recommended)**
   * Contact your Zscaler administrator
   * Request enabling HTTP/2 support for encrypted traffic subject to SSL inspection
   * This setting is under `Administration > Advanced Settings`
   * Enable the toggle for HTTP/2 support for SSL-inspected requests
   * For more information see [Zscaler's documentation](https://www.zscaler.com/de/blogs/product-insights/http-2-better-faster-stronger)

### SSL Certificate Verification Failures

**Symptoms:**

* VS Code extension fails to connect to Gitpod environments
* Certificate verification errors in application logs
* TLS handshake failures with "certificate verify failed" messages
* Applications showing "untrusted certificate" warnings

**Root Cause:**
Zscaler performs SSL inspection by intercepting HTTPS traffic and presenting its own certificates instead of the original server certificates. Applications using custom certificate stores (like VS Code) may not trust these Zscaler-generated certificates.

**Important Note:** Gitpod does not implement certificate pinning, so SSL inspection should work once the Zscaler certificates are properly trusted by the system.

**Identifying SSL Inspection:**
Run this command to check if Zscaler is intercepting certificates:

```bash
curl -I -vv https://app.gitpod.io
```

**With Zscaler SSL Inspection:**

```
* Server certificate:
*  subject: CN=app.gitpod.io; O=Zscaler Inc.; OU=Zscaler Inc.
*  start date: Mar 17 13:23:09 2025 GMT
*  expire date: Mar 30 03:38:20 2025 GMT
*  issuer: C=US; ST=California; O=Zscaler Inc.; OU=Zscaler Inc.; CN=Zscaler Intermediate Root CA (zscalerthree.net) (t)
```

**Without SSL Inspection:**

```
* Server certificate:
*  subject: CN=app.gitpod.io
*  start date: Aug 7 00:00:00 2024 GMT
*  expire date: Sep 5 23:59:59 2025 GMT
*  issuer: C=US; O=Amazon; CN=Amazon RSA 2048 M03
```

**Solutions:**

1. **Disable SSL Inspection for Gitpod (Recommended)**
   * Contact your network security team
   * Request adding `app.gitpod.io` to the SSL inspection exemption list
   * This ensures applications receive authentic Gitpod certificates

2. **Configure VS Code to Use System Certificates**

   * **Requirements:** VS Code 1.97 or later
   * **Steps:**
     1. Open VS Code
     2. Go to `File > Preferences > Settings`
     3. Search for "System certificates" and ensure it's enabled (default)
     4. Search for "Fetch Additional Support" and ensure it's enabled (default)
     5. Restart VS Code and test connection

   **If issues persist, try these additional settings:**

   * Enable "Electron Fetch" setting
   * Enable "System Certificates V2" setting
   * Restart VS Code after each change

### Runner Connection Issues

**Symptoms:**

* Gitpod runners cannot connect to the gateway
* Runner status not properly reported in dashboard
* OAuth authentication failures with external services (GitLab, GitHub)
* "Connection refused" or timeout errors in runner logs

**Root Cause:**
Zscaler may block or interfere with specific IP ranges and protocols that Gitpod services need, particularly:

* Static IP addresses for Lighthouse connectivity
* OAuth callback URLs and authentication flows
* Runner-to-gateway communication protocols

**Solutions:**

1. **Whitelist Gitpod IP Ranges**
   * Contact your network team to whitelist Gitpod's static IP addresses
   * This is particularly important for Lighthouse connectivity
   * See [Network Connectivity Requirements](/flex/runners/aws/aws-infrastructure-prerequisites#network-connectivity-requirements) for the current IP ranges

2. **Temporary Workaround: Use Personal Access Tokens**
   * While IP whitelisting is being configured, use Personal Access Tokens (PATs) instead of OAuth
   * This bypasses some authentication flows that may be blocked

## Configuration Checklist

Work with your network and security teams to implement these Zscaler configurations:

#### Phase 1: SSL Inspection Exemptions

* [ ] Add `app.gitpod.io` to SSL inspection bypass list
* [ ] Test certificate verification with `curl -I -v https://app.gitpod.io`
* [ ] Verify certificate issuer shows Amazon RSA (not Zscaler)

### HTTP/2 Protocol Support

* [ ] Raise provisioning ticket with Zscaler support to enable HTTP/2 backend configuration
* [ ] Enable HTTP/2 in SSL inspection policy pages
* [ ] Enable HTTP/2 for encrypted traffic subject to SSL inspection in Advanced Settings

### Network Access

* [ ] Whitelist Gitpod static IP ranges for runner connectivity
* [ ] Ensure WebSocket connections are allowed
* [ ] Verify GRPC traffic is not blocked

## Testing Your Configuration

After implementing the above changes:

1. **Test Certificate Trust**
   ```bash
   curl -I -v https://app.gitpod.io
   ```
   Verify the certificate issuer shows Amazon RSA (authentic) rather than Zscaler

2. **Test Gateway Certificate (for AWS runners)**
   ```bash
   curl -I -v https://us01.gitpod.dev
   ```
   You can also verify the gateway certificate using [SSL Labs](https://www.ssllabs.com/ssltest/analyze.html?d=us01.gitpod.dev\&s=52.22.228.114\&hideResults=on)

3. **Test Protocol Support**
   ```bash
   curl --http2 -I https://app.gitpod.io
   ```
   Verify HTTP/2 protocol is maintained

4. **Test Gitpod Services**
   * Try connecting with VS Code extension
   * Test Gitpod CLI commands
   * Verify runner connectivity if applicable

## Getting Help

If issues persist after implementing these solutions:

1. Collect diagnostic information:
   * Output from `curl -I -vv https://app.gitpod.io`
   * VS Code and Gitpod extension logs
   * Network configuration details


# Updating a Runner
Source: https://www.gitpod.io/docs/gitpod/runners/aws/update-runner

Learn how to update your AWS runner.

This guide explains how to update your AWS runner to ensure you have the latest features, improvements, and security patches. There are three methods to update your runner:

* [Automatic Updates](#automatic-updates): The AWS runner handles most updates automatically with minimal user intervention.
* [Updating Infrastructure](#updating-infrastructure): For significant changes, manual updates via CloudFormation are required.
* [Updating CloudFormation Parameters](#updating-cloudformation-parameters): Update specific configuration settings through CloudFormation parameters.

Follow the instructions in each section to keep your AWS runner up-to-date and running smoothly.

## Automatic Updates

The AWS runner includes a built-in update mechanism that automatically manages application updates. Here's how it works:

### Update Check Process

* The updater performs version checks periodically
* During each check, the runner:
  * Queries the Gitpod API for the available version
  * Compares the current version with the available version
  * Verifies infrastructure version compatibility

### Update Eligibility

A runner is eligible for updates when:

* It is on the stable channel
* Auto-updates are enabled for the version
* The infrastructure version matches the current runner's infrastructure version
* The available version is newer than the current version
* The runner image is different from the currently running image

### Update Process Flow

When an update is available, the following steps occur:

1. **Preparation**
   * The updater acquires a lock to ensure only one update process runs at a time
   * Creates a new task definition with the updated runner image
   * Maintains all existing configuration and IAM roles

2. **Deployment**
   * Updates the ECS service with the new task definition
   * Monitors the deployment progress
   * Uses circuit breaker protection for failed deployments

3. **Health Checks**
   * New container must pass health checks:

4. **Rollback**
   * If deployment fails, automatic rollback to previous version
   * Failed updates are logged and marked accordingly

### Infrastructure Version

* Ensures compatibility between runner and infrastructure
* Updates only proceed with matching versions

### Monitoring

* All update activities logged to AWS CloudWatch Logs
* Update process visible in AWS ECS console
* Prometheus metrics available (when configured on the runner)

### Important Notes

* Updates are non-disruptive to running workloads
* Process is fully automated with no manual intervention needed
* Failed updates don't impact existing runner functionality
* Runner maintains configuration and credentials through updates

> Tip: View the current version of the runner on the runner card under **Settings > Runners**.

## Updating Infrastructure

Certain updates, particularly those involving significant infrastructural changes, cannot be applied automatically. Follow these steps to apply updates:

<Warning>
  Upgrading CloudFormation templates that were applied from January 2025 or earlier will cause existing environments to no longer be accessible due to SSH port changes. Before upgrading, either stop and discard existing environments, or manually update the security group to allow access from 0.0.0.0/0 to port 22 (in addition to port 29222) after upgrading the stack.
</Warning>

1. Open the CloudFormation stack used for the runner in the AWS console.

2. Select **Update** to modify the stack configuration.

3. Select the **Replace existing template** option and enter the following URL in the **Amazon S3 URL** field:

   ```plaintext
   https://gitpod-flex-releases.s3.amazonaws.com/ec2/stable/gitpod-ec2-runner.json
   ```

   <Frame caption="Replace Existing Template">
     <img src="https://www.gitpod.io/images/docs/flex/runners/update_stack_replace_existing.png" />
   </Frame>

4. Review and adjust the parameters as needed.

5. Follow the remaining steps in the wizard to update the stack.

## Updating CloudFormation Parameters

To update only the CloudFormation (CF) parameters, such as VPC, subnets, or other configuration settings, follow these steps:

1. Open the CloudFormation stack used for the runner in the AWS console.

2. Select **Update** to modify the stack configuration.

3. Choose **Use existing template** when prompted, as shown below:

   <Frame caption="Use Existing Template">
     <img src="https://www.gitpod.io/images/docs/flex/runners/update_stack_use_existing.png" />
   </Frame>

4. Adjust the parameters in the update wizard to reflect the desired changes (e.g., updating VPC or subnet configurations).

5. Complete the remaining steps in the wizard to update the stack.

### Expanding Availability Zones

When expanding to additional availability zones, keep in mind that availability is determined by the subnets where your EC2 instances are running. The availability zones parameter helps you identify available subnets, but modifying this parameter alone will not impact availability. Ensure that your subnets are correctly configured to support the desired availability zones.

Use the **VPC Resource Map** in the AWS console to find subnets corresponding to your desired availability zones.

<Frame caption="VPC Resource Map">
  <img src="https://www.gitpod.io/images/docs/flex/runners/vpc_resource_map.png" />
</Frame>


# Updates and Maintenance
Source: https://www.gitpod.io/docs/gitpod/runners/linux/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:

1. Stop the runner

   * If running in the terminal, press Ctrl+C
   * If running as a service:

     ```bash
     sudo systemctl stop gitpod-runner
     ```

     <Note>
       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.
     </Note>

2. Run the update command:

   ```bash
   gitpod runner update
   ```

3. Restart the runner
   * If running in the terminal:
     ```bash
     gitpod runner run
     ```
   * If running as a service:
     ```bash
     sudo systemctl start gitpod-runner
     ```

## Monitoring

### Logs

* If running in the terminal, logs are printed directly to stdout
* If running as a systemd service, view logs with:
  ```bash
  journalctl -u gitpod-runner
  ```

Use the `-f` flag to follow logs in real-time:

```bash
journalctl -u gitpod-runner -f
```

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

1. **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

2. **Log Management**

   * If using systemd, consider configuring log rotation
   * Monitor logs periodically for warnings or errors
   * Keep track of resource usage patterns

3. **Backup Considerations**

   * The runner stores environment data in `~/gitpod-runner`
   * Consider this location in your backup strategy if needed

4. **System Maintenance**
   * Keep the host system updated
   * Monitor system health
   * Maintain sufficient free resources

## Common Maintenance Tasks

### Checking Runner Status

```bash
# If running as a service
sudo systemctl status gitpod-runner
```

### Restarting the Runner

```bash
# If running as a service
sudo systemctl restart gitpod-runner
```

## Deleting the Runner

To completely remove a runner:

1. Delete the runner from Gitpod in Settings -> Runners

2. 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:
     ```bash
     sudo systemctl stop gitpod-runner
     ```

   b. Remove runner files and environment data:

   ```bash
   rm -rf ~/gitpod-runner
   ```

   c. If you set up a systemd service, remove it:

   ```bash
   sudo systemctl disable gitpod-runner
   sudo rm /etc/systemd/system/gitpod-runner.service
   ```

   d. Remove the sudoers configuration:

   ```bash
   sudo rm /etc/sudoers.d/gitpod-runner
   ```

## Next Steps

* [Troubleshooting guide](/flex/runners/linux/troubleshooting) for common issues
* [System requirements](/flex/runners/linux/requirements) for reference
* [Setup guide](/flex/runners/linux/setup) for installation details


# Linux Runner
Source: https://www.gitpod.io/docs/gitpod/runners/linux/overview



The Linux runner lets you run Gitpod development environments directly on your Linux machine. It's designed to be an easy way to try Gitpod while maintaining full control over your infrastructure and costs.

## Key Features

* **Simple Setup**: Quick installation on your Linux machine
* **Fixed Costs**: Only pay for your hardware
* **Local Control**: Full control over your infrastructure
* **Local Network Access**: Direct access to local network services

## Architecture

The Linux runner consists of:

* **Runner Service**: Orchestrates environment lifecycle
* **Virtual Machines**: Uses cloud-hypervisor for environment isolation
* **Network Layer**: Manages VM connectivity and local network access
* **Management Plane Integration**: Connects to Gitpod for environment management

## Use Cases

Best suited for:

* **Evaluation**: Quick start without cloud infrastructure
* **Small Teams**: 2-10 developers sharing the runner for their environments
* **Local Network Access**: Teams needing local network service access
* **Cost Control**: Fixed infrastructure costs

## Comparison with AWS Runner

| **Feature**     | **Linux Runner**           | **AWS Runner**            |
| --------------- | -------------------------- | ------------------------- |
| Infrastructure  | Single Linux machine       | AWS cloud infrastructure  |
| Scaling         | Fixed to machine resources | Horizontal scaling        |
| Cost Model      | Fixed (hardware only)      | Pay per use               |
| Setup           | Simple local setup         | AWS account required      |
| Best For        | Evaluation & small teams   | Production & larger teams |
| Resource Limits | 10 environments max        | AWS quota based           |

## Limitations

* No horizontal scaling (single machine)
* Maximum 10 concurrent environments per runner
* AMD64 architecture only (no ARM support)
* Requires virtualization support (KVM)

## Network Access

Environments can access your local network, enabling:

* Local service integration
* Development database access
* On-premises tool connectivity

<Warning>
  Consider network policies as environments have full access to your local
  network.
</Warning>

## Getting Started

1. [Check Requirements](/flex/runners/linux/requirements)
2. [Install & Configure](/flex/runners/linux/setup)
3. [Setup Repository Access](/flex/runners/linux/setup#repository-access)
4. [Configure Environment Classes](/flex/runners/linux/setup#environment-classes)
5. [Share with your team](/flex/runners/aws/sharing-runners)

## Additional Resources

* [Maintenance Guide](/flex/runners/linux/maintenance)
* [Troubleshooting](/flex/runners/linux/troubleshooting)


# System Requirements
Source: https://www.gitpod.io/docs/gitpod/runners/linux/requirements



## Hardware Requirements

### CPU

* Architecture: x86\_64/AMD64
* Virtualization support (VMX or SVM)
* KVM enabled

```bash
# Verify CPU support
grep -E 'svm|vmx' /proc/cpuinfo
# Verify KVM
ls /dev/kvm
```

### Memory

* Base: 100MB for runner service
* Per Environment: 2GB minimum
* Example sizing:
  * 3 environments: 6.1GB minimum
  * 5 environments: 10.1GB minimum
  * 10 environments: 20.1GB minimum

### Storage

* Minimum: 10GB free space
* Recommended: 50GB+ for multiple environments
* SSD recommended for performance

```bash
# Check free space
df -h
```

## Operating System

### Supported Distributions

* Ubuntu 24.04 LTS
* CentOS 9
* Fedora 40
* Other modern distributions (may need additional configuration)

### Architecture Support

* ✅ AMD64 (x86\_64)
* ❌ ARM64/AArch64 (not supported)

## System Configuration

> You don't need to make these changes manually. The setup command will:

* Check for all required configurations
* Show you exactly what changes are needed
* Guide you through making any necessary changes

The following sections describe what the setup will check and configure:

#### 1. Kernel Modules

* **What**: The following kernel modules are required:

  Network modules:

  * `bridge`: Network bridge support
  * `br_netfilter`: Bridge netfilter support
  * `nf_tables`: Netfilter tables
  * `nf_nat`: Network address translation
  * `nf_conntrack`: Connection tracking
  * `xt_conntrack`: Connection tracking netfilter module
  * `tun`: Network tunneling support

  Virtualization modules:

  * `kvm`: Base KVM module
  * `kvm_intel` (Intel CPUs) or `kvm_amd` (AMD CPUs): CPU-specific virtualization

* **Why**: These modules enable:
  * Network isolation and routing between environments
  * Virtual machine creation and management
  * Secure network communication

#### 2. Network Settings

* **What**: Enable IP forwarding and bridge filtering
* **Why**: Allows environments to access the internet and communicate securely
* **Changes**:

  ```bash
  # Apply settings
  sudo sysctl -w net.ipv4.ip_forward=1
  sudo sysctl -w net.bridge.bridge-nf-call-iptables=1
  sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=1

  # Make permanent
  sudo bash -c 'cat > /etc/sysctl.d/99-gitpod-runner.conf << EOF
  net.ipv4.ip_forward=1
  net.bridge.bridge-nf-call-iptables=1
  net.bridge.bridge-nf-call-ip6tables=1
  EOF'
  ```

#### 3. UFW Configuration (if using UFW)

* **What**: Allow forwarding in UFW firewall
* **Why**: Required for environment network connectivity
* **Changes**:

  ```bash
  # Edit /etc/default/ufw
  DEFAULT_FORWARD_POLICY="ACCEPT"

  # Reload UFW
  sudo ufw reload
  ```

### Reverting Changes

To revert all system changes after uninstalling the runner:

```bash
# 1. Remove configuration files
sudo rm /etc/modules-load.d/gitpod-runner.conf
sudo rm /etc/sysctl.d/99-gitpod-runner.conf

# 2. Restore UFW settings (if modified)
sudo sed -i 's/DEFAULT_FORWARD_POLICY="ACCEPT"/DEFAULT_FORWARD_POLICY="DROP"/' /etc/default/ufw
sudo ufw reload

# 3. Restore system settings
sudo sysctl -w net.ipv4.ip_forward=0
sudo sysctl -w net.bridge.bridge-nf-call-iptables=0
sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=0

# 4. Unload kernel module(s) (optional). Example:
sudo modprobe -r br_netfilter
```

> Save your original network configuration before making changes if you need to restore exact previous values.

### Connectivity

* Outbound internet access required for:
  * Gitpod services
  * Container registries
  * Source code repositories

### Network Access

* Runner creates virtual networks
* Environments can access local network
* Consider security implications

## User Permissions

### Installation

Requires root/sudo for:

* Installing Gitpod CLI
* Setting capabilities
* Configuring network
* Setting up systemd service

### Operation

* Runs without root after setup
* Service user needs network capabilities

## Unsupported Configurations

❌ Will not work on:

* Virtual machines
* Cloud instances
* ARM-based systems
* Windows/macOS
* Systems without hardware virtualization

## Validation

The runner automatically validates these requirements during setup. When you run `gitpod runner setup`, it will check:

* CPU virtualization support
* KVM availability
* Memory and disk space
* Network configuration
* Required system capabilities

If any requirements are not met, the setup will provide specific instructions for resolving the issues.

## Next Steps

Once requirements are met:

1. [Set up your Linux runner](/flex/runners/linux/setup)
2. [Configure environment classes](/flex/runners/linux/setup#environment-classes)
3. [Set up repository access](/flex/runners/linux/setup#repository-access)

If you encounter issues, check our [troubleshooting guide](/flex/runners/linux/troubleshooting).


# Setting up Linux Runners
Source: https://www.gitpod.io/docs/gitpod/runners/linux/setup



This guide walks you through setting up a Linux runner. Before starting, ensure your system meets the [requirements](/flex/runners/linux/requirements).

## Prerequisites

* Admin access to your Gitpod organization
* Root/sudo access on your Linux machine
* A machine meeting all [system requirements](/flex/runners/linux/requirements)

## Installation Steps

### 1. Create Linux Runner in Gitpod

First, create a runner in your Gitpod organization:

1. Go to [Settings -> Runners](https://app.gitpod.io/settings/runners) in your Gitpod organization
2. Click **Set up a new runner**, and select **Linux**
3. Choose a name for your runner and click **Create**
4. Keep this page open - it will guide you through the remaining setup steps and automatically transition to repository access configuration once the runner is running

### 2. Install Gitpod CLI

On your Linux machine, install the Gitpod CLI:

```bash
wget -O gitpod "https://releases.gitpod.io/cli/stable/gitpod-linux-amd64"
chmod +x gitpod
sudo mv gitpod /usr/local/bin
```

### 3. Set up Runner

Run the setup command shown in the Gitpod UI in step 1:

```bash
gitpod runner setup --exchange-token <token>
```

The setup will:

* Validate system requirements
* Configure networking
* Set required permissions
* Download necessary components

If any requirements are not met, the setup will provide specific instructions for resolving the issues. Re-run the setup command after resolving any issues until it completes successfully.

### 4. Configure Permissions

During setup, the runner will check if it can set the required network capabilities. If it cannot, you'll be prompted to add specific rules to your sudoers configuration.

Follow the instructions provided by the setup command, which will typically include:

1. Copy the suggested sudoers rules, these should look like this (replacing `YOUR_USERNAME` with your user):
   ```
   YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/gitpod-runner
   YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/cloud-hypervisor
   ```
2. Open the sudoers file with:
   ```bash
   sudo visudo -f /etc/sudoers.d/gitpod-runner
   ```
3. Add the provided rules and save the file

These permissions allow the runner to:

* Set required network capabilities on its binaries without requiring full sudo access
* Automatically update itself without manual intervention
* Maintain proper isolation between environments

This approach is more secure than granting full sudo access because it:

* Limits elevated permissions to only the specific setcap command
* Restricts which binaries can receive capabilities
* Specifies exactly which capabilities can be granted
* Eliminates the need for password prompts during updates

### 5. Start Runner

```bash
gitpod runner run
```

Keep this command running to maintain the runner's operation. The runner will check for new environments to start and manage
existing ones.

## Optional: Systemd Service Setup

To run the runner as a system service, create a systemd service file:

1. Create the service file:

```bash
sudo nano /etc/systemd/system/gitpod-runner.service
```

2. Add this configuration:

> Make sure to replace `YOUR_USER_HERE` with your actual system username (`whoami`).

```
[Unit]
Description=Gitpod Runner Service
After=network.target

[Service]
Type=simple
User=YOUR_USER_HERE
ExecStart=/usr/local/bin/gitpod runner run
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

3. Start and enable the service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable gitpod-runner
sudo systemctl start gitpod-runner
```

4. Check the service status:

```bash
sudo systemctl status gitpod-runner
```

5. Check the service logs:

```bash
journalctl -u gitpod-runner
```

## Repository Access

Before the runner can be used to launch environments, configure repository access by following our [repository access guide](/flex/runners/aws/setup-aws-runners#configuring-repository-access).

## Environment Classes

Configure environment classes to define the resources allocated to each environment. See our [environment classes guide](/flex/runners/aws/environment-classes).

The Linux runner creates a default set of environment classes based on the resources available on the host machine.

## Next Steps

* [Share runner with your team](/flex/runners/linux/maintenance#sharing)
* [Review maintenance guide](/flex/runners/linux/maintenance) for updates and maintenance
* [Review troubleshooting guide](/flex/runners/linux/troubleshooting) if you encounter issues

## Monitoring

Monitor your runner through:

* Gitpod UI (Settings -> Runners)
* System logs:
  ```bash
  # For systemd service
  journalctl -u gitpod-runner -f
  ```

## Common Setup Issues

If the setup fails, check:

1. System meets all [requirements](/flex/runners/linux/requirements)
2. Network/firewall configuration
3. Virtualization support is enabled in BIOS
4. Sufficient disk space and memory
5. Sudoers configuration is set correctly for automatic capability setting

For more help, see our [troubleshooting guide](/flex/runners/linux/troubleshooting).


# Troubleshooting Linux Runners
Source: https://www.gitpod.io/docs/gitpod/runners/linux/troubleshooting



## Common Symptoms

### Environment Stuck in Startup Phase

If your environment is stuck in the startup phase:

1. Check network forwarding configuration:

   ```bash
   # If using UFW (Uncomplicated Firewall)
   grep FORWARD /etc/default/ufw
   sudo ufw status

   # If not using UFW, check iptables
   sudo iptables -L FORWARD
   ```

2. If you see `Chain FORWARD (policy DROP)` in `iptables` or UFW's forward policy is not set to ACCEPT:

   ```bash
   # For UFW
   sudo nano /etc/default/ufw
   # Set DEFAULT_FORWARD_POLICY="ACCEPT"
   sudo ufw reload

   # For iptables
   sudo iptables -P FORWARD ACCEPT
   ```

3. Verify internet connectivity on the host machine

### Runner Shows as Disconnected

If the runner appears disconnected in the UI:

1. Check runner service status:

   ```bash
   # If running as a service
   sudo systemctl status gitpod-runner
   ```

2. View logs for errors:

   ```bash
   journalctl -u gitpod-runner
   ```

3. Verify:
   * Internet connectivity
   * System resources
   * Service configuration

### Setup Validation Fails

#### CPU Virtualization Not Enabled

```bash
❌ System requirements validation failed:
• CPU virtualization not enabled
```

1. Verify CPU virtualization support:
   ```bash
   grep -E 'svm|vmx' /proc/cpuinfo
   ```
2. Enable virtualization in BIOS if supported
3. Note: Most cloud VMs don't support nested virtualization by default

#### UFW Forwarding Policy Error

```bash
❌ System requirements validation failed:
• UFW forwarding policy needs to be configured
```

Follow the steps in [Environment Stuck in Startup Phase](#environment-stuck-in-startup-phase)

### Permission Issues

If you see capability or permission errors:

```bash
Error: failed to set capabilities on runner binary
```

This usually indicates an issue with the sudoers configuration. Check:

1. Verify your sudoers configuration:

   ```bash
   sudo cat /etc/sudoers.d/gitpod-runner
   ```

2. Ensure it contains the correct rules for your user and runner path:

   ```
   YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/gitpod-runner
   YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/cloud-hypervisor
   ```

3. If the file doesn't exist or has incorrect permissions, recreate it:

   ```bash
   sudo visudo -f /etc/sudoers.d/gitpod-runner
   ```

4. Add the rules provided during the setup process, replacing `YOUR_USERNAME` in paths and username with your actual values

### Resource Constraints

If environments fail to start or perform poorly:

1. Check system resources:

   ```bash
   free -h
   df -h
   ```

   > Runner data is stored in `~/gitpod-runner`

2. Solutions:
   * Stop unused environments
   * Increase system resources
   * Reduce concurrent environment count

### Environment Limit Reached

If you hit the 10 environment limit:

1. Check current environments in UI
2. Delete unused environments
3. Note: Deleted environments don't count towards limit

### Network Access Issues

If environments can't access the network:

1. Check forwarding configuration (see [Environment Stuck in Startup Phase](#environment-stuck-in-startup-phase))
2. Verify host machine network connectivity
3. Check network interface configuration:
   ```bash
   ip link show
   ```

### Repository Access Issues

If the runner can't access repositories:

1. Verify repository provider configuration in UI
2. Check authentication status
3. Try re-authenticating with repository provider

## Viewing Logs

For systemd service:

```bash
# View all logs
journalctl -u gitpod-runner

# Follow logs in real-time
journalctl -u gitpod-runner -f

# View recent logs
journalctl -u gitpod-runner -n 100
```

For terminal mode, logs are printed to stdout.

## Getting Help

If you can't resolve an issue:

1. Collect information:

   * Runner logs (from `journalctl` or terminal, also in `~/gitpod-runner/state/${RUNNER_ID}/log/`)
   * Runner version (visible in UI)
   * System information
   * Error messages
   * Environment logs (in `~/gitpod-runner/state/${RUNNER_ID}/environments/${ENV_ID}/logs/*.log`)

2. Contact Gitpod support through:
   * Support chat (bottom right in UI)
   * Include collected information in your report

## Prevention

To prevent common issues:

1. Regular maintenance:

   * Keep runner updated
   * Monitor resource usage
   * Clean up unused environments

2. Monitor logs for warnings:

   ```bash
   journalctl -u gitpod-runner
   ```

3. Keep sufficient free resources:
   * Disk space
   * Memory
   * CPU capacity


# Overview
Source: https://www.gitpod.io/docs/gitpod/runners/overview



Runners are single-tenant, self-hosted, flexible orchestrators of remote development environments. They are self-hosted in order to compartmentalize any sensitive information related to your development environments. Runners are responsible for operational tasks like

* Scaling
* Backup
* Caching

To reduce operational overhead, runners offload all non-sensitive administration responsibilities to the management plane.

Gitpod offers two types of self-hosted runners:

1. **AWS Runner**: Deploy on AWS using a CloudFormation template, ideal for production use and larger teams. It provides:

   * Horizontal scaling capabilities
   * Full AWS infrastructure integration
   * Dev container image build caching for faster environment startup
   * Pay-per-use cost model
   * Deployment in any region or availability zone, in any AWS Account
   * Runners can be deployed into multiple different AWS Accounts

2. **Linux Runner**: Run directly on your Linux machine, perfect for evaluation and small teams. It offers:
   * Simple local setup
   * Fixed infrastructure costs
   * Direct local network access
   * Support for up to 10 concurrent environments

Organizations can have as many runners as needed, deploying them in different locations to support remote teams in different timezones, adhere to data sovereignty, and other compliance requirements.

To create or modify runners, you must have an admin role inside the Gitpod organization.

Once deployed, you don’t need to interact with the infrastructure directly. Through Gitpod Desktop you can configure:

* which repositories a runner can access
* what environment classes are supported
* share it with your organization to allow any member to use it when creating environments


# Requirements
Source: https://www.gitpod.io/docs/gitpod/runners/requirements



# Gitpod Requirements

This page outlines the essential requirements for using Gitpod, with special attention to network configurations that ensure optimal performance.

Here's what you need to get started with Gitpod, including important network settings for the best experience.

## Network Requirements

When accessing Gitpod (`app.gitpod.io`) using a browser, certain network configurations are essential, particularly in enterprise environments:

* **HTTP/2 Support**: The Gitpod Dashboard requires HTTP/2 protocol support throughout your network infrastructure.
  * **Important**: If your corporate network includes proxy servers that don't support HTTP/2 traffic, the Gitpod Dashboard will not function correctly.
  * Ensure all proxy servers in your network path are configured to pass through HTTP/2 traffic without downgrading it.


# Azure DevOps
Source: https://www.gitpod.io/docs/gitpod/source-control/azuredevops



Source control integrations can be configured for [Self-Hosted Runners](/flex/runners). You can set up a Azure DevOps integration during runner creation or in the runner settings. Self-hosted Azure DevOps instances are supported by changing the Host during setup.

## Configuring Azure DevOps Access

<Note>
  {' '}

  You can skip this step if someone has already set up the runner for you and SCM
  integration with Azure DevOps has already been configured. In that case, you
  can go directly to [Authorizing Azure DevOps Access](#authorizing-azure-devops-access).
  This step allows administrators to configure what authorization methods (OAuth,
  PATs) and SCM providers (GitHub, Azure DevOps, Bitbucket, Azure DevOps) will
  be available for authorization.
</Note>

### Self-Hosted Runners

For self-hosted runners (like AWS), Azure DevOps integration is configured during runner creation or in the runner settings.

There are two ways to integrate with Azure DevOps. Both can be used simultaneously:

1. **OAuth App (Recommended):** Using a Microsoft Entra ID OAuth app allows users to sign in more quickly. You'll need to set up an OAuth app within Microsoft Entra ID.
2. **Personal Access Token (PAT):** Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

#### Using OAuth

<Note>
  Microsoft Entra ID is required for OAuth-based authentication with Azure DevOps repositories.
  This integration uses Microsoft Entra OAuth apps to provide authentication
  for Azure DevOps repositories. For more details, see the
  [Microsoft Entra OAuth documentation](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/entra-oauth?view=azure-devops).
</Note>

1. Go to **Settings > Runners** and select the runner for which you want to configure OAuth.

2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>

3. Select **Azure DevOps (Entra ID)** from the list of providers.

4. In the "Configure repository access" modal, select "Enable OAuth".

   * Copy the callback URL and use it to create a new OAuth app in Microsoft Entra ID.
   * The *Client ID* and *Client Secret* will be created in the following steps.
   * The *Issuer URL* is specific to your Entra ID tenant:
     * for example: `https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0`

   <Frame caption="Enable Azure DevOps OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure_entra_oauth.png" />
   </Frame>

5. Create a Microsoft Entra ID OAuth app by following these steps:

   **Create OAuth App Registration in Microsoft Entra ID:**

   * Go to the [Azure Portal](https://portal.azure.com) and navigate to Microsoft Entra ID
   * Select **App registrations** and click **New registration**
   * Provide a name for your application (e.g., "Gitpod Azure DevOps Integration")
   * Copy the *Client ID* from the **Overview** page and enter it in Gitpod's "Configure repository access" dialog
   * Obtain the *Issuer URL* to be entered in Gitpod's "Configure repository access" dialog from **Overview > Endpoints**
     * Use the v2.0 URL, e.g. `https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/oauth2/v2.0`

   **Configure Authentication Settings:**

   * In your app registration, go to **Manage > Authentication**
   * Ensure **Web** platform is selected
   * Enable **ID tokens** under the *Implicit grant and hybrid flows* section

   <Frame caption="Configure authentication settings">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/entra_authentication.png" />
   </Frame>

   **Create Client Secret:**

   * Navigate to **Manage > Certificates & secrets**
   * Click **New client secret**
   * Add a description and set expiration as needed
   * Copy the **Value** and use it to enter the Client Secret in Gitpod's "Configure repository access" dialog

   <Frame caption="Create client secret">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/entra_secrets.png" />
   </Frame>

   **Configure API Permissions:**

   * Go to **Manage > API permissions**
   * Click **Add a permission** and configure the following scopes:

   **For Microsoft Graph (Authentication):**

   * `openid` - Required for OpenID Connect authentication
   * `offline_access` - Needed for refresh tokens

   **For Azure DevOps API:**

   * `vso.code` - For read operations (repositories, commits, pull requests, refs, branches)
   * `vso.code_write` - Required for commit and push operations

   <Frame caption="Configure API permissions">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/entra_api_permissions.png" />
   </Frame>

   **Prepare Azure DevOps for Entra ID Integration:**

   * In Azure DevOps, go to **Organization Settings > Security > Policies**
   * Enable "Third-party application access via OAuth"

   <Frame caption="Enable third-party OAuth access in Azure DevOps">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure_policies.png" />
   </Frame>

   * Navigate to **Organization Settings > General**
   * Connect your Microsoft Entra ID tenant

   <Frame caption="Connect Microsoft Entra ID in Azure DevOps">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure_entra.png" />
   </Frame>

6. Once you've created the OAuth app in Entra ID, provide the **Issuer URL**, **Client ID**, and **Client Secret** in the Gitpod.
   The client secret will be encrypted using the runner's public key and stored securely, ensuring that only the designated runner can decrypt and access the sensitive credentials.

7. Save your changes.
   This will also try to connect with Entra ID to verify the OAuth app.

#### Using Personal Access Tokens (PATs)

1. Go to **Settings > Runners** and select the runner for which you want to configure the PAT.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **Azure DevOps** from the list of providers.
4. In the modal that opens, toggle "Enable Personal Access Token".
   <Frame caption="Enable Azure DevOps PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure-enable-pat.png" />
   </Frame>
5. Save your changes

## Authorizing Azure DevOps Access

### Using OAuth (Microsoft Entra ID)

1. When creating your first environment, you will be asked to authorize the new application. To use OAuth press the *Connect* button.

   <Frame caption="Connect Azure DevOps OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure-connect-oauth.png" />
   </Frame>

   A new window will open that directs you to Microsoft Entra ID to authorize the OAuth app. The requested scopes are grouped as follows:

   **Microsoft Graph (Authentication):**

   * `openid` - Required for OpenID Connect authentication
   * `offline_access` - Needed for refresh tokens

   **Azure DevOps API:**

   * `vso.code` - Required for read operations (parsing context URLs, cloning repositories, accessing commits, pull requests, refs, and branches)
   * `vso.code_write` - Required for write operations (committing and pushing changes from your environment to the repository)

2. After you have authorized Gitpod, you can close the window. After a few seconds the you should get a confirmation that Azure DevOps (Entra ID) is now connected.
   <Frame caption="Connect Azure DevOps OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure-connected.png" />
   </Frame>

### Using Personal Access Tokens (PATs)

1. When creating your first environment, you will be asked to authorize the new application. Select *Provide a Personal Access Token*.

   <Frame caption="Connect Azure DevOps PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure-connect-pat.png" />
   </Frame>

   * Follow the instructions of the Azure documentation to create a PAT
   * The name of the token and all required scopes are pre-set.
   * By default, the token is valid for 30 days, but you can change the duration if needed.

2. After creating the token, return to the dialog and paste the token.
   <Frame caption="Set Azure DevOps PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/azure-set-pat.png" />
   </Frame>

3. The environment will now be created using the provided token.


# Bitbucket Cloud
Source: https://www.gitpod.io/docs/gitpod/source-control/bitbucket



Source control integrations can be configured for both [Self-Hosted Runners](/flex/runners) and [Gitpod Desktop](/flex/gitpod-desktop). You can set up a Bitbucket integration during runner creation or in the runner settings. Self-hosted Bitbucket instances are currently not supported.

## Configuring Bitbucket Access

<Note>
  {' '}

  You can skip this step if someone has already set up the runner for you and SCM
  integration with Bitbucket has already been configured. In that case, you can
  go directly to [Authorizing Bitbucket Access](#authorizing-bitbucket-access).
  This step allows administrators to configure what authorization methods (OAuth,
  PATs) and SCM providers (GitHub, GitLab, Bitbucket, Azure DevOps) will be available
  for authorization.
</Note>

### Self-Hosted Runners

For self-hosted runners (like AWS), Bitbucket integration is configured during runner creation or in the runner settings.

We are currently supporting OAuth for authorizing Bitbucket access. Support for Personal Access Tokens (PATs) is planned.

#### Using OAuth

1. Go to **Settings > Runners** and select the runner for which you want to configure OAuth.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **Bitbucket** from the list of providers.
4. In the modal that opens, toggle "Enable OAuth".
   <Frame caption="Enable Bitbucket OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/bitbucket-enable-oauth.png" />
   </Frame>
5. Follow the instructions in [Bitbucket's docs](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) to create an OAuth app.
   * The app name can be any name you like
   * You can get the callback URL from the SCM configuration dialog
   * Select the required scopes
     * The *account* scope is required so that the git author name and git author email can be set in the environment
     * The *repository* scope is required so that the repository can be cloned and the context url can be parsed
     * The *repository:write* scope is required so that changes can be pushed to the repository from the environment
     * The *pullrequests* scope is required so that an environment can be started from a pull request
       <Frame caption="Configure Bitbucket OAuth">
         <img src="https://www.gitpod.io/images/docs/flex/source-control/bitbucket-configure-oauth.png" />
       </Frame>
6. After creating the OAuth app, provide the **Client ID** and **Client Secret** in the runner configuration dialog. Bitbucket calls these *Key* and *Secret*. The client secret will be encrypted with the runner's public key, ensuring only the runner can read it.
7. Save your changes

## Authorizing Bitbucket Access

### Using OAuth

1. When creating your first environment, you will be asked to authorize the new application. To use OAuth press the *Connect* button.

   <Frame caption="Connect Bitbucket OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/bitbucket-connect-oauth.png" />
   </Frame>

   A new window will open that directs you to Bitbucket to authorize the OAuth app. The requested scopes are *account*, *repository*, *repository:write*, *pullrequests* and *issue*.

   * The *account* scope is required so that the git author name and git author email can be set in the environment
   * The *repository* scope is required so that the repository can be cloned and the context url can be parsed
   * The *repository:write* scope is required so that changes can be pushed to the repository from the environment
   * The *pullrequests* scope is required so that an environment can be started from a pull request

   <Frame caption="Authorize Bitbucket OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/bitbucket-authorize-app.png" />
   </Frame>

2. After you have authorized Gitpod, you can close the window. After a few seconds the you should get a confirmation that Bitbucket is now connected.
   <Frame caption="Connect Bitbucket OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/bitbucket-connected.png" />
   </Frame>


# GitHub
Source: https://www.gitpod.io/docs/gitpod/source-control/github



Source control integrations can be configured for both [Self-Hosted Runners](/flex/runners) and [Gitpod Desktop](/flex/gitpod-desktop). You can set up a GitHub integration during runner creation or in the runner settings. Self-hosted GitHub instances are supported by changing the Host during setup.

## Configuring GitHub Access

<Note>
  {' '}

  You can skip this step if someone has already set up the runner for you and SCM
  integration with GitHub has already been configured. In that case, you can go
  directly to [Authorizing GitHub Access](#authorizing-github-access). This step
  allows administrators to configure what authorization methods (OAuth, PATs) and
  SCM providers (GitHub, GitLab, Bitbucket, Azure DevOps) will be available for
  authorization.
</Note>

### Self-Hosted Runners

For self-hosted runners (like AWS), GitHub integration is configured during runner creation or in the runner settings.

There are two ways to integrate with GitHub. Both can be used simultaneously:

1. **OAuth App (Recommended):** Using an OAuth app allows users to sign in more quickly. You'll need to set up an OAuth app within Gitpod.
2. **Personal Access Token (PAT):** Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

#### Using OAuth

1. Go to **Settings > Runners** and select the runner for which you want to configure OAuth.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **GitHub** from the list of providers.
4. In the modal that opens, toggle "Enable OAuth".
   <Frame caption="Enable GitHub OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/github-enable-oauth.png" />
   </Frame>
5. Follow the instructions in [GitHub's docs](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to create an OAuth app.
   * The app name can be any name you like
   * For the homepage URL, you can use [https://app.gitpod.io/](https://app.gitpod.io/)
   * You can get the callback URL from the SCM configuration dialog
6. After creating the OAuth app, provide the **Client ID** and **Client Secret** in the runner configuration dialog. The client secret will be encrypted with the runner's public key, ensuring only the runner can read it.
7. Save your changes

#### Using Personal Access Tokens (PATs)

1. Go to **Settings > Runners** and select the runner for which you want to configure the PAT.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **GitHub** from the list of providers.
4. In the modal that opens, toggle "Enable Personal Access Token".
   <Frame caption="Enable GitHub PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/github-enable-pat.png" />
   </Frame>
5. Save your changes

### Gitpod Desktop

For Gitpod Desktop, GitHub authentication is managed through organization settings:

1. Organization administrators configure GitHub access in Settings -> Runners -> Gitpod Desktop
2. `github.com` is configured by default
3. For self-hosted GitHub instances:
   * Administrators must add the custom host in the settings
   * Users cannot authenticate with these hosts until they are configured
4. Users authenticate using **Personal Access Tokens**:
   * Gitpod checks for existing Git credentials first on the user's machine (using the git credential manager)
   * If none exist, users are prompted to provide a PAT during environment creation
   * Tokens can be managed under Settings -> Git Authentications

<Frame caption="Desktop Settings">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/desktop_settings.png" />
</Frame>

## Authorizing GitHub Access

### Using OAuth

1. When creating your first environment, you will be asked to authorize the new application. A new window will open that directs you to GitHub to authorize the OAuth app.

* The requested scopes are *repo*, *read:user*, *user:email*, and *workflow*.
* The *repo* permission is required so that your environment can clone the repository.
* The *read:user* permission is required so that the git author name can be set in the environment.
* The *user:email* permission is required so that the git author email can be set in the environment.
* The *workflow* permission is required so that GitHub Action YAML files can be edited in the environment.

2. After you have authorized Gitpod, you can close the window and go back to the environment details screen.

### Using Personal Access Tokens (PATs)

1. The first time a user creates an environment, they will be asked to enter a Personal Access Token.

   * Click the link provided on the screen to access the configuration dialog for creating a GitHub token.
   * The name of the token and all required scopes are pre-set.
   * By default, the token is valid for 30 days, but you can change the duration if needed.
     <Frame caption="Set GitHub PAT">
       <img src="https://www.gitpod.io/images/docs/flex/source-control/github-set-pat.png" />
     </Frame>

2. After creating the token, return to the dialog and paste the token.

3. The environment will now be created using the provided token.


# GitLab
Source: https://www.gitpod.io/docs/gitpod/source-control/gitlab



Source control integrations can be configured for both [Self-Hosted Runners](/flex/runners) and [Gitpod Desktop](/flex/gitpod-desktop). You can set up a GitLab integration during runner creation or in the runner settings. Self-hosted GitLab instances are supported by changing the Host during setup.

## Configuring GitLab Access

<Note>
  {' '}

  You can skip this step if someone has already set up the runner for you and SCM
  integration with GitLab has already been configured. In that case, you can go
  directly to [Authorizing GitLab Access](#authorizing-GitLab-access). This step
  allows administrators to configure what authorization methods (OAuth, PATs) and
  SCM providers (GitHub, GitLab, Bitbucket, Azure DevOps) will be available for
  authorization.
</Note>

### Self-Hosted Runners

For self-hosted runners (like AWS), GitLab integration is configured during runner creation or in the runner settings.

There are two ways to integrate with GitLab. Both can be used simultaneously:

1. **OAuth App (Recommended):** Using an OAuth app allows users to sign in more quickly. You'll need to set up an OAuth app within Gitpod.
2. **Personal Access Token (PAT):** Each user will need to create a Personal Access Token. They will be provided with a deep link to do so on their first environment creation.

#### Using OAuth

1. Go to **Settings > Runners** and select the runner for which you want to configure OAuth.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **GitLab** from the list of providers.
4. In the modal that opens, toggle "Enable OAuth".
   <Frame caption="Enable GitLab OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-enable-oauth.png" />
   </Frame>
5. Follow the instructions in [GitLab's docs](https://docs.gitlab.com/ee/integration/oauth_provider.html) to create an OAuth app.
   * The app name can be any name you like
   * You can get the callback URL from the SCM configuration dialog
   * Select the required scopes
     * The *api scope* is required so that the context url can be parsed
     * The *read\_repository* scope is required so that your environment can clone the repository
     * The *read\_user scope* is required so that the git author name and git author email can be set in the environment
       <Frame caption="Configure GitLab OAuth">
         <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-configure-oauth.png" />
       </Frame>
6. After creating the OAuth app, provide the **Client ID** and **Client Secret** in the runner configuration dialog. The client secret will be encrypted with the runner's public key, ensuring only the runner can read it.
7. Save your changes

#### Using Personal Access Tokens (PATs)

1. Go to **Settings > Runners** and select the runner for which you want to configure the PAT.
2. Navigate to the "Configure repository access" section and click "Add a new provider".
   <Frame caption="Add new provider">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/scm-providers.png" />
   </Frame>
3. Select **GitLab** from the list of providers.
4. In the modal that opens, toggle "Enable Personal Access Token".
   <Frame caption="Enable GitLab PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-enable-pat.png" />
   </Frame>
5. Save your changes

### Gitpod Desktop

For Gitpod Desktop, GitLab authentication is managed through organization settings:

1. Organization administrators configure GitLab access in Settings -> Runners -> Gitpod Desktop
2. `gitlab.com` is configured by default
3. For self-hosted GitLab instances:
   * Administrators must add the custom host in the settings
   * Users cannot authenticate with these hosts until they are configured
4. Users authenticate using **Personal Access Tokens**:
   * Gitpod checks for existing Git credentials first on the user's machine (using the git credential manager)
   * If none exist, users are prompted to provide a PAT during environment creation
   * Tokens can be managed under Settings -> Git Authentications

<Frame caption="Desktop Settings">
  <img src="https://www.gitpod.io/images/docs/flex/desktop/desktop_settings.png" />
</Frame>

## Authorizing GitLab Access

### Using OAuth

1. When creating your first environment, you will be asked to authorize the new application. To use OAuth press the *Connect* button.

   <Frame caption="Connect GitLab OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-connect-oauth.png" />
   </Frame>

   A new window will open that directs you to GitLab to authorize the OAuth app. The requested scopes are *api*, *read\_repository* and *read\_user*.

   * The *api* scope is required so that the context url can be parsed
   * The *read\_repository* scope is required so that your environment can clone the repository
   * The *read\_user scope* is required so that the git author name and git author email can be set in the environment
     <Frame caption="Authorize GitLab OAuth">
       <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-authorize-app.png" />
     </Frame>

2. After you have authorized Gitpod, you can close the window. After a few seconds the you should get a confirmation that GitLab is now connected.
   <Frame caption="Connect GitLab OAuth">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-connected.png" />
   </Frame>

### Using Personal Access Tokens (PATs)

1. When creating your first environment, you will be asked to authorize the new application. Select *Provide a Personal Access Token*.

   <Frame caption="Connect GitLab PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-connect-pat.png" />
   </Frame>

   * Click the link provided on the screen to access the configuration dialog for creating a GitLab token.
   * The name of the token and all required scopes are pre-set.
   * By default, the token is valid for 30 days, but you can change the duration if needed.

2. After creating the token, return to the dialog and paste the token.
   <Frame caption="Set GitLab PAT">
     <img src="https://www.gitpod.io/images/docs/flex/source-control/gitlab-set-pat.png" />
   </Frame>

3. The environment will now be created using the provided token.


# Overview
Source: https://www.gitpod.io/docs/gitpod/source-control/overview



Gitpod seamlessly integrates with major source control providers, enabling you to work with your code repositories directly within your Gitpod environments.

## Key Features

* **Automated Repository Cloning**: Your repositories are automatically cloned when you start a Gitpod environment
* **Full Branch Management**: Create, switch, and manage branches directly within your environment
* **Commit and Push**: Make changes and push them back to your repository without leaving Gitpod

## Supported Providers

Gitpod integrates with the following source control providers:

* [GitHub](/flex/source-control/github)
* [GitLab](/flex/source-control/gitlab)
* [Bitbucket Cloud](/flex/source-control/bitbucket)
* [Azure DevOps](/flex/source-control/azuredevops)

## Authentication

You can authenticate with your source control provider using:

* **OAuth**: For a streamlined authentication experience
* **Personal Access Tokens (PAT)**: For more granular control over permissions

## Security Architecture

Gitpod follows a secure architecture for source control integration:

* All source control interactions occur **only through the runner** on your infrastructure
* Gitpod's management plane **never has access** to your credentials or source code
* Your code and credentials remain exclusively within your control

Visit the provider-specific pages for detailed setup instructions and best practices.


# Amazon Cognito
Source: https://www.gitpod.io/docs/gitpod/sso/cognito



You can set up Single Sign-on (SSO) with Amazon Cognito for your team.

This section helps you to create an OIDC application with Amazon Cognito. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to set up a new [Amazon Cognito application](https://console.aws.amazon.com/cognito/home) in your AWS account.

## Create an OIDC application

1. Nagivate to [Amazon Cognito](https://console.aws.amazon.com/cognito/home) service page, then select `Set up your application`.

2. Configure the application by filling out the form:

   * **Application type**: `Traditional web application`

   * **Name**: `Gitpod`

   * **Options for sign-in identifiers**:

     * `Email`

   * **Required attributes for sign-up**:

     * `email`

     * `name`

   * **Return URL**: `https://app.gitpod.io/auth/oidc/callback`

   Click the *Create* button

   <Frame caption="Amazon Cognito - New Application">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/cognito-application.png" />
   </Frame>

3. Obtain *Client ID*, *Client Secret* from the Overview page<br /><br />

   Upon creation of the application, you will be redirected to then also created user pool. Learn more on user pools in Amazon Cognito [here](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html?icmpid=docs_cognito_console_help_panel).

   * Feel free to rename the user pool before proceeding!

   * Obtain **Issuer URL**

     * You'll find the **User pool ID** here

     * The pattern for the *Issuer URL* is:<br />
       `https://cognito-idp.<awsregion>.amazonaws.com/<user-pool-id>`

     * Verify to use the correct URL by opening the OIDC Discovery location `<Issuer URL>/.well-known/openid-configuration` in your browser, i.e. open `https://cognito-idp.<awsregion>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration`.

   * Then navigate to *Applications > App clients > Gitpod* to find the details of the newly create application, and copy the information you'll need in Gitpod:

     * **Client ID**

     * **Client secret**

   <Frame caption="Amazon Cognito - Overview">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/cognito-overview.png" />
   </Frame>

4. Configure OIDC Scopes<br /><br />

   The default selection of OIDC scopes in Amazon Cognito doesn't meet the requirements for Gitpod. Please navigate to *App client > Login pages > Edit* to make the necessary changes.

   <Frame caption="Amazon Cognito - Edit Scopes">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/cognito-edit-scopes.png" />
   </Frame>

   * Ensure the `Profile` scope is selected here:

   <Frame caption="Amazon Cognito - Scopes">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/cognito-scopes.png" />
   </Frame>

5. Adjust **Sign-up** settings to your needs

   * Disable **Self-registration** if you want to limit access to your application.

   * With the Sign-up disabled , you may need to manage users under *User management* manually.

   <Frame caption="Amazon Cognito - Sign-up">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/cognito-signup.png" />
   </Frame>

6. Continue with the SSO configuration in Gitpod: [Clicking *Save & Test*](/flex/sso#3-save-and-test-the-configuration)


# Microsoft Entra ID
Source: https://www.gitpod.io/docs/gitpod/sso/entra



You can set up Single Sign-on (SSO) with Microsoft Entra ID for your team.

This section helps you to create an OIDC application with Microsoft Entra ID. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to [Microsoft Entra admin center](https://entra.microsoft.com/)

## Create an OIDC application

1. On the [Microsoft Entra admin center](https://entra.microsoft.com/), navigate to *Identity > Applications*

2. Select `New Registration`

   <Frame caption="New Registration">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-1-new-app.png" />
   </Frame>

3. Specify General Settings

   * App name, e.g. `Gitpod`

   * Platform: `Web`

   * Redirect URI: `https://app.gitpod.io/auth/oidc/callback`

   * <Frame caption="Register Application">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-2-register-app.png" />
     </Frame>

4. Obtain *Client Secret* from the *Certificates & secrets* page

   * Once the application is registered, navigate to the subpage *Certificates & secrets* to create and obtain a new client secret.

     * Click the *New client secret* button
       <Frame caption="New client secret">
         <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-3-client-secret.png" />
       </Frame>

     * Adjust the expiry of the client secret
       <Frame caption="Client secret expiry">
         <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-4-client-secret-expires.png" />
       </Frame>

     * Then copy the value of the client secret to be pasted in Gitpod's SSO setup
       <Frame caption="Client secret expiry">
         <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-5-client-secret-copy.png" />
       </Frame>

5. Configure OIDC Scopes

   * The default selection of OIDC scopes in Microsoft Entra ID doesn't meet the requirements for Gitpod. Please navigate to *API permissions > Add a permission* to make the necessary changes.

     <Frame caption="Add a permission">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-7-permissions-openid.png" />
     </Frame>

     * Select *Delegated permissions* and *OpenId*, then ensure to enable the following scopes:

       * `email`

       * `openid`

       * `profile`

       * <Frame caption="OpenID Scopes">
           <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-6-permissions.png" />
         </Frame>

   * Although the `email` claim is part of the standard OIDC specification, depending on the setup, Microsoft Entra ID does not include it by default in ID tokens. Under *Manage*, select *Token configuration* and fix this:

     * Click *Add optional claim*

     * Add the `email` scope

     * <Frame caption="Add email scope">
         <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-10-id-email-claim.png" />
       </Frame>

6. Obtain *Issuer URL* from *Endpoints* tab

   * Navigate to the *Overview* page and select *Endpoints*

     <Frame caption="Endpoints tag">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-8-endpoints-tab.png" />
     </Frame>

   * Copy the *Authority URL* to be used as *Issuer URL* in Gitpod's SSO setup

     <Frame caption="Endpoints tag">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-8-endpoints-tab-issuer.png" />
     </Frame>

     > **Note**: Validate the **Issuer URL** by checking the [OIDC Discovery](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri) location. In some configurations, the **Issuer URL** needs to be adjusted.

     * If the *Authority URL* reads like `https://login.microsoftonline.com/{tenant}/v2.0`, the OIDC Discovery location is `https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration`. Open this URL in your browser and check the `issuer` field.

     * Check the `issuer` field in the OIDC Discovery output and ensure this matches the *Authority URL* (*Issuer URL*).
       If not, e.g. if it reads like `https://sts.windows.net/{tenant}`, please try again with`{authority_url}/v2.0/.well-known/openid-configuration` and use `{authority_url}/v2.0` as **Issuer URL** in Gitpod's SSO setup.

7. Obtain the *Client ID* from the *Overview* page

   * Navigate to the *Overview* page and copy the *Application (client) ID* value to be used as *Client ID* in Gitpod's SSO setup

     <Frame caption="Client ID">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/entra-9-client-id.png" />
     </Frame>

8. Continue with the SSO configuration in Gitpod: [Clicking *Save & Test*](/flex/sso#3-save-and-test-the-configuration)


# GitLab
Source: https://www.gitpod.io/docs/gitpod/sso/gitlab



You can set up Single Sign-on (SSO) with Gitlab SaaS or a self-hosted Gitlab for your team.

This section helps you to create an OIDC application with Gitlab. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* If you are setting up SSO with a self-hosted GitLab, make sure you have Admin permissions on that Gitlab installation, or work together with the administrator.
* If you are setting up SSO with GitLab SaaS (gitlab.com), it is advised to create the OIDC application in a group, so please make sure you have Group Admin permissions on that group.

## Create an OIDC application

The OIDC application allows you to integrate with Gitpod.

1. Navigate to *Groups > My Awesome Group > Settings > Applications* (for SaaS) or *Admin Area > Application* (for self-hosted).

2. Click the *Add new application* button.
   <Frame caption="Gitlab - Add new application">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/gitlab-group-applications.png" />
   </Frame>

3. Configure the OIDC application by filling out the form:

   * **Name**: Gitpod
   * **Redirect URI**: `https://app.gitpod.io/auth/oidc/callback`
   * **Confidential**: `Yes`
   * **Scopes**:

     * `read_user`
     * `openid`
     * `profile`
     * `email`

     Then click the `Save Application` button.

     <Frame caption="Gitlab - Appplication scopes">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/gitlab-scopes.png" />
     </Frame>

4. Obtain the *Client ID* & *Client Secret* from the following confirmation screen, which you'll need for the Gitpod SSO configuration in the following step. This is how to interpret the information:

   * **Application ID**: *Client ID*
   * **Secret**: *Client Secret*

   <Frame caption="Gitlab - Appplication secret">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/gitlab-copy-secret.png" />
   </Frame>

5. Which *Issuer URL* to use?

   * For self-hosted Gitlab: `https://your-gitlab-installation.org`

   * For Gitlab Saas: `https://gitlab.com`

6. Continue with the SSO configuration in Gitpod: [Clicking *Save & Test*](/flex/sso#3-save-and-test-the-configuration)


# Google
Source: https://www.gitpod.io/docs/gitpod/sso/google



You can set up Single Sign-on (SSO) with Google for your team.

This section helps you to create an OIDC application with Google. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to setup a new [API Credentials](https://console.cloud.google.com/apis/credentials) in your GCP Account

## Create an OAuth/OIDC application

The OAuth/OIDC application allows you to integrate with Gitpod.

1. Navigate to your *Google Cloud Console > API Credentials*

2. Select *Create Credentials*, and choose *OAuth Client ID*

   <Frame caption="Create credentials - Google Cloud Dashboard">
     <img src="https://www.gitpod.io/images/docs/gitpod-dedicated/guides/getting-started/sso/google/create-credentials.webp" />
   </Frame>

3. Configure your *OAuth Client ID* by specifying the *Authorized Redirect URI*: `https://app.gitpod.io/auth/oidc/callback`

4. Obtain the *Client ID* & *Client Secret* and input these into your Gitpod Setup page

   <Frame caption="OAuth Client Created - Google Cloud Dashboard">
     <img src="https://www.gitpod.io/images/docs/gitpod-dedicated/guides/getting-started/sso/google/OAuth-client-created.webp" />
   </Frame>

5. Use Google's global *Issuer URL*: `https://accounts.google.com`

6. Continue with the SSO configuration in Gitpod: [Clicking *Save & Test*](/flex/sso#3-save-and-test-the-configuration)


# Okta
Source: https://www.gitpod.io/docs/gitpod/sso/okta



You can set up Single Sign-on (SSO) with Okta for your team.

This section helps you to create an OIDC application with Okta. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to your Okta instance
* Permission to create an [app integration](https://help.okta.com/oie/en-us/Content/Topics/Apps/apps-overview-get-started.htm)

## Create an OIDC application

1. On the Okta Admin dashboard, navigate to Applications

2. Select `Create App Integration`

   <Frame caption="Applications - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/gitpod-dedicated/guides/getting-started/sso/okta/okta-dashboard.webp" />
   </Frame>

3. Select the following options and click *Next*

   * Sign-in method: `OIDC - Open ID Connect`
   * Application type: `Web Application`

   <Frame caption="Create App Integration - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/gitpod-dedicated/guides/getting-started/sso/okta/create-app-integration.webp" />
   </Frame>

4. Specify General Settings

   * App integration name, e.g. `Gitpod`
   * Sign-in redirect URIs: `https://app.gitpod.io/auth/oidc/callback`
   * Sign-out redirect URIs: `none`

   <Frame caption="Specify Okta settings - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/okta-general.png" />
   </Frame>

5. Assignments

   * You have to select Okta users or groups which would be allowed to use the integration with Gitpod.
   * Okta let's you [import and synchronize directories](https://help.okta.com/oie/en-us/content/topics/directory/directory-integrations-main.htm?cshid=csh-directory-integrations-main), which then can be assigned to use the integration.

   <Frame caption="Specify Assignments - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/okta-assignments.png" />
   </Frame>

6. Obtain *Client ID*, *Client Secret* from General tab

   <Frame caption="Configure Client Secrets - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/gitpod-dedicated/guides/getting-started/sso/okta/client-configs-okta.webp" />
   </Frame>

7. Obtain *Issuer URL*

   <Frame caption="Issuer - Okta Dashboard">
     <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/okta-copy-issuer-url.png" />
   </Frame>

8. Continue with the SSO configuration in Gitpod: [Clicking *Save & Test*](/flex/sso#3-save-and-test-the-configuration)


# Overview
Source: https://www.gitpod.io/docs/gitpod/sso/overview

Single Sign-on for your organization in Gitpod

This section helps you, as an Organization Admin, set up and manage Single Sign-On (SSO) for your team. You'll learn how to enable SSO, control access, and troubleshoot common issues to keep your team logging in smoothly and securely.

## Overview

Single Sign-On (SSO) lets your team log in to your organization using their existing session with an external Identity Provider (IdP), such as Okta or Azure AD, through OpenID Connect (OIDC). This simplifies user authentication, enhances security, and streamlines access management across your organization.

## Setup Single Sign-on for the organization

### Prerequisites

This is what you will need to have in order to enable SSO:

* Admin-level access to your organization settings.

* Domain/DNS admin privileges so you can add a DNS TXT record. This TXT record is used by Gitpod to verify ownership of the domain associated with your organization.

* Access to an Identity Provider (e.g. Google, Gitlab, Okta, Microsoft Entra ID) that supports OpenID Connect (OIDC).

  * You'll need to create an OIDC application with your Identity Provider and obtain the **Client ID**, **Client Secret**, and **Issuer URL**.

## Step-by-step guide to set up SSO

To begin setting up Single Sign-On, navigate to **Organization Settings** and choose *Log in and security* from the left-hand menu. Next, click on the *Setup* button.

<Frame caption="Log in and security">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/login-security.png" />
</Frame>

### Step 1. Configure SSO

Let's first configure how Gitpod will connect with your Identity Provider.

Enter your organization's **email domain**. This is important because your team members will use their email addresses from this domain when they [sign in](#log-in-with-single-sign-on).

Now, it's time to set up the connection with your Identity Provider. We've created detailed guides for the most popular providers to make this easier for you:

* **[Okta](/flex/sso/okta)**
* **[Google](/flex/sso/google)**
* **[GitLab](/flex/sso/gitlab)**
* **[Entra ID](/flex/sso/entra)**
* **[Amazon Cognito](/flex/sso/cognito)**
* **[PingFederate](/flex/sso/pingfederate)**

After following the guide for your provider, you'll need three important pieces of information to complete the form:

* **Client ID**: The identifier for your OIDC application.
* **Client Secret**: Secret key for authenticating with the IdP.
* **Issuer URL**: Endpoint of the OIDC server.

Copy the **Callback URL** from the bottom of this form, and paste it into the settings of the OIDC application with the IdP.

<Frame caption="Setup SSO">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/sso-configure-completed.png" />
</Frame>

#### Testing your configuration

Before rolling this out to your team, let's make sure everything is working properly:

Test the OIDC application by clicking **Test & Continue**

* The authentication flow with your Identity Provider should open in a new browser window.
* Please verify the authentication flow works for you before inviting your team to use the SSO login.

  <Frame caption="Test the OIDC application">
    <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/sso-configure-saved.png" />
  </Frame>

If everything looks good, click **Verify your domain** to continue to the next step.

### Step 2. Verify your domain

In the second step, you'll need to verify your organization's email domain. This is done by adding a **TXT record** to your domain's DNS settings. Copy the name and value for the TXT record from this view.

<Frame caption="Verify your domain">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/sso/sso-verify-your-domain.png" />
</Frame>

> Please note that your email domain must be verified before the [Sign in with SSO option](#log-in-with-single-sign-on) can be used on the Login screen.

#### Check the status of your domain

Click **Verify** to check the status of your domain verification and return to the overview page. A delay in DNS updates is expected, so no worries!

You'll find the verification status on the *Log in and security* page. Once you've added the TXT record for your email domain, simply click the refresh button to update the status.

<Frame caption="Check domain status">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/check-domain-status.png" />
</Frame>

### Problems and solutions

While setting up SSO, some issues may arise due to misconfigurations or external factors. These can include problems with your Identity Provider settings, incorrect credentials, or network issues. To help you navigate these challenges, we’ve included an FAQ section below with solutions to common problems.

1. Error: *The redirect URI included is not valid.*

   * Make sure to paste the correct redirect URI into the OIDC application with your Identity Provider, e.g. `https://app.gitpod.io/auth/oidc/callback`.

     <Frame caption="Invite URL error">
       <img src="https://www.gitpod.io/images/docs/flex/organizations/login-security-faq-redirect-uri.png" />
     </Frame>

2. Error: *no such host*

   * Make sure to paste the correct *Issuer URL*, e.g. `https://dev-16686455.okta.com`. You can also verify the URL by appending the OIDC Discovery path `/.well-known/openid-configuration` and open the resulting URL in you browser, e.g. `https://dev-16686455.okta.com/.well-known/openid-configuration`

## Log in with Single Sign-on

### Use your email address

Once you've finished setting up SSO for your organization, you'll need to log out before heading back to the Login page.

* Click the *Continue with SSO* button to sign in using your new SSO setup.

  <Frame caption="Login page">
    <img src="https://www.gitpod.io/images/docs/flex/organizations/login-with-sso.png" />
  </Frame>

* Now enter your email address and click *Continue*. The domain of your email address **must match** the domain of your SSO configuration.

  <Frame caption="Email address">
    <img src="https://www.gitpod.io/images/docs/flex/organizations/login-with-sso-email.png" />
  </Frame>

### Use the invite link

* Go to `Settings > Members > Invite members` and copy the invite link for your domain.

* When you open the invite link while not logged in, you will only see the active login providers.

  <Frame caption="Login on invite link">
    <img src="https://www.gitpod.io/images/docs/flex/organizations/login-invite-link.png" />
  </Frame>

## Managing Single Sign-on Access

Only *Organization Admins* are allowed to configure, modify, or disable SSO settings. Regular members will not have access to these options.

<Frame caption="SSO enabled">
  <img src="https://www.gitpod.io/images/docs/flex/organizations/login-security.png" />
</Frame>

#### Deactivating login providers

A deactivated login provider can not be used to join your organization. The existing login sessions are not affected by this setting.

If you need to deactivate a login provider:

* Go to *Settings > Log In and Security*.

* Click the toggle switch next to the login provider and confirm the action.

> To protect you from losing access to your organization, the one remaining login provider cannot be deactivated.


# PingFederate
Source: https://www.gitpod.io/docs/gitpod/sso/pingfederate



You can set up Single Sign-on (SSO) with PingFederate for your team.

This section helps you to create an OIDC application with PingFederate. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Gitpod. See the [Step-by-step guide](/flex/sso#step-by-step-guide-to-set-up-sso) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to your PingFederate instance
* Administrator permissions on PingFederate to create and configure OAuth clients
* Understanding of your organization's authentication flow requirements

## Create an OAuth Client

The OAuth client allows you to integrate with Gitpod using the OpenID Connect protocol.

Please refer to the [official PingFederate documentation](https://docs.pingidentity.com/pingfederate/12.2/administrators_reference_guide/pf_configuring_oauth_clients.html) for detailed configuration steps.

1. Log in to your PingFederate Administrative Console.

2. Navigate to **Applications > OAuth > Clients**.

3. Click **Add Client** to create a new OAuth client.

4. Configure the OAuth client with the following settings:

   * **Client ID**: Generate or specify a unique identifier (you'll need this for Gitpod)
   * **Client Authentication**: Select `Client Secret`
   * **Client Secret**: Generate a secure secret (you'll need this for Gitpod)
   * **Allowed Grant Types**: Select `Authorization Code`
   * **Redirect URIs**: `https://app.gitpod.io/auth/oidc/callback`
   * **Allowed Scopes**: Include at minimum:
     * `openid`
     * `profile`
     * `email`

5. **Configure Token Settings**:
   * Set appropriate token lifetimes based on your security policies
   * Ensure ID tokens include necessary claims (`sub`, `email`, `name`)

6. **Save the Configuration** and note down:
   * **Client ID**: The unique identifier you specified
   * **Client Secret**: The generated secret
   * **Issuer URL**: Your PingFederate base URL (e.g., `https://your-pingfederate.company.com`)

## Additional Configuration

Depending on your PingFederate setup, you may need to:

* Configure attribute mapping to ensure user information (email, name) is properly passed to Gitpod
* Set up any required authentication policies or adapters
* Configure session management settings
* Review and adjust any security policies that might affect the integration

## Troubleshooting

Common issues and solutions:

* **Invalid Redirect URI**: Ensure the redirect URI in PingFederate exactly matches `https://app.gitpod.io/auth/oidc/callback`
* **Missing Claims**: Verify that your PingFederate configuration includes the required OpenID Connect claims (`sub`, `email`, `profile`)
* **Authentication Failures**: Check PingFederate logs for detailed error information

For detailed configuration instructions and troubleshooting, refer to the [PingFederate OAuth Configuration Guide](https://docs.pingidentity.com/pingfederate/12.2/administrators_reference_guide/pf_troubleshooting.html).

## Continue with Gitpod Configuration

Once you have obtained the *Client ID*, *Client Secret*, and *Issuer URL* from your PingFederate configuration, continue with [Step 1. Configure SSO](/flex/sso#step-1-configure-sso) in Gitpod.