히스토리

• GitLab 18.0에서 일반 제공됩니다. 기능 플래그 vscode_web_ide가 제거됐습니다.

Web IDE는 GitLab UI에서 직접 여러 파일을 편집하고, 변경 사항을 스테이징하고, 커밋을 만들 수 있는 고급 편집기입니다. Web 편집기와 달리 Web IDE는 소스 컨트롤 관리를 갖춘 완전한 개발 환경을 제공합니다.

Web IDE의 GitLab Flavored Markdown 미리 보기 지원은 에픽 15810에서 제안됐습니다.

Web IDE 열기#

여러 가지 방법으로 Web IDE에 접근할 수 있습니다.

키보드 단축키로 열기#

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. . 키보드 단축키를 사용합니다.

디렉터리에서 열기#

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 디렉터리로 이동합니다.
3. Code > Open in Web IDE를 선택합니다.

파일에서 열기#

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 파일로 이동합니다.
3. Edit > Open in Web IDE를 선택합니다.

머지 리퀘스트에서 열기#

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 머지 리퀘스트로 이동합니다.
3. 오른쪽 위에서 Code > Open in Web IDE를 선택합니다.

Web IDE는 새 파일과 수정된 파일을 별도 탭에서 열고, 변경 사항을 나란히 표시합니다. 로드 시간을 줄이기 위해 변경된 줄이 가장 많은 파일 10 개만 자동으로 열립니다.

Web IDE 인터페이스는 왼쪽 사이드바 Explorer 뷰에서 새 파일이나 수정된 파일 옆에 머지 리퀘스트 아이콘([merge-request])을 표시합니다. 파일의 변경 사항을 보려면 파일을 오른쪽 버튼으로 클릭하고 Compare with merge request base를 선택합니다.

파일 관리#

Web IDE로 여러 파일을 열고, 편집하고, 업로드할 수 있습니다.

파일 열기#

Web IDE에서 이름으로 파일을 열려면 다음과 같이 합니다.

1. Command+P를 누릅니다.
2. 검색 상자에 파일 이름을 입력합니다.

열린 파일 검색#

Web IDE에서 열린 파일 전체를 검색하려면 다음과 같이 합니다.

1. Shift+Command+F를 누릅니다.
2. 검색 상자에 검색어를 입력합니다.

파일 업로드#

Web IDE에서 파일을 업로드하려면 다음과 같이 합니다.

1. Web IDE 왼쪽에서 Explorer ([documents])를 선택하거나 Shift+Command+E를 누릅니다.

2. 파일을 업로드할 디렉터리로 이동합니다. 새 디렉터리를 만들려면 다음과 같이 합니다.

   • Explorer 뷰의 오른쪽 위에서 New Folder ([folder-new])를 선택합니다.

3. 디렉터리를 오른쪽 버튼으로 클릭하고 Upload를 선택합니다.

4. 업로드할 파일을 선택합니다.

여러 파일을 한 번에 업로드할 수 있습니다. 파일이 업로드되고 리포지터리에 자동으로 추가됩니다.

커밋하지 않은 변경 사항 복원#

Web IDE에서 편집하는 파일은 직접 저장하지 않아도 됩니다. Web IDE가 수정한 파일을 스테이징하므로 변경 사항을 커밋할 수 있습니다. 커밋하지 않은 변경 사항은 브라우저의 로컬 스토리지에 저장됩니다. 브라우저 탭을 닫거나 Web IDE를 새로 고쳐도 유지됩니다.

커밋하지 않은 변경 사항을 사용할 수 없다면, 로컬 히스토리에서 변경 사항을 복원할 수 있습니다. Web IDE에서 커밋하지 않은 변경 사항을 복원하려면 다음과 같이 합니다.

1. Shift+Command+P를 누릅니다.
2. 검색 상자에 Local History: Find Entry to Restore를 입력합니다.
3. 커밋하지 않은 변경 사항이 있는 파일을 선택합니다.

소스 컨트롤 사용#

소스 컨트롤로 수정된 파일을 보고, 브랜치를 만들고 전환하며, 변경 사항을 커밋하고, 머지 리퀘스트를 만들 수 있습니다.

수정된 파일 보기#

Web IDE에서 수정한 파일 목록을 보려면 다음과 같이 합니다.

• Web IDE 왼쪽에서 Source Control ([branch])을 선택하거나 Control+Shift+G를 누릅니다.

CHANGES, STAGED CHANGES, MERGE CHANGES가 표시됩니다. 자세한 내용은 VS Code 문서를 참고합니다.

브랜치 전환#

Web IDE는 기본적으로 현재 브랜치를 사용합니다. Web IDE에서 브랜치를 전환하려면 다음과 같이 합니다.

1. 아래쪽 상태 바 왼쪽에서 현재 브랜치 이름을 선택합니다.
2. 기존 브랜치를 입력하거나 선택합니다.

브랜치 생성#

Web IDE에서 현재 브랜치를 기준으로 브랜치를 만들려면 다음과 같이 합니다.

1. 아래쪽 상태 바 왼쪽에서 현재 브랜치 이름을 선택합니다.
2. 드롭다운 목록에서 Create new branch를 선택합니다.
3. 새 브랜치 이름을 입력합니다.

Web IDE는 체크아웃한 브랜치를 기준으로 브랜치를 만듭니다. 다른 기준으로 브랜치를 만들려면 다음 단계를 따를 수도 있습니다.

1. Web IDE 왼쪽에서 Source Control ([branch])을 선택하거나 Control+Shift+G를 누릅니다.
2. Source Control 패널 오른쪽 위에서 줄임표 메뉴([ellipsis_h])를 선택합니다.
3. 드롭다운 목록에서 Branch > **Create branch from...**를 선택합니다.
4. 드롭다운 목록에서 기준으로 사용할 브랜치를 선택합니다.

리포지터리에 쓰기 권한이 없으면 Create new branch가 표시되지 않습니다.

브랜치 삭제#

1. Web IDE 왼쪽에서 Source Control ([branch])을 선택하거나 Control+Shift+G를 누릅니다.
2. Source Control 패널 오른쪽 위에서 줄임표 메뉴([ellipsis_h])를 선택합니다.
3. 드롭다운 목록에서 Branch > Delete branch를 선택합니다.
4. 드롭다운 목록에서 삭제할 브랜치를 선택합니다.

Web IDE에서는 보호된 브랜치를 삭제할 수 없습니다.

변경 사항 커밋#

Web IDE에서 변경 사항을 커밋하려면 다음과 같이 합니다.

1. Web IDE 왼쪽에서 Source Control ([branch])을 선택하거나 Control+Shift+G를 누릅니다.
2. 커밋 메시지를 입력합니다.
3. 다음 커밋 옵션 중 하나를 선택합니다.
   • Commit to current branch - 현재 브랜치에 변경 사항을 커밋합니다
   • Create a new branch - 새 브랜치를 만들고 변경 사항을 커밋합니다
   • Commit and force push - 원격 브랜치로 변경 사항을 강제 푸시합니다
   • Amend commit and force push - 마지막 커밋을 수정하고 강제 푸시합니다

커밋 후 강제 푸시#

변경 사항을 커밋하고 강제 푸시하려면 다음과 같이 합니다.

1. 작업 버튼 메뉴를 선택하거나 줄임표([ellipsis_h])를 선택합니다.
2. Commit and force push를 선택합니다.

커밋 수정 후 강제 푸시#

마지막 커밋을 수정하고 강제 푸시하려면 다음과 같이 합니다.

1. 작업 버튼 메뉴를 선택하거나 줄임표([ellipsis_h])를 선택합니다.
2. Amend commit and force push를 선택합니다.

이렇게 하면 마지막 커밋이 업데이트되고 원격 리포지터리로 강제 푸시됩니다. 새 커밋을 만들지 않고 최근 커밋을 수정할 때 사용합니다.

머지 리퀘스트 생성#

Web IDE에서 머지 리퀘스트를 만들려면 다음과 같이 합니다.

1. 변경 사항을 커밋합니다.
2. 오른쪽 아래에 나타나는 알림에서 Create MR을 선택합니다.

자세한 내용은 놓친 알림 보기를 참고합니다.

Web IDE 사용자 지정#

키보드 단축키, 테마, 설정, 동기화에 대한 선호에 맞게 Web IDE를 사용자 지정합니다.

Command Palette 사용#

Command Palette로 여러 명령에 접근할 수 있습니다. Web IDE에서 Command Palette를 열고 명령을 실행하려면 다음과 같이 합니다.

1. Shift+Command+P를 누릅니다.
2. 명령을 입력하거나 선택합니다.

설정 편집#

설정 편집기로 사용자 설정과 Web IDE 워크스페이스 설정을 보고 편집할 수 있습니다. Web IDE에서 설정 편집기를 열려면 다음과 같이 합니다.

• 상단 메뉴 바에서 File > Preferences > Settings를 선택하거나 Command+,를 누릅니다.

설정 편집기에서 변경할 설정을 검색할 수 있습니다.

키보드 단축키 편집#

키보드 단축키 편집기로 사용할 수 있는 모든 명령의 기본 키 바인딩을 보고 변경할 수 있습니다. Web IDE에서 키보드 단축키 편집기를 열려면 다음과 같이 합니다.

• 상단 메뉴 바에서 File > Preferences > Keyboard Shortcuts를 선택하거나 Command+K를 누른 다음 Command+S를 누릅니다.

키보드 단축키 편집기에서 다음을 검색할 수 있습니다.

• 변경할 키 바인딩
• 키 바인딩을 추가하거나 제거할 명령

키 바인딩은 키보드 레이아웃을 기준으로 합니다. 키보드 레이아웃을 변경하면 기존 키 바인딩이 자동으로 업데이트됩니다.

색 테마 변경#

Web IDE의 색 테마를 여러 가지 중에서 선택할 수 있습니다. 기본 테마는 GitLab Dark 입니다.

Web IDE에서 색 테마를 변경하려면 다음과 같이 합니다.

1. 상단 메뉴 바에서 File > Preferences > Theme > Color Theme를 선택하거나 Command+K를 누른 다음 Command+T를 누릅니다.
2. 드롭다운 목록에서 화살표 키로 테마를 미리 봅니다.
3. 테마를 선택합니다.

Web IDE는 활성 색 테마를 사용자 설정에 저장합니다.

동기화 설정 구성#

Web IDE에서 동기화 설정을 구성하려면 다음과 같이 합니다.

1. Shift+Command+P를 누릅니다.
2. 검색 상자에 Settings Sync: Configure를 입력합니다.
3. 다음 항목의 체크박스를 선택하거나 선택 해제합니다.
   • Settings
   • Keyboard shortcuts
   • User snippets
   • User tasks
   • UI state
   • Extensions
   • Profiles

이 설정은 여러 Web IDE 인스턴스에 자동으로 동기화됩니다. 사용자 프로필은 동기화할 수 없고, 동기화된 설정을 이전 버전으로 되돌릴 수도 없습니다.

놓친 알림 보기#

Web IDE에서 작업을 수행하면 오른쪽 아래에 알림이 나타납니다. 놓쳤을 수 있는 알림을 보려면 다음과 같이 합니다.

1. 아래쪽 상태 바 오른쪽에서 종 아이콘([notifications])을 선택해 알림 목록을 확인합니다.
2. 보려는 알림을 선택합니다.

확장 관리#

히스토리

• GitLab 17.0에서 web_ide_oauth와 web_ide_extensions_marketplace라는 기능 플래그와 함께 베타로 도입됐습니다. 기본적으로 비활성화됩니다.
• web_ide_oauth는 GitLab 17.4에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화됐습니다.
• web_ide_extensions_marketplace는 GitLab 17.4에서 GitLab.com에서 활성화됐습니다.
• web_ide_oauth는 GitLab 17.5에서 제거됐습니다.
• GitLab 17.10에서 vscode_extension_marketplace_settings 기능 플래그가 도입됐습니다. 기본적으로 비활성화됩니다.
• web_ide_extensions_marketplace는 GitLab 17.11에서 GitLab Self-Managed에서 활성화됐고, vscode_extension_marketplace_settings는 GitLab 17.11에서 GitLab.com과 GitLab Self-Managed에서 활성화됐습니다.
• GitLab 18.1에서 일반 제공됩니다. 기능 플래그 web_ide_extensions_marketplace와 vscode_extension_marketplace_settings가 제거됐습니다.

VS Code Extension Marketplace는 Web IDE의 기능을 강화하는 확장에 접근할 수 있게 합니다. 기본적으로 GitLab Web IDE는 Open VSX Registry에 연결됩니다.

사전 요구 사항:

• 사용자 환경 설정에서 Extension Marketplace를 통합해야 합니다.
• GitLab Self-Managed와 GitLab Dedicated에서는 GitLab 관리자가 확장 레지스트리를 활성화해야 합니다.
• 엔터프라이즈 사용자의 경우 그룹 Owner가 엔터프라이즈 사용자용 Extension Marketplace를 활성화해야 합니다.

확장 설치#

Web IDE에서 확장을 설치하려면 다음과 같이 합니다.

1. 상단 메뉴 바에서 View > Extensions를 선택하거나 Command+Shift+X를 누릅니다.
2. 검색 상자에 확장 이름을 입력합니다.
3. 설치할 확장을 선택합니다.
4. Install을 선택합니다.

확장 제거#

Web IDE에서 확장을 제거하려면 다음과 같이 합니다.

1. 상단 메뉴 바에서 View > Extensions를 선택하거나 Command+Shift+X를 누릅니다.
2. 설치된 확장 목록에서 제거할 확장을 선택합니다.
3. Uninstall을 선택합니다.

확장 설정#

Web IDE 확장은 프로젝트에서 동작하려면 추가 구성이 필요할 수 있습니다.

Vim 키 바인딩 사용#

Vim 키 바인딩을 사용하면 Vim 텍스트 편집기의 키보드 단축키로 텍스트를 이동하고 편집할 수 있습니다. Extension Marketplace로 Web IDE에 Vim 키 바인딩을 추가할 수 있습니다.

Vim 키 바인딩을 활성화하려면 Vim 확장을 설치합니다. 자세한 내용은 확장 설치를 참고합니다.

AsciiDoc 지원#

AsciiDoc 확장은 Web IDE에서 AsciiDoc 파일에 대한 실시간 미리 보기, 구문 강조, 스니펫을 제공합니다. Web IDE에서 AsciiDoc 마크업 미리 보기를 사용하려면 AsciiDoc 확장을 설치해야 합니다. 자세한 내용은 확장 설치를 참고합니다.

관련 주제#

• Web IDE의 GitLab Duo Non-Agentic Chat

문제 해결#

Web IDE를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

입력 시 문자 오프셋#

Web IDE에서 입력할 때 네 문자 오프셋이 발생할 수 있습니다. 해결 방법은 다음과 같습니다.

1. 상단 메뉴 바에서 File > Preferences > Settings를 선택하거나 Command+,를 누릅니다.
2. 오른쪽 위에서 **Open Settings (JSON)**을 선택합니다.
3. settings.json 파일에 "editor.disableMonospaceOptimizations": true를 추가하거나 "editor.fontFamily" 설정을 변경합니다.

자세한 내용은 VS Code 이슈 80170을 참고합니다.

OAuth 콜백 URL 업데이트#

사전 요구 사항:

• 인스턴스에 대한 관리자 접근 권한이 있어야 합니다.

Web IDE는 인증에 인스턴스 전체 OAuth 애플리케이션을 사용합니다. OAuth 콜백 URL 이 잘못 구성되면 다음 메시지가 표시되는 Cannot open Web IDE 오류 페이지가 나타날 수 있습니다.

The URL you're using to access the Web IDE and the configured OAuth callback URL do not match. This issue often occurs when you're using a proxy.

이 문제를 해결하려면 GitLab 인스턴스에 접근할 때 사용하는 URL과 일치하도록 OAuth 콜백 URL을 업데이트해야 합니다.

사전 요구 사항:

• 관리자 접근 권한.

OAuth 콜백 URL을 업데이트하려면 다음과 같이 합니다.

1. 오른쪽 위에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Applications를 선택합니다.
3. GitLab Web IDE에서 Edit를 선택합니다.
4. OAuth 콜백 URL을 입력합니다. 여러 URL을 줄바꿈으로 구분해 입력할 수 있습니다.

액세스 토큰 수명은 5 분 미만일 수 없음#

액세스 토큰 수명이 5 분 미만일 수 없다는 오류 메시지가 나타날 수 있습니다.

이 오류는 GitLab 인스턴스의 액세스 토큰 만료 시간이 5 분 미만으로 구성돼 있을 때 발생합니다. Web IDE가 제대로 동작하려면 액세스 토큰 수명이 최소 5 분이어야 합니다.

이 문제를 해결하려면 인스턴스 구성에서 액세스 토큰 수명을 최소 5 분으로 늘립니다. 액세스 토큰 만료를 구성하는 방법에 관한 자세한 내용은 액세스 토큰 만료를 참고합니다.

Workhorse 의존성#

GitLab Self-Managed에서는 Workhorse를 설치하고 GitLab Rails 서버 앞에서 실행해야 합니다. 그렇지 않으면 Web IDE를 열 때나 Markdown 미리 보기 같은 특정 기능을 사용할 때 문제가 발생할 수 있습니다.

보안을 위해 Web IDE의 일부는 별도 오리진에서 실행해야 합니다. 이 방식을 지원하기 위해 Web IDE는 Workhorse를 사용해 Web IDE 에셋으로 오가는 요청을 적절히 라우팅합니다. Web IDE 에셋은 정적 프론트엔드 에셋이므로, 이 작업에 Rails에 의존하는 것은 불필요한 오버헤드입니다.

CORS 문제#

Web IDE가 GitLab Self-Managed 인스턴스에서 제대로 동작하려면 특정 CORS(Cross-Origin Resource Sharing) 구성이 필요합니다. GitLab API 엔드포인트(/api/*)는 Web IDE를 지원하기 위해 다음 HTTP 응답 헤더를 포함해야 합니다.

Web IDE는 확장 호스트 도메인의 서브도메인 부분을 동적으로 생성합니다. CORS 헤더가 다음 규칙을 충족하는지 확인합니다.

• 패턴 일치: https://*.cdn.web-ide.gitlab-static.net 패턴과 일치하는 오리진을 허용합니다.
• 검증: 서브도메인에 영숫자만 포함되고 52 자 이하인지 확인합니다.
• 보안: Access-Control-Allow-Origin에 와일드카드(*)를 절대 사용하지 않습니다. 보안 위험이 있습니다.

GitLab 인스턴스의 기본 CORS 구성은 이 요구 사항을 충족합니다. GitLab Self-Managed 인스턴스가 HTTP 리버스 프록시 서버 뒤에 있거나 커스텀 CORS 정책 구성을 사용하면 문제가 발생할 수 있습니다.

오프라인 환경#

Web IDE는 기본 확장 호스트 도메인(https://*.cdn.web-ide.gitlab-static.net)에 연결할 수 없을 때 기능이 제한됩니다. 오프라인 환경에서는 GitLab 관리자가 해결 방법으로 커스텀 확장 호스트 도메인을 설정할 수 있습니다.

문제 신고#

문제를 신고하려면 다음 정보를 담아 새 이슈를 생성합니다.

• 오류 메시지
• 전체 오류 세부 정보
• 문제가 발생하는 빈도
• 문제를 재현하는 단계

유료 티어를 사용한다면 지원팀에 문의해 도움을 받을 수도 있습니다.