ワークスペース

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

ワークスペースは、GitLabのコード用の仮想サンドボックス環境です。ワークスペースを使用すると、GitLabプロジェクト用の隔離された開発環境を作成および管理できます。これらの環境により、異なるプロジェクトが互いに干渉しないようにすることができます。

各ワークスペースは、独自の依存関係、ライブラリ、ツールで構成され、各プロジェクトの特定のニーズに合わせてカスタマイズできます。

ワークスペースは、最大で約1暦年、8760時間存在できます。この期間を過ぎると、ワークスペースは自動的に終了します。

クリックスルーデモについては、GitLabワークスペースを参照してください。

ワークスペースは、Kubernetes向けGitLabエージェントサーバー（agentk）をサポートするあらゆるlinux/amd64 Kubernetesクラスター上で実行されます。sudoコマンドを実行したり、ワークスペース内でコンテナをビルドする必要がある場合、プラットフォーム固有の要件がある可能性があります。

詳細については、プラットフォームの互換性を参照してください。

ワークスペースとプロジェクト

ワークスペースのスコープはプロジェクトに設定されます。ワークスペースを作成する際には、以下を行う必要があります:

ワークスペースを特定のプロジェクトに割り当てます。
devfileを使用してプロジェクトを選択します。

ワークスペースは、現在のユーザー権限によって定義されたアクセスレベルで、GitLab APIとやり取りできます。ユーザー権限が後で取り消された場合でも、実行中のワークスペースにユーザーは引き続きアクセスできます。

プロジェクトからワークスペースを管理する

プロジェクトからワークスペースを管理するには:

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
右上にあるコードを選択します。
ドロップダウンリストのあなたのワークスペースで、次の操作を実行できます:
- 既存のワークスペースを再起動、停止、または終了します。
- 新しいワークスペースを作成します。

ワークスペースを終了すると、GitLabはそのワークスペース内の保存されていないデータやコミットされていないデータを削除します。データを復元することはできません。

ワークスペースに関連付けられたリソースを削除する

ワークスペースを終了すると、ワークスペースに関連付けられているすべてのリソースが削除されます。プロジェクト、agentk、ユーザー、または実行中のワークスペースに関連付けられたトークンを削除すると:

ワークスペースはユーザーインターフェースから削除されます。
Kubernetesクラスターでは、実行中のワークスペースリソースは孤立状態になり、自動的に削除されません。

孤立したリソースをクリーンアップするには、管理者はKubernetesでワークスペースを手動で削除する必要があります。

エピック11452は、この動作を変更することを提案しています。

エージェントレベルでワークスペースを管理する

agentkに関連付けられているすべてのワークスペースを管理するには:

上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
操作 > Kubernetesクラスターを選択します。
リモート開発用に設定されたエージェントを選択します。
ワークスペースタブを選択します。
リストから、既存のワークスペースを再起動、停止、または終了できます。

実行中のワークスペースからエージェントを特定する

複数のagentkデプロイメントを含む環境では、実行中のワークスペースからエージェントを特定したい場合があります。

実行中のワークスペースに関連付けられているエージェントを特定するには、次のいずれかの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]"

このコンテナのimageは定期的に更新されます。[VERSION_TAG]はプレースホルダーにすぎません。最新バージョンについては、デフォルトのdefault_devfile.yamlを参照してください。

ワークスペースのデフォルトイメージには、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

devfileは.devfileフォルダー内に直接配置する必要があります。ネストされたサブフォルダーはサポートされていません。たとえば、.devfile/subfolder/devfile.yamlは認識されません。

検証ルール

devfileのサイズは3 MBを超えてはなりません。

プロパティ	明示的なルール
`schemaVersion`	`2.2.0`である必要があります。
`components`	- devfileには少なくとも1つのコンポーネントが必要です。 - 名前は`gl-`で始まってはいけません。 - `container`と`volume`のみがサポートされています。 - `mountSources`と`sourceMapping`はサポートされていません。
`commands`	- IDは`gl-`で始まってはいけません。 - `exec`と`apply`コマンドタイプのみがサポートされています。 - `exec`コマンドの場合、以下のオプションのみがサポートされます。`commandLine`、`component`、`label`、および`hotReloadCapable`。 - `hotReloadCapable`が`exec`コマンドに対して指定されている場合、`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コンポーネントタイプは、次のスキーマプロパティのみをサポートします。

プロパティ	説明
`image` ¹	ワークスペースに使用するコンテナイメージの名前。
`memoryRequest`	コンテナが使用できるメモリの最小量。
`memoryLimit`	コンテナが使用できるメモリの最大量。
`cpuRequest`	コンテナが使用できるCPUの最小量。
`cpuLimit`	コンテナが使用できるCPUの最大量。
`env`	コンテナで使用する環境変数。名前を`gl-`で始めることはできません。
`endpoints`	コンテナから公開するポートマッピング。名前を`gl-`で始めることはできません。
`volumeMounts`	コンテナにマウントするストレージボリューム。
`command`	コンテナのエントリポイントをオーバーライドするコマンド。`overrideCommand`属性を参照してください。
`args`	コンテナのコマンドに対する引数。`overrideCommand`属性を参照してください。

脚注:

imageプロパティにカスタムコンテナイメージを作成する場合、ワークスペースベースイメージを基盤として使用できます。これには、SSHアクセス、ユーザー権限、およびワークスペースの互換性に関する重要な設定が含まれています。ベースイメージを使用しない場合は、カスタムイメージがすべてのワークスペース要件を満たしていることを確認してください。

`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フィールド。

`overrideCommand`	Devfileコンポーネント	コンテナイメージ	結果
`true`	指定済み	指定済み	検証エラー: `overrideCommand`が`true`の場合、devfileコンポーネントの`command`/`args`は指定できません。
`true`	指定済み	未指定	検証エラー: `overrideCommand`が`true`の場合、devfileコンポーネントの`command`/`args`は指定できません。
`true`	未指定	指定済み	コンテナのエントリポイントは`tail -f /dev/null`に置き換えられます。
`true`	未指定	未指定	コンテナのエントリポイントは`tail -f /dev/null`に置き換えられます。
`false`	指定済み	指定済み	Devfileコンポーネントの`command`/`args`がエントリポイントとして使用されます。
`false`	指定済み	未指定	Devfileコンポーネントの`command`/`args`がエントリポイントとして使用されます。
`false`	未指定	指定済み	コンテナイメージの`Entrypoint`/`Cmd`が使用されます。
`false`	未指定	未指定	コンテナが途中で終了します（`CrashLoopBackOff`）。¹

脚注:

ワークスペースを作成する際、プライベートまたは内部レジストリなどからコンテナイメージの詳細にアクセスすることはできません。overrideCommandがfalseでDevfileがcommandまたはargsを指定しない場合、GitLabはコンテナイメージを検証することも、必要なEntrypointまたはCmdフィールドをチェックすることもありません。Devfileまたはコンテナのいずれかがこれらのフィールドを指定していることを確認する必要があります。そうしないと、コンテナが途中で終了し、ワークスペースが起動に失敗します。

ユーザー定義の`postStart`イベント

devfileでカスタムpostStartイベントを定義して、ワークスペースの起動後にコマンドを実行できます。これらのpostStartイベントはワークスペースのアクセシビリティをブロックしません。内部初期化が完了するとすぐにワークスペースが利用可能になります。カスタムのpostStartコマンドがまだ実行中または実行待機中であっても同様です。

このタイプのイベントは以下に使用します:

開発依存関係を設定します。
ワークスペース環境を設定します。
初期化スクリプトを実行します。

postStartイベント名はgl-で始まってはならず、execタイプのコマンドのみを参照できます。

postStartイベントを設定する方法を示す例については、例の設定を参照してください。

`postStart`コマンドの作業ディレクトリ

デフォルトでは、postStartコマンドはコンポーネントに応じて異なる作業ディレクトリで実行されます:

属性がgl/inject-editor: trueのメインコンポーネント: コマンドはプロジェクトディレクトリ（/projects/<project-path>）で実行されます。
その他のコンポーネント: コマンドはコンテナのデフォルト作業ディレクトリで実行されます。

workingDirをコマンド定義で指定することで、デフォルトの動作をオーバーライドできます:

commands:
  - id: install-dependencies
    exec:
      component: tooling-container
      commandLine: "npm install"
      workingDir: "/custom/path"
  - id: setup-project
    exec:
      component: tooling-container
      commandLine: "echo 'Setting up in project directory'"
      # Runs in project directory by default

`postStart`イベントの進捗を監視する

ワークスペースがpostStartイベントを実行している間、その進捗を監視し、ワークスペースのログを確認できます。postStartスクリプトの進捗を確認するには:

ワークスペースでターミナルを開きます。
ワークスペースのログディレクトリに移動します:
```
cd /tmp/workspace-logs/
```
出力ログを表示してコマンド結果を確認します:
```
tail -f poststart-stdout.log
```

すべての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
  - name: database-container
    attributes:
      overrideCommand: false
    container:
      image: mysql
      command: ["echo"]
      args: ["-n", "user-defined entrypoint command"]
      env:
        - name: MYSQL_ROOT_PASSWORD
          value: "my-secret-pw"
commands:
  # Command 1: Container 1, no working directory (uses project directory)
  - id: install-dependencies
    exec:
      component: tooling-container
      commandLine: "npm install"

  # Command 2: Container 1, with working directory
  - id: setup-environment
    exec:
      component: tooling-container
      commandLine: "echo 'Setting up development environment'"
      workingDir: "/home/gitlab-workspaces"

  # Command 3: Container 2, no working directory (uses container default)
  - id: init-database
    exec:
      component: database-container
      commandLine: "echo 'Database initialized' > db-init.log"

  # Command 4: Container 2, with working directory
  - id: setup-database
    exec:
      component: database-container
      commandLine: "mkdir -p /var/lib/mysql/logs && echo 'DB setup complete' > setup.log"
      workingDir: "/var/lib/mysql"

events:
  postStart:
    - install-dependencies
    - setup-environment
    - init-database
    - setup-database

このコンテナのimageはデモンストレーションのみを目的としています。

その他の例については、examplesプロジェクトを参照してください。

ワークスペースコンテナの要件

デフォルトでは、ワークスペースは、devfileに定義されたgl/inject-editor属性を持つコンテナにGitLab VS Codeフォークを挿入して起動します。GitLab VS Codeフォークが挿入されるワークスペースコンテナは、次のシステム要件を満たしている必要があります。

システムアーキテクチャ: AMD64
システムライブラリ:
- glibc 2.28以降
- glibcxx 3.4.25以降

これらの要件は、Debian 10.13とUbuntu 20.04でテスト済みです。

GitLabは常にワークスペースツールインジェクターイメージをGitLabレジストリ（registry.gitlab.com）からプルします。このイメージをオーバーライドすることはできません。

他のイメージにプライベートコンテナレジストリを使用している場合、GitLabはこれらの特定のイメージをGitLabレジストリからフェッチします。この要求事項は、オフライン環境など、厳格なネットワークコントロールを備えた環境に影響を与える可能性があります。

ワークスペースベースイメージ

GitLabは、すべてのワークスペース環境の基盤となるワークスペースベースイメージ（registry.gitlab.com/gitlab-org/gitlab-build-images:workspaces-base）を提供します。

ベースイメージには以下が含まれます:

安定したLinuxオペレーティングシステムの基盤。
ワークスペース操作に適したユーザー権限を持つ、事前設定されたユーザー。
必須の開発ツールとシステムライブラリ。
プログラミング言語とツールのバージョン管理。
リモートアクセス用のSSHサーバー設定。
任意のユーザーIDをサポートするためのセキュリティ設定。

ワークスペースベースイメージを使用しない場合は、カスタムワークスペースイメージを作成できます。GitLabがカスタムイメージを適切に初期化して接続できるようにするには、必要な設定コマンドをベースイメージDockerfileから自身のDockerfileにコピーしてください。

ベースイメージを拡張する

ワークスペースベースイメージに基づいてカスタムワークスペースイメージを作成できます。例:

FROM registry.gitlab.com/gitlab-org/gitlab-build-images:workspaces-base

# Install additional tools
RUN sudo apt-get update && sudo apt-get install -y \
    your-additional-package \
    && sudo rm -rf /var/lib/apt/lists/*

# Install specific language versions
RUN mise install python@3.11 && mise use python@3.11

ワークスペースのアドオン

ワークスペースでは、VS Code用GitLab拡張機能がデフォルトで設定されています。

この拡張機能を使用すると、イシューの表示、マージリクエストの作成、CI/CDパイプラインの管理を行うことができます。この拡張機能は、GitLab Duoコード提案やGitLab Duo ChatなどのAI機能を強化します。

拡張機能マーケットプレース

ステータス: ベータ版

VS Code拡張機能マーケットプレースは、Web IDEの機能を強化する拡張機能へのアクセスを提供します。デフォルトでは、GitLab Web IDEはOpen VSX Registryに接続します。

詳細については、VS Code拡張機能マーケットプレースを設定するを参照してください。

パーソナルアクセストークン

ワークスペースを作成すると、write_repositoryおよびapi API権限を持つ、365日で期限が切れるパーソナルアクセストークンが発行されます。このトークンは、プロジェクトを初期クローンしたり、ワークスペースを起動したり、VS Code用GitLab拡張機能を設定するために使用されます。

ワークスペースで実行するGit操作は、認証と認可にこのトークンを使用します。ワークスペースを終了すると、トークンは失効します。

ワークスペースでGit認証を行うには、GIT_CONFIG_COUNT、GIT_CONFIG_KEY_n、およびGIT_CONFIG_VALUE_n環境変数を使用します。これらの変数には、ワークスペースコンテナでGit 2.31以降が必要です。

クラスター内のポッドのやり取り

ワークスペースは、Kubernetesクラスター内のポッドとして実行されます。GitLabは、ポッドが相互にやり取りする方法に制限を加えません。

この要求事項があるため、この機能をクラスター内の他のコンテナから隔離することを検討してください。

ネットワークアクセスとワークスペースの認証

GitLabはAPIを制御できないため、Kubernetesコントロールプレーンへのネットワークアクセスを制限する責任はクライアント側にあります。

ワークスペースの作成者のみが、ワークスペースおよびワークスペースで公開されているすべてのエンドポイントにアクセスできます。ワークスペースの作成者は、OAuthでユーザー認証を行った後にのみ、ワークスペースにアクセスすることが認可されます。

コンピューティングリソースとボリュームストレージ

ワークスペースを停止すると、GitLabはそのワークスペースのコンピューティングリソースをゼロにスケールダウンします。ただし、ワークスペース用にプロビジョニングされたボリュームは引き続き存在します。

プロビジョニングされたボリュームを削除するには、ワークスペースを終了する必要があります。

ワークスペースの自動停止と終了

デフォルトでは、ワークスペースは自動的に次のように処理されます。

ワークスペースが最後に起動または再起動されてから36時間後に停止します。
ワークスペースが最後に停止されてから722時間後に終了します。

任意のユーザーID

コンテナイメージを自分で用意できます。このイメージは、任意のLinuxユーザーIDとして実行できます。

GitLabでは、コンテナイメージのLinuxユーザーIDを予測できません。GitLabは、Linux rootグループID権限を使用して、コンテナ内でファイルを作成、更新、または削除します。Kubernetesクラスターで使用されるコンテナランタイムでは、すべてのコンテナのデフォルトのLinuxグループIDが0であることを確認する必要があります。

任意のユーザーIDをサポートしていないコンテナイメージがある場合、ワークスペース内でファイルを作成、更新、または削除することはできません。任意のユーザーIDをサポートするコンテナイメージを作成するには、任意のユーザーIDをサポートするカスタムワークスペースイメージを作成するを参照してください。

ワークスペースログディレクトリ

ワークスペースが起動すると、GitLabはさまざまな初期化および起動プロセスからの出力をキャプチャするためのログディレクトリを作成します。

ワークスペースのログは/tmp/workspace-logs/に保存されます。

このディレクトリは、ワークスペースの起動進捗を監視し、postStartイベント、開発ツール、およびその他のワークスペースコンポーネントに関する問題をトラブルシューティングを行うのに役立ちます。詳細については、デバッグpostStartイベントを参照してください。

利用可能なログファイル

ログディレクトリには、以下のログファイルが含まれています:

ログファイル	目的	内容
`poststart-stdout.log`	`postStart`コマンド出力	ユーザー定義コマンドや内部GitLab起動タスクを含む、すべての`postStart`コマンドの標準出力。
`poststart-stderr.log`	`postStart`コマンドエラー	`postStart`コマンドからのエラー出力と`stderr`。これらのログを使用して、起動スクリプトの失敗をトラブルシューティングを行うことができます。
`start-vscode.log`	VS Codeサーバー起動	GitLab VS Codeフォークサーバーの初期化からのログ。
`start-sshd.log`	SSHデーモン起動	SSHデーモンの初期化からの出力で、サーバー起動や設定の詳細が含まれます。
`clone-unshallow.log`	Gitリポジトリ変換	シャロークローンをフルクローンに変換し、プロジェクトの完全なGit履歴を取得するバックグラウンドプロセスからのログ。

ログファイルは、ワークスペースを再起動するたびに再作成されます。ワークスペースを停止して再起動しても、以前のログファイルは保持されません。

シャロークローン

ワークスペースを作成すると、GitLabはシャロークローンを使用してパフォーマンスを向上させます。シャロークローンは、完全なGit履歴ではなく最新のコミット履歴のみをダウンロードするため、大規模なリポジトリの初期クローン時間を大幅に短縮します。

ワークスペースが起動した後、Gitはバックグラウンドでシャロークローンをフルクローンに変換します。このプロセスは透過的であり、開発ワークフローに影響を与えません。