正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

ワークスペース

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

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

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

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

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

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

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

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

ワークスペースのスコープはプロジェクトに設定されます。ワークスペースを作成する場合は、次の手順を実行する必要があります:

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

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

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

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

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

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

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

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

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

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

イシュー414384で、この動作を変更することが提案されています。

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

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

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

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

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

複数の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は認識されません。

検証ルール

  • schemaVersionは2.2.0である必要があります。
  • devfileには、少なくとも1つのコンポーネントが必要です。
  • Devfileのサイズは3MBを超えてはなりません。
  • componentsの場合:
    • 名前をgl-で始めることはできません。
    • containerとvolumeのみがサポートされています。
  • commandsの場合:
    • gl-の場合、IDをで始めることはできません。
    • execおよびapplyコマンドタイプのみがサポートされています。
    • execコマンドの場合、次のオプションのみがサポートされています：commandLine、component、label、およびhotReloadCapable。
    • hotReloadCapableがexecコマンドに指定されている場合、falseに設定する必要があります。
  • eventsの場合:
    • 名前をgl-で始めることはできません。
    • preStartとpostStartのみがサポートされています。
    • Devfile標準では、postStartイベントにリンクできるのはexecコマンドのみです。Applyコマンドが必要な場合は、preStartイベントを使用する必要があります。
  • parent、projects、starterProjectsはサポートされていません。
  • variablesの場合、キーをgl-、gl_、GL-、またはGL_で始めることはできません。
  • attributesの場合:
    • pod-overridesは、ルートレベルまたはcomponentsで設定しないでください。
    • container-overridesはcomponentsで設定しないでください。

containerコンポーネントタイプ

containerコンポーネントタイプを使用して、コンテナイメージをワークスペースの実行環境として定義します。ベースイメージ、依存関係、およびその他の設定を指定できます。

containerコンポーネントタイプは、次のスキーマプロパティのみをサポートします:

プロパティ説明
image 1ワークスペースに使用するコンテナイメージの名前。
memoryRequestコンテナが使用できるメモリの最小量。
memoryLimitコンテナが使用できるメモリの最大量。
cpuRequestコンテナが使用できるCPUの最小量。
cpuLimitコンテナが使用できるCPUの最大量。
envコンテナで使用する環境変数。名前をgl-で始めることはできません。
endpointsコンテナから公開するポートマッピング。名前をgl-で始めることはできません。
volumeMountsコンテナにマウントするストレージボリューム。
overrideCommandキープアライブコマンドでコンテナエントリポイントをオーバーライドします。デフォルトはコンポーネントタイプによって異なります。

Footnotes（脚注）:

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

overrideCommand属性

overrideCommand属性は、ワークスペースがコンテナエントリポイントをどのように処理するかを制御するブール値です。この属性は、コンテナの元のエントリポイントを保持するか、キープアライブコマンドで置き換えるかを決定します。

overrideCommandのデフォルト値は、コンポーネントタイプによって異なります:

  • 属性gl/inject-editor: trueを持つmainコンポーネント: 指定されていない場合、trueがデフォルトになります。
  • 他のすべてのコンポーネント: 指定されていない場合、falseがデフォルトになります。

trueの場合、コンテナを実行状態に保つために、コンテナエントリポイントはtail -f /dev/nullに置き換えられます。falseの場合、コンテナは、devfileコンポーネントcommand/argsまたはビルドされたコンテナイメージのEntrypoint/Cmdのいずれかを使用します。

次の表に、overrideCommandがコンテナの動作にどのように影響するかを示します。明確にするために、次の用語が表で使用されています:

  • Devfileコンポーネント: Devfileコンポーネントエントリのcommandおよびargsプロパティ。
  • コンテナイメージ: OCIコンテナイメージのEntrypointおよびCmdフィールド。
overrideCommandDevfileコンポーネントコンテナイメージ。結果:
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)。1

Footnotes（脚注）:

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

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

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

このタイプのイベントを使用して、次の操作を行います:

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

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

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

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

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

  • 属性gl/inject-editor: trueを持つmainコンポーネント: コマンドはプロジェクトディレクトリ (/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スクリプトの進捗状況を確認するには:

  1. ワークスペースでターミナルを開きます。

  2. ワークスペースログディレクトリに移動します:

    cd /tmp/workspace-logs/

  3. 出力ログを表示して、コマンドの結果を確認します:

    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
    container:
      image: mysql
      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がカスタムイメージを適切に初期化して接続できるようにするには、必要な設定コマンドをbase image 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 Workflow拡張機能がデフォルトで設定されています。

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

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

  • ステータス: ベータ

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

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

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

ワークスペースを作成すると、write_repositoryとapiの権限を持つパーソナルアクセストークンを取得します。このトークンを使用して、ワークスペースの起動時に、最初にプロジェクトのクローンを作成したり、VS Code用GitLab Workflow拡張機能を設定したりします。

ワークスペースで実行する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イベント、開発ツール、およびその他のワークスペースコンポーネントに関するイシューのトラブルシューティングに役立ちます。詳細については、Debug postStartイベントを参照してください。

利用可能なログファイル

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

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

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

シャロークローン

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

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