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

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

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

클릭 스루 데모는 GitLab 워크스페이스를 참고합니다.

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

워크스페이스는 프로젝트 범위로 지정됩니다. 워크스페이스를 만들 때 다음을 수행해야 합니다.

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

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

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

프로젝트에서 워크스페이스를 관리하려면 다음을 수행합니다.

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

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

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

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

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

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

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

agentk와 관련된 모든 워크스페이스를 관리하려면 다음을 수행합니다.

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

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

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

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

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

Devfile#

워크스페이스는 devfile을 기본으로 지원합니다. devfile은 GitLab 프로젝트에 필요한 도구, 언어, 런타임 및 기타 컴포넌트를 지정하여 개발 환경을 정의하는 파일입니다. devfile을 사용하면 정의한 사양에 맞게 개발 환경을 자동으로 구성할 수 있습니다. devfile은 사용하는 머신이나 플랫폼과 무관하게 일관되고 재현 가능한 개발 환경을 만듭니다.

워크스페이스는 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 크기는 3 MB를 초과할 수 없습니다.

container 컴포넌트 유형#

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

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

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 필드.

사용자 정의 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 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 문서

Footnotes

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

2. 워크스페이스를 만들 때는 비공개 또는 내부 레지스트리 등에 있는 컨테이너 이미지의 세부 정보에 액세스할 수 없습니다. overrideCommand가 false이고 Devfile이 command 또는 args를 지정하지 않으면 GitLab은 컨테이너 이미지를 검증하지 않고 필수 Entrypoint 또는 Cmd 필드도 확인하지 않습니다. Devfile이나 컨테이너 중 한쪽이 이러한 필드를 지정하도록 해야 하며, 그러지 않으면 컨테이너가 조기에 종료되고 워크스페이스가 시작되지 않습니다. ↩