DevOps 실무자를 위한 GitLab Wiki 활용법

협업과 지식 관리 최적화

Fabbro

Software Engineer

2025년 1월 22일 · 약 16분

지금 GitLab으로 프로젝트를 관리하신다면, 이 글을 보고 GitLab Wiki를 시작해 보시면 어떨까요? Wiki는 GitLab 인스턴스 안에서 직접 문서를 만들고, 정리하며, 공유하는 도구입니다. 이는 프로젝트와 가까이 있으며, 프로젝트 활동을 쉽게 녹일 수 있는 문서이기도 하죠. Wiki를 잘 활용하면, 팀이 원활히 협업하고, 지식 관리를 최적화하는 데 도움이 됩니다. 이 글에서는 DevOps 실무자가 Wiki를 효과적으로 활용하는 방법을 소개하겠습니다.

GitLab Wiki 장점

GitLab Wiki는 프로젝트와 관련된 문서를 작성하고 관리하는 도구입니다. 이는 GitLab 프로젝트와 그룹 수준에서 모두 사용할 수 있고요. Markdown, RDoc, AsciiDoc, Org 등 여러 형식을 지원하죠. 이로써 정보를 보기 쉽게 표시합니다.

Wiki는 팀이 GitLab의 단일 플랫폼 안에서 애자일 계획 프로세스를 간소화하고, 협업을 강화하는 데 도움이 됩니다. 아울러 중요한 정보에 접근하고, 이를 최신 상태로 유지하는 데 유용하죠. 아래는 GitLab 프로덕트 매니저인 Matthew Macfarlane이 설명한 Wiki의 장점과 제 의견을 아우른 내용입니다.

중앙 집중식 정보 저장소

Wiki는 모든 지식을 저장하는 단일 진실 공급원으로 역할을 합니다. Wiki를 사용하면, 외부 솔루션을 찾기 위해 플랫폼을 떠나지 않고도 필요한 정보를 쉽게 찾을 수 있습니다.
정보 접근과 협업 편의성

Wiki로 문서를 작업할 때, GitLab의 이슈, Merge request(MR)에 쉽게 접근해 정보를 파악할 수 있습니다. 또 링크와 미리보기로 팀에서 편리하게 협업할 수 있습니다.
버전 제어

Wiki는 GitLab의 버전 제어 시스템에 따라 작동됩니다. 이는 모든 변경 사항을 추적하고, 필요하면 이전 버전을 복원할 수 있습니다. 이는 시간이 지나면서 문서의 무결성을 유지하는 데 도움이 됩니다.
템플릿

템플릿을 사용해 여러 페이지의 콘텐츠를 일관된 형식과 스타일로 유지할 수 있습니다. 이는 문서의 전문성과 가독성을 향상합니다. 템플릿은 재사용할 수 있어 문서 작성 시간을 줄여줍니다.

Wiki 단계별 활용 가이드

어떻게 하면 Wiki의 장점을 잘 활용할 수 있을까요? 지금부터 Wiki 사용법을 단계별로 실습하며, 효과적인 Wiki 활용 노하우를 소개하겠습니다.

Wiki 첫 페이지 생성

Wiki 활용의 첫걸음은 페이지 생성에서 시작합니다. 다음 순서대로 작업하세요.

GitLab Project 혹은 Group > Plan > Wiki 메뉴에 진입합니다.
Create your first page 버튼을 눌러 첫 페이지를 생성합니다.
Title, Path, Content, Commit message 항목에 내용을 입력합니다.
- Title: 문서 제목을 입력합니다. 문서 작성이 완료되면 오른쪽 사이드바에 표시됩니다.
- Path: 문서 경로를 입력합니다. /로 문서 위치를 구분합니다. 이는 기본적으로 문서 제목에 기반해 자동 입력됩니다. 아래 Generate page path from title 체크박스를 해제하면, 경로를 수동으로 바꿀 수 있습니다. 그러나 임의로 변경한 모든 경로를 다 기억하기 어려우므로 문서 제목에 기반한 경로를 유지하는 걸 추천합니다. 이 예시에서는 Wiki 페이지의 첫 번째 경로가 ‘home’으로 고정됐기에 첫 번째 페이지의 경로는 반드시 ‘home’으로 입력합니다.
- Content: 문서 내용을 입력합니다.
- Commit message: 커밋 메시지를 입력합니다.
작성을 완료하면, Create Page 버튼을 눌러 페이지를 생성합니다.

페이지 추가

Wiki에서 페이지를 추가하는 방법은 3가지입니다. 이 중 가장 편리한 방법을 찾아 활용하세요.

Wiki 페이지 오른쪽 상단의 케밥(세 개의 점으로 된 아이콘) 메뉴를 클릭한 다음, New page를 클릭합니다(경로 자동 입력 없음).
오른쪽 사이드바 페이지 메뉴에 마우스를 올리면 등장하는 + 버튼을 클릭합니다(경로 자동 입력).
문서 작성 시 링크 텍스트(용어 정리)의 URL에 미래에 추가할 페이지 경로를 입력합니다(경로 자동 입력).
1. 이렇게 작성한 링크 텍스트(용어 정리)를 클릭하면, 해당 경로의 페이지 생성 페이지로 이동합니다.
2. 새 페이지에서 경로(Path)를 입력할 때, 띄어 쓰려면 -를 입력하세요!

사이드바 활용

생성된 페이지로 이동하는 페이지 버튼은 Wiki 페이지 오른쪽 사이드바에 나열됩니다. 사이드바 구성과 맞춤형 설정 방법을 알아보겠습니다.

구성
1. /로 나눠진 경로(Path)의 깊이(depth)에 따라 페이지 버튼이 오른쪽 사이드바에 노출됩니다.
2. 사이드바에서는 페이지별 목차도 보여줍니다. heading1~6까지 나옵니다.
3. 사이드바에는 페이지 버튼이 최대 5000개 표시됩니다. 그 이상 보려면, View all pages를 클릭합니다.
맞춤형 설정
1. 사이드바 오른쪽 상단의 톱니바퀴 버튼을 클릭합니다.
2. Edit custom sidebar의 Content 칸에 링크 텍스트로 페이지 버튼을 직접 만듭니다. 이미지를 넣어 자유롭게 꾸며도 됩니다.
3. 사이드바를 맞춤형으로 설정하면, 기본으로 제공되는 사이드바의 페이지 버튼을 토글로 접을 수 있습니다.
4. 사이드바를 다시 수정하려면, 사이드바 오른쪽 상단의 톱니바퀴 버튼을 클릭합니다.
5. 맞춤형 설정을 해제하려면, 수정 페이지에서 Delete custom sidebar 버튼을 누릅니다.

변경 이력 조회

Wiki에서는 ‘History’ 기능으로 ‘누가, 언제, 어떻게 페이지를 변경했는지’ 파악할 수 있습니다. 여기서는 사이드바 오타 수정 이력을 History 기능으로 확인하겠습니다.

각 페이지에서 오른쪽 상단의 케밥 메뉴를 눌러 Page history에 진입합니다.
History 페이지에 버전별 커밋 메시지가 뜹니다. ‘누가(Author), 언제(Last updated), 어떤 내용(Diff)으로 수정했는지’ 나옵니다.
Diff를 누르면, 변경 사항을 자세히 볼 수 있습니다.
수정 이전 버전으로 되돌리려면 다음 두 가지 방법 중 하나를 실행합니다.
1. 이전 버전의 내용을 복사해 Wiki 페이지에서 직접 수정합니다.
2. Wiki도 저장소이므로, 저장소를 받아와서 수정합니다.
실습에서는 4-ⅱ 방법을 사용해 수정 이전 버전으로 복구하겠습니다.
1. Wiki 페이지 오른쪽 상단의 케밥 메뉴를 눌러 Clone repository를 클릭, git clone 합니다.
2. clone 받은 저장소 폴더로 이동해 에디터 또는 터미널에서 원치 않는 변경 사항을 revert 합니다.
3. main 브랜치에 push 합니다.
4. History 페이지에 돌아오면, 원치 않는 변경 사항을 revert한 이력이 업데이트된 걸 확인할 수 있습니다.

템플릿 생성

반복 사용하는 문서 양식은 Wiki에서 템플릿으로 만들면 효율적입니다. 이는 문서 일관성을 유지하고, 문서 작성 시간을 절약하는 데 도움이 됩니다. 아래는 템플릿 생성 방법입니다.

Wiki 페이지 오른쪽 상단의 케밥 메뉴를 눌러 템플릿 페이지에 진입합니다.
템플릿 페이지에서 다시 오른쪽 상단에 New template 버튼을 클릭해 템플릿 생성 페이지로 이동합니다.
템플릿 Title, Content, 커밋 메시지를 작성합니다. Create page 버튼을 누르면 템플릿이 생성됩니다.
템플릿을 사용하기 위해 ‘업데이트 노트’ 페이지를 만들었는데요. 이곳에 새 페이지를 추가하겠습니다. 새 페이지의 Template 항목에서 앞서 만든 템플릿을 선택합니다.
템플릿을 선택하자, Content가 ‘미리 정의했던 템플릿’ 형식으로 자동 변경됩니다.
아래는 위 템플릿을 활용해 작성한 문서 예시입니다.

GitLab 이슈, MR 접근

Wiki 위치에 따라 GitLab 이슈와 MR에 쉽게 접근할 수 있습니다. 방법은 간단합니다.

아래 예시는 Group에서 만든 Wiki인데요. 에디터 Content 칸에 #을 입력하면, Group을 포함한 모든 프로젝트의 이슈에 바로 접근할 수 있습니다.
에디터 Content 칸에 #을 입력하면 이슈가, !를 입력하면 MR이 나타납니다.
이렇게 작성된 링크에 마우스를 올리면 미리보기가 나옵니다.

에디터 사용 팁

이미지 입력
- 이미지를 입력할 때 이미지를 복사한 다음, 에디터에 plain text 모드로 붙여 넣으세요. 그게 더 깔끔하고, 위치를 조정하기도 쉽습니다. 크기를 조정하려면, rich text 모드로 변경해 마우스로 이미지 크기를 조정하는 게 더 편합니다.
1. 에디터에 복사한 이미지를 plain text 모드로 붙여 넣습니다.
2. 그다음, rich text 모드로 변경합니다.
3. 입력한 이미지를 드래그해 원하는 크기로 조절합니다.
다양한 도구 지원
- + 버튼을 클릭해 다양한 도구를 활용하세요. Details block을 누르면 details html 코드를 직접 삽입하지 않아도 됩니다. Create or edit diagram을 누르면 GitLab에서 바로 다이어그램을 작업할 수 있습니다. 또 Table of contents를 누르면 목차가 추가됩니다. 이밖에 여러 도구를 한번씩 클릭하며 기능을 확인하세요.