工作空间

工作空间是 GitLab 中代码的虚拟沙盒环境。 您可以使用工作空间为 GitLab 项目创建和管理隔离的开发环境。 这些环境确保不同项目之间不会相互干扰。

每个工作空间都包含自己的依赖项、库和工具集，您可以根据每个项目的特定需求进行自定义。

工作空间最多可以存在大约一个日历年，即 8760 小时。之后，它将被自动终止。

点击演示，请参阅 GitLab 工作空间。

工作空间和项目

工作空间限定在项目范围内。 当您 创建工作空间 时，必须：

• 将工作空间分配给特定项目。
• 选择带有 devfile 的项目。

工作空间可以与 GitLab API 交互，访问级别由当前用户权限定义。 即使用户权限稍后被撤销，运行中的工作空间对用户仍然保持可访问。

从项目管理工作空间

要从项目管理工作空间：

1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。
2. 在右上角，选择 代码。
3. 从下拉列表中，在 您的工作空间 下，您可以：
   • 重启、停止或终止现有工作空间。
   • 创建新工作空间。

删除与工作空间关联的资源

当您终止工作空间时，您会删除与该工作空间关联的所有资源。 当您删除与运行中的工作空间关联的项目、代理、用户或令牌时：

• 工作空间将从用户界面中删除。
• 在 Kubernetes 集群中，运行中的工作空间资源将变成孤立的，不会被自动删除。

要清理孤立的资源，管理员必须手动在 Kubernetes 中删除工作空间。

问题 414384 提议更改此行为。

在代理级别管理工作空间

要管理与代理关联的所有工作空间：

1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。
2. 选择 运维 > Kubernetes 集群。
3. 选择为远程开发配置的代理。
4. 选择 工作空间 标签页。
5. 从列表中，您可以重启、停止或终止现有工作空间。

从运行中的工作空间识别代理

在包含多个代理的部署中，您可能希望从运行中的工作空间识别代理。

要识别与运行中的工作空间关联的代理，请使用以下 GraphQL 端点之一：

• agent-id 返回代理所属的项目。
• Query.workspaces 返回：
  • 与工作空间关联的 集群代理。
  • 代理所属的项目。

Devfile

工作空间内置支持 devfile。Devfile 是通过为 GitLab 项目指定必要的工具、语言、运行时和其他组件来定义开发环境的文件。 使用它们可以根据您的定义规范自动配置开发环境。无论您使用什么机器或平台，它们都能创建一致且可复现的开发环境。

工作空间支持 GitLab 默认 devfile 和自定义 devfile。

GitLab 默认 devfile

创建工作空间时，所有项目都可以使用 GitLab 默认 devfile。 此 devfile 包含：

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]"

工作空间默认镜像包含 Ruby、Node.js、Rust、Go、Python、Java、PHP、GCC 等开发工具及其相应的包管理器。这些工具会定期更新。

GitLab 默认 devfile 可能不适合所有开发环境配置。在这些情况下，您可以创建 自定义 devfile。

自定义 devfile

如果您需要特定的开发环境配置，请创建自定义 devfile。 您可以在相对于项目根目录的以下位置定义 devfile：

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

验证规则

• schemaVersion 必须是 2.2.0。
• Devfile 必须至少有一个组件。
• Devfile 大小不能超过 3 MB。
• 对于 components：
  • 名称不能以 gl- 开头。
  • 仅支持 container 和 volume。
• 对于 commands：
  • ID 不能以 gl- 开头。
  • 仅支持 exec 和 apply 命令类型。
  • 对于 exec 命令，仅支持以下选项：commandLine、component、label 和 hotReloadCapable。
  • 当为 exec 命令指定 hotReloadCapable 时，必须将其设置为 false。
• 对于 events：
  • 名称不能以 gl- 开头。
  • 仅支持 preStart 和 postStart。
  • Devfile 标准只允许将 exec 命令链接到 postStart 事件。如果您想要 apply 命令，必须使用 preStart 事件。
• parent、projects 和 starterProjects 不受支持。
• 对于 variables，键不能以 gl-、gl_、GL- 或 GL_ 开头。
• 对于 attributes：
  • pod-overrides 不能在根级别或 components 中设置。
  • container-overrides 不能在 components 中设置。

container 组件类型

使用 container 组件类型将容器镜像定义为工作空间的执行环境。您可以指定基础镜像、依赖项和其他设置。

container 组件类型仅支持以下架构属性：

overrideCommand 属性

overrideCommand 属性是一个布尔值，控制工作空间如何处理容器入口点。此属性决定是保留容器的原始入口点还是用保持活跃的命令替换它。

overrideCommand 的默认值取决于组件类型：

• 带有 gl/inject-editor: true 属性的主组件：未指定时默认为 true。
• 所有其他组件：未指定时默认为 false。

当 true 时，容器入口点被替换为 tail -f /dev/null 以保持容器运行。 当 false 时，容器使用 devfile 组件的 command/args 或构建的容器镜像的 Entrypoint/Cmd。

下表显示了 overrideCommand 如何影响容器行为。为清晰起见，表中使用以下术语：

• Devfile 组件：devfile 组件条目中的 command 和 args 属性。
• 容器镜像：OCI 容器镜像中的 Entrypoint 和 Cmd 字段。

脚注：

1. 当您创建工作空间时，它无法访问容器镜像详细信息，例如来自私有或内部注册表的镜像。当 overrideCommand 为 false 且 Devfile 未指定 command 或 args 时，GitLab 不会验证容器镜像或检查必需的 Entrypoint 或 Cmd 字段。您必须确保 Devfile 或容器指定了这些字段，否则容器会提前退出，工作空间启动失败。

用户定义的 postStart 事件

您可以在 devfile 中定义自定义 postStart 事件，在工作空间启动后运行命令。这些 postStart 事件不会阻塞工作空间的可访问性。一旦内部初始化完成，工作空间即可使用，即使您的自定义 postStart 命令仍在运行或等待运行。

使用此类事件来：

• 设置开发依赖项。
• 配置工作空间环境。
• 运行初始化脚本。

postStart 事件名称不能以 gl- 开头，且只能引用 exec 类型命令。

有关如何配置 postStart 事件的示例，请参阅 示例配置。

示例配置

以下是示例 devfile 配置：

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

有关更多信息，请参阅 devfile 文档。其他示例请参阅 examples 项目。

工作空间容器要求

默认情况下，工作空间会在 devfile 中定义了 gl/inject-editor 属性的容器中注入并启动 GitLab VS Code fork。 注入了 GitLab VS Code fork 的工作空间容器必须满足以下系统要求：

• 系统架构：AMD64
• 系统库：
  • glibc 2.28 及更高版本
  • glibcxx 3.4.25 及更高版本

这些要求已在 Debian 10.13 和 Ubuntu 20.04 上测试过。有关更多信息，请参阅 VS Code 文档。

工作空间附加组件

GitLab Workflow 扩展 for VS Code 在工作空间中默认配置。

使用此扩展，您可以查看问题、创建合并请求和管理 CI/CD 管道。此扩展还支持 AI 功能，如 GitLab Duo Code Suggestions 和 GitLab Duo Chat。

有关更多信息，请参阅 GitLab Workflow extension for VS Code。

扩展市场

VS Code 扩展市场为您提供访问增强工作空间功能的扩展。

您可以在工作空间 Web IDE 中使用 扩展市场。扩展市场连接到 Open VSX 注册表。有关更多信息，请参阅 配置 VS Code 扩展市场。

个人访问令牌

当您 创建工作空间 时，您会获得具有 write_repository 和 api 权限的个人访问令牌。 使用此令牌初始克隆项目、启动工作空间以及配置 GitLab Workflow 扩展 for VS Code。

您在工作空间中执行的任何 Git 操作都使用此令牌进行身份验证和授权。终止工作空间会撤销该令牌。

在工作空间中使用 GIT_CONFIG_COUNT、GIT_CONFIG_KEY_n 和 GIT_CONFIG_VALUE_n 环境变量 进行 Git 身份验证。这些变量要求工作空间容器中安装 Git 2.31 或更高版本。

集群中的 Pod 交互

工作空间在 Kubernetes 集群中作为 pod 运行。GitLab 对 pod 之间的交互方式不施加任何限制。

由于此要求，请考虑将此功能与集群中的其他容器隔离。

网络访问和工作空间授权

限制对 Kubernetes 控制平面的网络访问是客户端的责任，因为 GitLab 无法控制 API。

只有工作空间创建者可以访问工作空间和在该工作空间中暴露的任何端点。工作空间创建者只有在通过 OAuth 进行用户身份验证后才能被授权访问工作空间。

计算资源和卷存储

当您停止工作空间时，GitLab 将该工作空间的计算资源缩减为零。但是，为工作空间配置的卷仍然存在。

要删除配置的卷，您必须终止工作空间。

自动工作空间停止和终止

默认情况下，工作空间会自动：

• 在工作空间上次启动或重启后 36 小时停止。有关更多信息，请参阅 max_active_hours_before_stop。
• 在工作空间上次停止后 722 小时终止。有关更多信息，请参阅 max_stopped_hours_before_termination。

任意用户 ID

您可以提供自己的容器镜像，它可以以任何 Linux 用户 ID 运行。

GitLab 无法预测容器镜像的 Linux 用户 ID。GitLab 使用 Linux root 组 ID 权限在容器中创建、更新或删除文件。Kubernetes 集群使用的容器运行时必须确保所有容器都具有默认的 Linux 组 ID 0。

如果您有不支持任意用户 ID 的容器镜像，您无法在工作空间中创建、更新或删除文件。要创建支持任意用户 ID 的容器镜像，请参阅 创建支持任意用户 ID 的自定义工作空间镜像。

有关更多信息，请参阅 OpenShift 文档。

浅克隆

当您创建工作空间时，GitLab 使用浅克隆来提高性能。浅克隆只下载最新的提交历史，而不是完整的 Git 历史，这大大减少了大型仓库的初始克隆时间。

工作空间启动后，Git 在后台将浅克隆转换为完整克隆。此过程是透明的，不会影响您的工作流程。

相关主题

• 工作空间故障排除