히스토리

• GitLab 16.0에서 기능 플래그 remote_development_feature_flag가 GitLab.com 및 GitLab Self-Managed에서 활성화되었습니다.
• GitLab 16.7에서 일반적으로 사용 가능하게 되었습니다. 기능 플래그 remote_development_feature_flag가 제거되었습니다.

워크스페이스는 GitLab에서 코드를 위한 가상 샌드박스 환경입니다. 워크스페이스를 사용하여 GitLab 프로젝트를 위한 격리된 개발 환경을 만들고 관리할 수 있습니다. 이러한 환경은 서로 다른 프로젝트가 서로 간섭하지 않도록 합니다.

각 워크스페이스에는 각 프로젝트의 특정 요구 사항에 맞게 사용자 정의할 수 있는 자체 종속성, 라이브러리 및 도구 세트가 포함되어 있습니다.

워크스페이스는 최대 약 1 달력 연도, 8760 시간 동안 존재할 수 있습니다. 이후 자동으로 종료됩니다.

클릭 스루 데모는 GitLab 워크스페이스를 참조하십시오.

워크스페이스 및 프로젝트#

워크스페이스는 프로젝트 범위입니다. 워크스페이스를 만들 때:

• 특정 프로젝트에 워크스페이스를 할당합니다.
• devfile이 있는 프로젝트를 선택합니다.

워크스페이스는 현재 사용자 권한으로 정의된 액세스 수준으로 GitLab API와 상호 작용할 수 있습니다. 실행 중인 워크스페이스는 나중에 사용자 권한이 취소되더라도 사용자가 액세스할 수 있습니다.

프로젝트에서 워크스페이스 관리#

히스토리

• GitLab 16.2에서 도입되었습니다.

프로젝트에서 워크스페이스를 관리하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 오른쪽 상단에서 Code를 선택합니다.
3. 드롭다운 목록에서 Your workspaces 아래에서:
   • 기존 워크스페이스를 다시 시작, 중지 또는 종료할 수 있습니다.
   • 새 워크스페이스를 만들 수 있습니다.

워크스페이스와 관련된 리소스 삭제#

워크스페이스를 종료하면 워크스페이스와 관련된 모든 리소스를 삭제합니다. 실행 중인 워크스페이스와 관련된 프로젝트, agentk, 사용자 또는 토큰을 삭제하면:

• 워크스페이스가 사용자 인터페이스에서 삭제됩니다.
• Kubernetes 클러스터에서 실행 중인 워크스페이스 리소스가 고아가 되며 자동으로 삭제되지 않습니다.

고아 리소스를 정리하려면 관리자가 Kubernetes에서 수동으로 워크스페이스를 삭제해야 합니다.

에픽 11452는 이 동작을 변경하는 것을 제안합니다.

에이전트 수준에서 워크스페이스 관리#

히스토리

• GitLab 16.8에서 도입되었습니다.

agentk와 관련된 모든 워크스페이스를 관리하려면:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
3. 원격 개발을 위해 구성된 에이전트를 선택합니다.
4. Workspaces 탭을 선택합니다.
5. 목록에서 기존 워크스페이스를 다시 시작, 중지 또는 종료할 수 있습니다.

실행 중인 워크스페이스에서 에이전트 식별#

여러 agentk 설치를 포함하는 배포에서 실행 중인 워크스페이스에서 에이전트를 식별할 수 있습니다.

실행 중인 워크스페이스와 관련된 에이전트를 식별하려면 다음 GraphQL 엔드포인트 중 하나를 사용합니다:

• agent-id: 에이전트가 속한 프로젝트를 반환합니다.
• Query.workspaces: 다음을 반환합니다:
  • 워크스페이스와 관련된 클러스터 에이전트.
  • 에이전트가 속한 프로젝트.

Devfile#

워크스페이스에는 devfile에 대한 기본 지원이 있습니다. Devfile은 GitLab 프로젝트에 필요한 도구, 언어, 런타임 및 기타 구성 요소를 지정하여 개발 환경을 정의하는 파일입니다. 이를 사용하여 정의된 사양으로 개발 환경을 자동으로 구성합니다. 사용하는 기계 또는 플랫폼에 관계없이 일관되고 재현 가능한 개발 환경을 만듭니다.

워크스페이스는 GitLab 기본 devfile과 사용자 정의 devfile을 모두 지원합니다.

GitLab 기본 devfile#

히스토리

• GitLab 17.8에서 Go와 함께 도입되었습니다.
• GitLab 17.9에서 Node, Ruby 및 Rust에 대한 지원이 추가되었습니다.
• GitLab 18.0에서 Python, PHP, Java 및 GCC에 대한 지원이 추가되었습니다.

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

유효성 검사 규칙#

• devfile 크기는 3MB를 초과해서는 안 됩니다.

container 컴포넌트 유형#

container 컴포넌트 유형을 사용하여 컨테이너 이미지를 워크스페이스의 실행 환경으로 정의합니다. 기본 이미지, 종속성 및 기타 설정을 지정할 수 있습니다.

container 컴포넌트 유형은 다음 스키마 속성만 지원합니다:

각주:

1. image 속성에 대한 사용자 정의 컨테이너 이미지를 만들 때 워크스페이스 기본 이미지를 기반으로 사용할 수 있습니다. SSH 액세스, 사용자 권한 및 워크스페이스 호환성을 위한 중요한 구성이 포함됩니다. 기본 이미지를 사용하지 않기로 선택한 경우 사용자 정의 이미지가 모든 워크스페이스 요구 사항을 충족하는지 확인합니다.

overrideCommand 속성#

overrideCommand 속성은 워크스페이스가 컨테이너 엔트리포인트를 처리하는 방법을 제어하는 부울입니다. 이 속성은 컨테이너의 원래 엔트리포인트가 보존되는지 또는 keep-alive 명령으로 교체되는지 결정합니다.

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 이벤트를 구성하는 방법을 보여주는 예는 구성 예시를 참조하십시오.

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 스크립트의 진행 상황을 확인하려면:

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

다른 예는 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 18.3에서 도입되었습니다.

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

워크스페이스 애드온#

히스토리

• GitLab 17.2에서 도입되었습니다.

GitLab for VS Code 확장이 기본적으로 워크스페이스에서 구성됩니다.

이 확장을 사용하면 이슈를 보고, 병합 요청을 만들고, CI/CD 파이프라인을 관리할 수 있습니다. 이 확장은 GitLab Duo Code Suggestions 및 GitLab Duo Chat과 같은 AI 기능도 지원합니다.

Extension Marketplace#

히스토리

• GitLab 16.9에서 allow_extensions_marketplace_in_workspace라는 플래그와 함께 베타로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.6에서 기능 플래그 allow_extensions_marketplace_in_workspace가 제거되었습니다.

VS Code Extension Marketplace는 Web IDE의 기능을 향상시키는 확장에 대한 액세스를 제공합니다. 기본적으로 GitLab Web IDE는 Open VSX Registry에 연결됩니다.

자세한 내용은 VS Code Extension Marketplace 구성을 참조하십시오.

개인 액세스 토큰#

히스토리

• GitLab 16.4에서 도입되었습니다.
• GitLab 17.2에서 api 권한이 추가되었습니다.

워크스페이스를 만들면 write_repository 및 api 권한으로 365일 후 만료되는 개인 액세스 토큰을 받습니다. 이 토큰은 워크스페이스를 시작하는 동안 프로젝트를 처음 복제하고 GitLab for VS Code 확장을 구성하는 데 사용됩니다.

워크스페이스에서 수행하는 Git 작업은 이 토큰을 인증 및 권한 부여에 사용합니다. 워크스페이스를 종료하면 토큰이 취소됩니다.

워크스페이스에서 Git 인증을 위해 GIT_CONFIG_COUNT, GIT_CONFIG_KEY_n 및 GIT_CONFIG_VALUE_n 환경 변수를 사용합니다. 이러한 변수는 워크스페이스 컨테이너에서 Git 2.31 이상이 필요합니다.

클러스터에서의 Pod 상호 작용#

워크스페이스는 Kubernetes 클러스터에서 Pod로 실행됩니다. GitLab은 Pod가 서로 상호 작용하는 방식에 제한을 두지 않습니다.

이 요구 사항으로 인해 클러스터의 다른 컨테이너에서 이 기능을 격리하는 것을 고려합니다.

네트워크 액세스 및 워크스페이스 권한 부여#

GitLab은 API에 대한 제어가 없기 때문에 Kubernetes 제어 평면에 대한 네트워크 액세스를 제한하는 것은 클라이언트의 책임입니다.

워크스페이스를 만든 사람만 워크스페이스와 해당 워크스페이스에서 노출된 엔드포인트에 액세스할 수 있습니다. 워크스페이스 생성자는 OAuth로 사용자 인증 후에만 워크스페이스에 액세스할 수 있습니다.

컴퓨팅 리소스 및 볼륨 스토리지#

워크스페이스를 중지하면 GitLab이 해당 워크스페이스의 컴퓨팅 리소스를 0으로 축소합니다. 그러나 워크스페이스에 프로비저닝된 볼륨은 여전히 존재합니다.

프로비저닝된 볼륨을 삭제하려면 워크스페이스를 종료해야 합니다.

자동 워크스페이스 중지 및 종료#

히스토리

• GitLab 17.6에서 도입되었습니다.

기본적으로 워크스페이스는 자동으로:

• 워크스페이스가 마지막으로 시작되거나 다시 시작된 후 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 이벤트 디버그를 참조하십시오.

사용 가능한 로그 파일#

로그 디렉토리에는 다음 로그 파일이 포함됩니다:

얕은 복제#

히스토리

• GitLab 18.2에서 workspaces_shallow_clone_project라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.3에서 GitLab.com에서 활성화되었습니다.
• GitLab 18.4에서 일반적으로 사용 가능하게 되었습니다. 기능 플래그 workspaces_shallow_clone_project가 제거되었습니다.

워크스페이스를 만들면 GitLab은 성능을 향상시키기 위해 얕은 복제를 사용합니다. 얕은 복제는 전체 Git 기록 대신 최신 커밋 기록만 다운로드하여 대규모 저장소의 초기 복제 시간을 크게 줄입니다.

워크스페이스가 시작된 후 Git은 백그라운드에서 얕은 복제를 전체 복제로 변환합니다. 이 프로세스는 투명하며 개발 워크플로에 영향을 미치지 않습니다.

관련 주제#

• 워크스페이스 만들기
• 워크스페이스 설정
• 워크스페이스 문제 해결
• GitLab Duo Code Suggestions
• GitLab Duo 에이전틱 채팅
• GraphQL API 참조
• Devfile 문서
• 임의 사용자 ID에 관한 OpenShift 문서