---
title: "DevOps 실무자를 위한 GitLab Wiki 활용법"
description: "GitLab Wiki는 GitLab 인스턴스 안에서 직접 문서를 만들고, 정리하며, 공유하는 도구입니다. 이는 프로젝트 활동을 쉽게 기록하는 문서이기도 하죠. Wiki를 잘 활용하면 기술팀이 원활히 협업하고, 지식 관리를 최적화하는 데 도움이 됩니다. 이 글은 DevOps 실무자가 Wiki를 효과적으로 활용하는 방법을 다뤘습니다."
url: https://insight.infograb.net/blog/2025/01/22/gitlab-wiki/
source: content/generated/blog/2025-01-22-gitlab-wiki.md
---

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

## **GitLab Wiki 장점**

![](/img/blog/2025-01-22-gitlab-wiki-inline-01.png)

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

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

1. **중앙 집중식 정보 저장소**

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

2. **정보 접근과 협업 편의성**

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

3. **버전 제어**

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

4. **템플릿**

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

## Wiki 단계별 활용 가이드

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

### Wiki 첫 페이지 생성

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

1. **GitLab Project 혹은 Group > Plan > Wiki** 메뉴에 진입합니다.
2. **Create your first page** 버튼을 눌러 첫 페이지를 생성합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-02.png)

3. **Title, Path, Content, Commit message** 항목에 내용을 입력합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-03.png)

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

### 페이지 추가

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

1. Wiki 페이지 오른쪽 상단의 **케밥(세 개의 점으로 된 아이콘) 메뉴**를 클릭한 다음, **New page**를 클릭합니다(경로 자동 입력 없음).

2. 오른쪽 사이드바 페이지 메뉴에 마우스를 올리면 등장하는 **+** 버튼을 클릭합니다(경로 자동 입력).

3. 문서 작성 시 링크 텍스트(**용어 정리**)의 URL에 미래에 추가할 페이지 경로를 입력합니다(경로 자동 입력).

### 사이드바 활용

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

1. **구성**
    1. `/`로 나눠진 경로(**Path**)의 깊이(depth)에 따라 페이지 버튼이 오른쪽 사이드바에 노출됩니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-04.png)

    2. 사이드바에서는 페이지별 목차도 보여줍니다. heading1~6까지 나옵니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-05.png)

    3. 사이드바에는 페이지 버튼이 최대 5000개 표시됩니다. 그 이상 보려면, **View all pages**를 클릭합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-06.png)

2. **맞춤형 설정**
    1. 사이드바 오른쪽 상단의 **톱니바퀴** 버튼을 클릭합니다.
    2. **Edit custom sidebar**의 **Content** 칸에 링크 텍스트로 페이지 버튼을 직접 만듭니다. 이미지를 넣어 자유롭게 꾸며도 됩니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-07.png)

    3. 사이드바를 맞춤형으로 설정하면, 기본으로 제공되는 사이드바의 페이지 버튼을 토글로 접을 수 있습니다.
    4. 사이드바를 다시 수정하려면, 사이드바 오른쪽 상단의 **톱니바퀴** 버튼을 클릭합니다.
    5. 맞춤형 설정을 해제하려면, 수정 페이지에서 **Delete custom sidebar** 버튼을 누릅니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-08.png)

### 변경 이력 조회

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

1. 각 페이지에서 오른쪽 상단의 **케밥 메뉴**를 눌러 **Page history**에 진입합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-09.png)

2. History 페이지에 버전별 커밋 메시지가 뜹니다. ‘누가(**Author**), 언제(**Last updated**), 어떤 내용(**Diff**)으로 수정했는지’ 나옵니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-10.png)

3. Diff를 누르면, 변경 사항을 자세히 볼 수 있습니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-11.png)

4. 수정 이전 버전으로 되돌리려면 다음 두 가지 방법 중 하나를 실행합니다.
    1. 이전 버전의 내용을 복사해 Wiki 페이지에서 직접 수정합니다.
    2. Wiki도 저장소이므로, 저장소를 받아와서 수정합니다.
5. 실습에서는 4-ⅱ 방법을 사용해 수정 이전 버전으로 복구하겠습니다.
    1. Wiki 페이지 오른쪽 상단의 **케밥 메뉴**를 눌러 **Clone repository**를 클릭, git clone 합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-12.png)

    2. clone 받은 저장소 폴더로 이동해 에디터 또는 터미널에서 원치 않는 변경 사항을 revert 합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-13.png)

    3. main 브랜치에 push 합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-14.png)

    d. History 페이지에 돌아오면, 원치 않는 변경 사항을 revert한 이력이 업데이트된 걸 확인할 수 있습니다. 

### 템플릿 생성

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

1. Wiki 페이지 오른쪽 상단의 **케밥 메뉴**를 눌러 템플릿 페이지에 진입합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-15.png)

2. 템플릿 페이지에서 다시 오른쪽 상단에 **New template** 버튼을 클릭해 템플릿 생성 페이지로 이동합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-16.png)

3. 템플릿 Title, Content, 커밋 메시지를 작성합니다. **Create page** 버튼을 누르면 템플릿이 생성됩니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-17.png)

4. 템플릿을 사용하기 위해 ‘업데이트 노트’ 페이지를 만들었는데요. 이곳에 새 페이지를 추가하겠습니다. 새 페이지의 Template 항목에서 앞서 만든 템플릿을 선택합니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-18.png)

5. 템플릿을 선택하자, Content가 ‘미리 정의했던 템플릿’ 형식으로 자동 변경됩니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-19.png)

6. 아래는 위 템플릿을 활용해 작성한 문서 예시입니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-20.png)

### GitLab 이슈, MR 접근

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

1. 아래 예시는 Group에서 만든 Wiki인데요. 에디터 Content 칸에 #을 입력하면, Group을 포함한 모든 프로젝트의 이슈에 바로 접근할 수 있습니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-21.png)

2. 에디터 Content 칸에 #을 입력하면 이슈가, !를 입력하면 MR이 나타납니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-22.png)

3. 이렇게 작성된 링크에 마우스를 올리면 미리보기가 나옵니다.

    ![](/img/blog/2025-01-22-gitlab-wiki-inline-23.png)

### 에디터 사용 팁

- **이미지 입력**
    - 이미지를 입력할 때 이미지를 복사한 다음, 에디터에 plain text 모드로 붙여 넣으세요. 그게 더 깔끔하고, 위치를 조정하기도 쉽습니다. 크기를 조정하려면, rich text 모드로 변경해 마우스로 이미지 크기를 조정하는 게 더 편합니다.
    1. 에디터에 복사한 이미지를 plain text 모드로 붙여 넣습니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-24.png)

    2. 그다음, rich text 모드로 변경합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-25.png)

    3. 입력한 이미지를 드래그해 원하는 크기로 조절합니다.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-26.png)

- **다양한 도구 지원**
    - **+** 버튼을 클릭해 다양한 도구를 활용하세요. **Details block**을 누르면 details html 코드를 직접 삽입하지 않아도 됩니다. **Create or edit diagram**을 누르면 GitLab에서 바로 다이어그램을 작업할 수 있습니다. 또 **Table of contents**를 누르면 목차가 추가됩니다. 이밖에 여러 도구를 한번씩 클릭하며 기능을 확인하세요.

        ![](/img/blog/2025-01-22-gitlab-wiki-inline-27.png)

## 맺음말

GitLab Wiki는 팀 협업과 문서 관리를 최적화하는 강력한 도구입니다. Wiki를 사용하면 정보를 중앙 집중식으로 관리하고, 문서의 일관성을 유지하며, 효율적인 협업 환경을 조성할 수 있습니다. 이 글을 참고해 Wiki를 실무에 알차게 활용하세요!

::cta::

## 참고 자료

1. Matthew Macfarlane, “Get to know the GitLab Wiki for effective knowledge management”, GitLab, 2024.7.17, [https://about.gitlab.com/blog/2024/07/17/get-to-know-the-gitlab-wiki-for-effective-knowledge-management/](https://about.gitlab.com/blog/2024/07/17/get-to-know-the-gitlab-wiki-for-effective-knowledge-management/)
2. “Wiki”, GitLab, [https://docs.gitlab.com/ee/user/project/wiki/](https://docs.gitlab.com/ee/user/project/wiki/)

::faq::

- q: GitLab Wiki는 어떤 도구이고 어떤 장점이 있나요?

    a: GitLab Wiki는 GitLab 프로젝트와 그룹 수준에서 문서를 만들고 정리·공유하는 도구로, Markdown, RDoc, AsciiDoc, Org 등 여러 형식을 지원합니다. 플랫폼을 떠나지 않고 정보를 찾는 중앙 집중식 저장소 역할을 하고, 이슈·MR에 쉽게 접근하며, 버전 제어로 모든 변경을 추적하고 이전 버전을 복원할 수 있습니다. 템플릿으로 여러 페이지를 일관된 형식과 스타일로 유지할 수도 있습니다.

- q: GitLab Wiki 첫 페이지는 어떻게 만드나요?

    a: 프로젝트 또는 그룹의 Plan > Wiki 메뉴에서 Create your first page 버튼을 누르고 Title, Path, Content, Commit message를 입력한 뒤 Create page를 누르면 됩니다(2025년 1월 기준 화면). Path는 기본적으로 제목에 기반해 자동 입력되며, 임의로 바꾼 경로는 모두 기억하기 어려우므로 제목 기반 경로를 유지하는 것이 좋습니다. 첫 페이지의 경로는 home으로 입력합니다.

- q: GitLab Wiki에서 이전 버전으로 되돌리려면 어떻게 하나요?

    a: 페이지의 케밥 메뉴에서 Page history에 들어가면 버전별로 작성자(Author), 수정 시각(Last updated), 변경 내용(Diff)을 확인할 수 있습니다. 되돌리려면 이전 버전 내용을 복사해 페이지에서 직접 수정하거나, Wiki도 저장소이므로 Clone repository로 저장소를 받아 원치 않는 변경을 revert한 뒤 main 브랜치에 push하면 됩니다. 되돌린 이력은 History 페이지에 다시 기록됩니다.

- q: GitLab Wiki 템플릿은 어떻게 만들고 쓰나요?

    a: Wiki 페이지의 케밥 메뉴로 템플릿 페이지에 들어가 New template을 누르고 Title, Content, 커밋 메시지를 작성하면 템플릿이 생성됩니다. 새 페이지를 만들 때 Template 항목에서 템플릿을 고르면 Content가 미리 정의한 형식으로 바뀝니다. 반복해서 쓰는 문서 양식을 템플릿으로 만들면 문서 일관성을 유지하고 작성 시간을 줄일 수 있습니다.

- q: GitLab Wiki 사이드바는 어떻게 구성되고, 직접 바꿀 수 있나요?

    a: 사이드바에는 Path의 / 깊이에 따라 페이지 버튼이 표시되고, 페이지별 목차(heading 1~6)도 함께 나옵니다. 페이지 버튼은 최대 5000개까지 표시되며, 그 이상은 View all pages로 볼 수 있습니다. 사이드바 오른쪽 위 톱니바퀴 버튼의 Edit custom sidebar에서 링크 텍스트로 페이지 버튼을 직접 만들어 맞춤형 사이드바를 설정할 수 있습니다.

::faq-end::

::button::[GitLab으로 팀의 협업과 지식 관리를 한곳에 모으고 싶으신가요? GitLab 공식 파트너 인포그랩과 상담하세요!](https://insight.infograb.net/contact/)::
