Workspaces

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Version history

• Feature flag remote_development_feature_flag enabled on GitLab.com and GitLab Self-Managed in GitLab 16.0.
• Generally available in GitLab 16.7. Feature flag remote_development_feature_flag removed.

A workspace is a virtual sandbox environment for your code in GitLab. You can use workspaces to create and manage isolated development environments for your GitLab projects. These environments ensure that different projects don't interfere with each other.

Each workspace includes its own set of dependencies, libraries, and tools, which you can customize to meet the specific needs of each project.

A workspace can exist for a maximum of approximately one calendar year, 8760 hours. After this, it is automatically terminated.

For a click-through demo, see GitLab workspaces.

A Workspace runs on any linux/amd64 Kubernetes cluster. If you need to run sudo commands, or build and run containers in your workspace, there might be platform-specific requirements.

For more information, see Platform compatibility.

Workspaces and projects

Workspaces are scoped to a project. When you create a workspace, you must:

• Assign the workspace to a specific project.
• Select a project with a devfile.

The workspace can interact with the GitLab API, with the access level defined by current user permissions. A running workspace remains accessible to the user even if user permissions are later revoked.

Manage workspaces from a project

Version history

• Introduced in GitLab 16.2.

To manage workspaces from a project:

1. On the left sidebar, select Search or go to and find your project.
2. In the upper right, select Code.
3. From the dropdown list, under Your workspaces, you can:
   • Restart, stop, or terminate an existing workspace.
   • Create a new workspace.

When you terminate a workspace, GitLab deletes any unsaved or uncommitted data in that workspace. The data cannot be recovered.

Deleting resources associated with a workspace

When you terminate a workspace, you delete all resources associated with the workspace. When you delete a project, agent, user, or token associated with a running workspace:

• The workspace is deleted from the user interface.
• In the Kubernetes cluster, the running workspace resources become orphaned and are not automatically deleted.

To clean up orphaned resources, an administrator must manually delete the workspace in Kubernetes.

Issue 414384 proposes to change this behavior.

Manage workspaces at the agent level

Version history

• Introduced in GitLab 16.8.

To manage all workspaces associated with an agent:

1. On the left sidebar, select Search or go to and find your project.
2. Select Operate > Kubernetes clusters.
3. Select the agent configured for remote development.
4. Select the Workspaces tab.
5. From the list, you can restart, stop, or terminate an existing workspace.

When you terminate a workspace, GitLab deletes any unsaved or uncommitted data in that workspace. The data cannot be recovered.

Identify an agent from a running workspace

In deployments that contain multiple agents, you might want to identify an agent from a running workspace.

To identify an agent associated with a running workspace, use one of the following GraphQL endpoints:

• agent-id to return the project the agent belongs to.
• Query.workspaces to return:
  • The cluster agent associated with the workspace.
  • The project the agent belongs to.

Devfile

Workspaces have built-in support for devfiles. Devfiles are files that define a development environment by specifying the necessary tools, languages, runtimes, and other components for a GitLab project. Use them to automatically configure your development environment with your defined specifications. They create consistent and reproducible development environments, regardless of the machine or platform you use.

Workspaces support both GitLab default devfile and custom devfiles.

GitLab default devfile

Version history

• Introduced with Go in GitLab 17.8.
• Added support for Node, Ruby, and Rust in GitLab 17.9.
• Added support for Python, PHP, Java, and GCC in GitLab 18.0.

A GitLab default devfile is available for all projects when you create a workspace. This devfile contains:

schemaVersion: 2.2.0
components:
  - name: development-environment
    attributes:
      gl/inject-editor: true
    container:
      image: "registry.gitlab.com/gitlab-org/gitlab-build-images/workspaces/ubuntu-24.04:[VERSION_TAG]"

This container image is updated regularly. [VERSION_TAG] is a placeholder only. For the latest version, see the default default_devfile.yaml.

The workspace default image includes development tools such as Ruby, Node.js, Rust, Go, Python, Java, PHP, GCC, and their corresponding package managers. These tools are updated regularly.

A GitLab default devfile might not be suitable for all development environments configurations. In these cases, you can create a custom devfile.

Custom devfile

If you need a specific development environment configuration, create a custom devfile. You can define a devfile in the following locations, relative to your project's root directory:

- /.devfile.yaml
- /.devfile.yml
- /.devfile/{devfile_name}.yaml
- /.devfile/{devfile_name}.yml

Devfiles must be placed directly in the .devfile folder. Nested subfolders are not supported. For example, .devfile/subfolder/devfile.yaml is not recognized.

Validation rules

• schemaVersion must be 2.2.0.
• The devfile must have at least one component.
• The devfile size must not exceed 3 MB.
• For components:
  • Names must not start with gl-.
  • Only container and volume are supported.
• For commands:
  • IDs must not start with gl-.
  • Only exec and apply command types are supported.
  • For exec commands, only the following options are supported: commandLine, component, label, and hotReloadCapable.
  • When hotReloadCapable is specified for exec commands, it must be set to false.
• For events:
  • Names must not start with gl-.
  • Only preStart and postStart are supported.
  • The Devfile standard only allows exec commands to be linked to postStart events. If you want an apply command, you must use a preStart event.
• parent, projects, and starterProjects are not supported.
• For variables, keys must not start with gl-, gl_, GL-, or GL_.
• For attributes:
  • pod-overrides must not be set at the root level or in components.
  • container-overrides must not be set in components.

container component type

Use the container component type to define a container image as the execution environment for a workspace. You can specify the base image, dependencies, and other settings.

The container component type supports the following schema properties only:

overrideCommand attribute

The overrideCommand attribute is a boolean that controls how Workspaces handle container entrypoints. This attribute determines whether the container's original entrypoint is preserved or replaced with a keep-alive command.

The default value for overrideCommand depends on the component type:

• Main component with attribute gl/inject-editor: true: Defaults to true when not specified.
• All other components: Defaults to false when not specified.

When true, the container entrypoint is replaced with tail -f /dev/null to keep the container running. When false, the container uses either the devfile component command/args or the built container image's Entrypoint/Cmd.

The following table shows how overrideCommand affects container behavior. For clarity, these terms are used in the table:

• Devfile component: The command and args properties in the devfile component entry.
• Container image: The Entrypoint and Cmd fields in the OCI container image.

Footnotes:

1. When you create a workspace, it cannot access container image details, for example, from private or internal registries. When overrideCommand is false and the Devfile doesn't specify command or args, GitLab does not validate container images or check for required Entrypoint or Cmd fields. You must ensure that either the Devfile or container specifies these fields, or the container exits prematurely and the workspace fails to start.

User-defined postStart events

You can define custom postStart events in your devfile to run commands after the workspace starts. These postStart events do not block workspace accessibility. The workspace becomes available as soon as internal initialization is complete, even if your custom postStart commands are still running or waiting to run.

Use this type of event to:

• Set up development dependencies.
• Configure the workspace environment.
• Run initialization scripts.

postStart event names must not start with gl- and can only reference exec type commands.

For an example that shows how to configure postStart events, see the example configurations.

Monitor postStart event progress

When your workspace runs postStart events, you can monitor their progress and check the workspace logs. All postStart command output is captured in log files located in the workspace logs directory.

To check the progress of your postStart scripts:

1. Open a terminal in your workspace.

2. Go to the workspace logs directory:

   cd /tmp/workspace-logs/

3. View the output logs to see command results:

   tail -f poststart-stdout.log

Example configurations

The following is an example devfile configuration:

schemaVersion: 2.2.0
variables:
  registry-root: registry.gitlab.com
components:
  - name: tooling-container
    attributes:
      gl/inject-editor: true
    container:
      image: "{{registry-root}}/gitlab-org/remote-development/gitlab-remote-development-docs/ubuntu:22.04"
      env:
        - name: KEY
          value: VALUE
      endpoints:
        - name: http-3000
          targetPort: 3000
commands:
  - id: install-dependencies
    exec:
      component: tooling-container
      commandLine: "npm install"
  - id: setup-environment
    exec:
      component: tooling-container
      commandLine: "echo 'Setting up development environment'"
events:
  postStart:
    - install-dependencies
    - setup-environment

This container image is for demonstration purposes only. To use your own container image, see Arbitrary user IDs.

For more information, see the devfile documentation. For other examples, see the examples projects.

Workspace container requirements

By default, workspaces inject and start the GitLab VS Code fork in the container that has a defined gl/inject-editor attribute in the devfile. The workspace container where the GitLab VS Code fork is injected must meet the following system requirements:

• System architecture: AMD64
• System libraries:
  • glibc 2.28 and later
  • glibcxx 3.4.25 and later

These requirements have been tested on Debian 10.13 and Ubuntu 20.04. For more information, see the VS Code documentation.

GitLab always pulls the workspace injector image (gl-tools-injector) and project cloner image (gl-project-cloner) from the GitLab registry (registry.gitlab.com/gitlab-org/gitlab-web-ide-vscode-fork/web-ide-injector). These images cannot be overridden.

If you use a private container registry for your other images, GitLab still needs to fetch these specific images from the GitLab registry. This requirement may impact environments with strict network controls, such as offline environments.

Workspace add-ons

Version history

• Introduced in GitLab 17.2.

The GitLab Workflow extension for VS Code is configured by default in workspaces.

With this extension, you can view issues, create merge requests, and manage CI/CD pipelines. This extension also powers AI features like GitLab Duo Code Suggestions and GitLab Duo Chat.

For more information, see GitLab Workflow extension for VS Code.

Extension marketplace

• Status: Beta

Version history

• Introduced as a beta in GitLab 16.9 with a flag named allow_extensions_marketplace_in_workspace. Disabled by default.
• Feature flag allow_extensions_marketplace_in_workspace removed in GitLab 17.6.

The VS Code Extension Marketplace provides you with access to extensions that enhance the functionality of your workspace.

You can use the extension marketplace in your workspace Web IDE. The extension marketplace connects to the Open VSX Registry. For more information, see Configure VS Code Extension Marketplace.

Personal access token

Version history

• Introduced in GitLab 16.4.
• api permission added in GitLab 17.2.

When you create a workspace, you get a personal access token with write_repository and api permissions. Use this token to clone the project initially, while starting the workspace, and to configure the GitLab Workflow extension for VS Code.

Any Git operation you perform in the workspace uses this token for authentication and authorization. Terminating the workspace revokes the token.

Use the GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n, and GIT_CONFIG_VALUE_n environment variables for Git authentication in the workspace. These variables require Git 2.31 or later in the workspace container.

Pod interaction in a cluster

Workspaces run as pods in a Kubernetes cluster. GitLab does not impose any restrictions on the manner in which pods interact with each other.

Consider isolating this feature from other containers in your cluster, because of this requirement.

Network access and workspace authorization

It's the client's responsibility to restrict network access to the Kubernetes control plane because GitLab does not have control over the API.

Only the workspace creator can access the workspace and any endpoints exposed in that workspace. The workspace creator is only authorized to access the workspace after user authentication with OAuth.

Compute resources and volume storage

When you stop a workspace, GitLab scales the compute resources for that workspace down to zero. However, the volume provisioned for the workspace still exists.

To delete the provisioned volume, you must terminate the workspace.

Automatic workspace stop and termination

Version history

• Introduced in GitLab 17.6.

By default, a workspace automatically:

• Stops 36 hours after the workspace was last started or restarted. For more information, see max_active_hours_before_stop.
• Terminates 722 hours after the workspace was last stopped. For more information, see max_stopped_hours_before_termination.

Arbitrary user IDs

You can provide your own container image, which can run as any Linux user ID.

It's not possible for GitLab to predict the Linux user ID for a container image. GitLab uses the Linux root group ID permission to create, update, or delete files in a container. The container runtime used by the Kubernetes cluster must ensure all containers have a default Linux group ID of 0.

If you have a container image that does not support arbitrary user IDs, you cannot create, update, or delete files in a workspace. To create a container image that supports arbitrary user IDs, see Create a custom workspace image that supports arbitrary user IDs.

For more information, see the OpenShift documentation.

Workspace logs directory

When a workspace starts, GitLab creates a logs directory to capture output from various initialization and startup processes.

The workspace logs are stored in /tmp/workspace-logs/.

This directory helps you monitor workspace startup progress and troubleshoot issues with postStart events, development tools, and other workspace components. For more information, see Debug postStart events.

Available log files

The logs directory contains the following log files:

Log files are recreated each time you restart a workspace. Previous log files are not preserved when you stop and restart a workspace.

Shallow cloning

Version history

• Introduced in GitLab 18.2 with a flag named workspaces_shallow_clone_project. Disabled by default.

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

When you create a workspace, GitLab uses shallow cloning to improve performance. A shallow clone downloads only the latest commit history instead of the complete Git history, which significantly reduces the initial clone time for large repositories.

After the workspace starts, Git converts the shallow clone to a full clone in the background. This process is transparent and doesn't affect your development workflow.

Related topics

• Troubleshooting Workspaces