GitLab 위키는 계획 도구와 함께 작동합니다. 별도의 도구가 아닙니다. 위키 페이지를 에픽, 이슈, 보드에 연결할 수 있습니다. GitLab Query Language(GLQL)를 기반으로 하는 임베디드 뷰를 통해 위키 페이지에서 이슈와 작업 항목의 라이브 자동 업데이트 뷰를 표시할 수 있어 문서를 동적 대시보드로 전환합니다. 문서와 계획이 함께 작동하는 원활한 워크플로를 만들기 위해 위키를 이슈, 에픽, 보드에 연결하는 방법을 알아보십시오.

위키는 다음을 제공하여 계획 도구를 돕습니다:

• 풍부한 문서 공간: 이슈 설명에 맞지 않는 복잡한 요구 사항, 설계 결정, 프로세스 문서.
• 버전 제어된 지식: 시간이 지남에 따라 사양과 결정의 변경 사항을 추적합니다.
• 라이브 데이터 뷰: GLQL 쿼리를 임베드하여 위키 페이지에서 직접 실시간 이슈 및 작업 항목 데이터를 표시합니다.
• 지속적인 컨텍스트: 이슈가 닫힌 후에도 결정 뒤의 "이유"를 유지합니다.
• 중앙 참조: 팀 프로세스, 표준, 합의에 대한 단일 정보 출처.
• 유연한 서식: 전체 Markdown 지원이 있는 표, 다이어그램, 장문 콘텐츠.
• 통합 액세스 제어: 위키는 GitLab의 기존 역할 및 권한 시스템을 사용하므로 팀 구성원이 별도 인증 없이 프로젝트 역할에 따라 자동으로 적절한 위키 액세스를 갖습니다.

사전 요건#

이 가이드를 효과적으로 사용하려면 다음에 익숙해야 합니다:

• GitLab 위키
• GitLab Flavored Markdown
• 이슈 및 에픽과 같은 다양한 작업 항목 생성 및 관리

위키 페이지를 작업 항목에 연결#

위키 문서와 계획 항목 간에 링크를 만들어 연결된 지식 네트워크를 구축합니다.

에픽에 위키 문서 연결#

에픽은 종종 에픽 설명에 담기에는 너무 긴 상세 사양이 필요합니다. 전체 문서를 위키에 보관합니다:

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Plan > Wiki를 선택합니다.

3. 상세 요구 사항이 담긴 위키 페이지를 만듭니다(예: 슬러그 product-requirements).

4. 상단 표시줄에서 Search or go to를 선택하고 프로젝트의 그룹을 찾습니다.

5. Plan > Work items를 선택합니다.

6. 필터 표시줄에서 필터 Type, 연산자 is, 값 Epic을 선택합니다.

7. 원하는 에픽을 식별하고 제목을 선택합니다.

8. 에픽 설명에서 위키 페이지에 링크합니다:

   ## Requirements
   
   See full specification: [[product-requirements]]
   
   Or with custom text: [[Full PRD|product-requirements]]
   
   Or use the full URL:
   [Full PRD](https://gitlab.example.com/group/project/-/wikis/product-requirements)
   

9. 위키 페이지에서 에픽으로 다시 링크합니다:

   Related epic: &123
   

사용 사례 예시:

• 제품 요구 사항 문서(PRD)
• 기술 설계 사양
• 사용자 연구 결과
• 경쟁 분석
• 성공 지표 및 KPI

이슈에서 위키 참조#

구현 세부 정보, 표준, 가이드에 대해 이슈를 위키 페이지에 연결합니다:

## Implementation notes

Follow our [[API-design-standards]] when implementing this endpoint.

For local setup, see [[Development Setup Guide|development-environment-setup]].

Definition of Done: [[team-dod]]

사용 사례 예시:

• 코딩 표준 및 스타일 가이드
• 개발 환경 설정
• 테스트 절차
• 배포 런북
• 문제 해결 가이드
• 온보딩 문서

위키에서 작업 항목으로 링크#

위키 페이지에서 직접 이슈와 에픽을 참조합니다:

## Current sprint goals

- Implement user authentication: #1234
- Fix performance regression: #1235
- Update API documentation: #1236

## Q3 roadmap

Major initiatives:
- Authentication overhaul: &10
- Performance improvements: &11
- API v2 release: &12

크로스 프로젝트 위키 참조#

다른 프로젝트의 위키 페이지에 링크합니다:

## Related documentation

See the backend team's API guide: [[backend/api:api-standards]]

Or use the alternative syntax: [wiki_page:backend/api:api-standards]

With custom text: [[Backend API Standards|backend/api:api-standards]]

임베디드 뷰로 동적 대시보드 만들기#

히스토리

• GitLab 17.4에서 glql_integration이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.4에서 일부 그룹 및 프로젝트에 대해 GitLab.com에서 활성화되었습니다.
• GitLab 17.10에서 실험에서 베타로 변경되었습니다.
• GitLab 17.10에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.
• GitLab 18.3에서 일반적으로 사용 가능하게 되었습니다. 기능 플래그 glql_integration이 제거되었습니다.

GitLab Query Language(GLQL)를 사용하여 위키 페이지를 라이브 대시보드로 변환합니다. 임베디드 뷰는 데이터가 변경될 때 자동으로 업데이트되어 위키를 벗어나지 않고 계획 데이터를 실시간으로 볼 수 있습니다.

기본 임베디드 뷰 구문#

GLQL 쿼리를 임베드하려면 언어 식별자로 glql이 있는 코드 블록을 사용합니다:

```glql
display: table
title: Sprint 18.5 Dashboard
description: Current sprint work items
fields: title, assignee, state, health, labels, milestone, updated
limit: 20
sort: updated desc
query: project = "gitlab-org/gitlab" and milestone = "18.5" and opened = true
```

이렇게 하면 현재 마일스톤의 모든 열린 이슈를 표시하는 라이브 테이블이 만들어지며 이슈가 생성, 수정 또는 닫힐 때 자동으로 업데이트됩니다.

계획 대시보드 예시#

위키 페이지에서 직접 종합적인 계획 대시보드를 만듭니다.

사전 요건:

• 쿼리된 이슈와 작업 항목을 볼 수 있는 권한이 있어야 합니다.

스프린트 개요 대시보드:

```glql
display: table
title: Sprint Overview
description: All work for the current sprint
fields: title, assignee, state, labels("priority::*") as "Priority", health, due
limit: 30
sort: due asc
query: project = "group/project" and milestone = "Current Sprint" and opened = true
```

중요 버그 추적기:

```glql
display: table
title: Critical Bugs
description: High-priority bugs requiring immediate attention
fields: title, assignee, labels, created, updated
limit: 10
query: project = "group/project" and label = "bug" and label = "severity::1" and opened = true
```

팀 작업 부하 뷰:

```glql
display: list
title: Team Work In Progress
description: Active work items by team member
fields: title, assignee, milestone, due
limit: 15
sort: assignee asc
query: project = "group/project" and assignee in (alice, bob, charlie) and label = "workflow::in dev"
```

개인 작업 목록:

```glql
display: orderedList
title: My Tasks
description: Tasks assigned to me, sorted by priority
fields: title, labels("priority::*") as "Priority", due
limit: 10
sort: due asc
query: type = Task and assignee = currentUser() and opened = true
```

임베디드 뷰는 다음을 지원합니다:

• 여러 표시 형식: table, list, 또는 orderedList
• 사용자 지정 필드: 표시할 필드 선택
• 정렬: 오름차순 또는 내림차순으로 임의의 필드 기준 정렬
• 필터링: 여러 조건을 사용한 복잡한 쿼리
• 페이지 매김: Load more로 추가 결과 로드
• 동적 함수: 개인화된 뷰에는 currentUser(), 날짜 기반 쿼리에는 today() 사용

위키를 사용한 계획 워크플로#

스프린트 계획 및 실행#

스프린트 전체에 걸쳐 연결된 문서 흐름을 만듭니다:

스프린트 전 계획#

1. 요구 사항 수집: 위키에 상세 요구 사항 문서화
2. 에픽 생성: 위키 사양을 참조하는 에픽 생성
3. 스토리 분류: 이슈를 관련 위키 문서에 연결
4. 추정 메모: 위키에 추정 이유 문서화

스프린트 중#

• 데일리 스탠드업: 차단된 이슈 링크가 있는 데일리 위키 페이지 생성.
• 기술 결정: 구현 이슈 링크와 함께 설계 결정 문서화.
• 장애물: 이슈 참조와 함께 위키에서 차단 요소 추적.

스프린트 후#

• 회고: 다음을 참조하는 위키 회고 페이지 생성:
  • 완료된 이슈
  • 속도 지표
  • 실행 항목(새 이슈로)
  • 학습된 교훈

장기 계획 문서#

로드맵에 연결되는 전략적 문서를 유지합니다:

로드맵 문서 구조#

roadmap/
├── 2025-strategy
├── q1-okrs
├── q2-okrs
├── architecture-decisions/
│   ├── adr-001-microservices
│   ├── adr-002-authentication
└── technical-debt-registry

각 페이지는 관련 에픽에 연결되고 이슈 참조를 통해 진행 상황을 추적합니다.

아키텍처 결정 기록#

추적 가능성이 있는 기술 결정을 문서화합니다. 다음과 유사한 템플릿을 사용할 수 있습니다:

# ADR-001: Adopt microservices architecture

## Status

Accepted

## Context

[Detailed context...]

## Decision

[Decision details...]

## Consequences

[Impact analysis...]

## Implementation

- Infrastructure epic: &50
- Service extraction: #2001, #2002, #2003
- Monitoring setup: #2004

크로스 기능 협업#

위키를 크로스 기능 팀의 협업 허브로 사용합니다:

설계 문서#

• 설계 사양을 구현 이슈에 연결
• 사용 예시가 있는 컴포넌트 라이브러리 유지
• 에픽 참조와 함께 설계 결정 문서화

API 문서#

• 구현 이슈에 연결되는 API 문서 생성
• 마일스톤 참조와 함께 버전 관리 정보 유지
• 테스트 이슈에 연결된 예시 코드 포함

QA 테스트 계획#

• 에픽 요구 사항에 연결된 테스트 전략
• 이슈 추적 가능성이 있는 테스트 케이스 저장소
• 이슈 예시가 있는 버그 패턴 문서

탐색 및 발견 패턴#

이슈와 보드에서 위키를 발견 가능하게 만들기#

이슈 및 에픽 템플릿#

위키 참조를 템플릿에 포함합니다:

## Prerequisites

- [ ] Review [[contribution-guidelines]]
- [ ] Check [[security-checklist]]
- [ ] Read relevant documentation in [[project-wiki-home]]

## Implementation

- [ ] Follow [[coding-standards]]
- [ ] Update [[api-documentation]] if needed
- [ ] Add tests per [[testing-guidelines]]

마일스톤 설명#

위키 계획 문서에 링크합니다:

## Milestone 18.5

Sprint dates: 2025-02-01 to 2025-02-14

- [[Sprint 18.5 Goals|sprint-18-5-goals]]
- [[Sprint 18.5 Capacity|sprint-18-5-capacity]]
- [[Known Issues|known-issues-and-workarounds]]

보드 설명#

위키 워크플로 문서를 참조합니다:

This board follows our [[Kanban Workflow Guide|kanban-workflow-guide]].

For column definitions, see [[Board Column Definitions|board-column-definitions]].

위키에서 작업 항목 표시#

인덱스 페이지 만들기#

관련 이슈를 수집하는 위키 페이지를 만듭니다:

# Open bugs dashboard

## Critical (P1)

- #1001 - Database connection timeout
- #1002 - Authentication bypass

## High (P2)

- #1003 - Performance degradation
- #1004 - UI rendering issue

## By component

### Authentication

- #1001, #1005, #1009

### API

- #1002, #1006, #1010

계층적 위키 구조 사용#

폴더와 상대 링크로 위키 페이지를 구성합니다:

# Team handbook

## Processes

- [Sprint Planning](processes/sprint-planning) - How we plan sprints
- [Code Review](processes/code-review) - Review standards and SLAs
- [Incident Response](processes/incident-response) - On-call procedures

## Go up to parent page

[Back to Documentation](../documentation)

실용적인 예시#

예시 1: 기능 개발 워크플로#

위키 통합을 사용한 완전한 기능 개발 사이클:

1. 제품 관리자:

   • 시장 조사가 담긴 feature-x-prd 위키 페이지 만들기.
   • [[Feature X PRD|feature-x-prd]] 링크와 함께 에픽 &100 만들기.
   • 위키에 수락 기준 추가.

2. 엔지니어링 리드:

   • feature-x-technical-design 위키 페이지 만들기.
   • 디자인 문서를 에픽 &100에 연결.
   • 위키 참조가 있는 구현 이슈 #201-205 만들기.

3. 엔지니어:

   • MR 설명에서 위키 디자인 문서 참조.
   • 결정 변경으로 위키 업데이트.
   • 이슈를 위키 문제 해결 가이드에 연결.

4. QA 엔지니어:

   • feature-x-test-plan 위키 페이지 만들기.
   • 테스트 이슈 #301-305를 테스트 계획에 연결.
   • 이슈 참조와 함께 위키에 테스트 결과 문서화.

5. 기술 작성자:

   • 위키에서 사용자 문서 업데이트.
   • 문서 이슈 #401 만들기.
   • 위키 변경 사항을 기능 에픽에 연결.

예시 2: 라이브 대시보드가 있는 팀 지식 기반#

실시간 인사이트를 위한 임베디드 뷰로 팀 핸드북을 구성합니다:

# Engineering team handbook

## Current sprint status

```glql
display: table
title: Sprint Progress
fields: title, assignee, state, labels("workflow::*") as "Status"
limit: 20
query: project = "team/project" and milestone = "Sprint 23" and opened = true
```

## Processes

- [[Sprint Planning Process|sprint-planning-process]] - How we plan sprints
- [[Code Review Guidelines|code-review-guidelines]] - Review standards and SLAs
- [[Incident Response|incident-response]] - On-call procedures

## Technical standards

- [[API Design Standards|API-design-standards]] - REST API conventions
- [[Database Schema Guide|database-schema-guide]] - Schema design rules
- [[Security Checklist|security-checklist]] - Security requirements

## Work management

- [Issue board](https://gitlab.example.com/group/project/-/boards/123)
- [Current milestone](https://gitlab.example.com/group/project/-/milestones/45)
- Label taxonomy: [[Label Definitions|label-definitions]]

## Onboarding

- [[New Developer Setup|new-developer-setup]] - Environment setup
- [[First Week Issues|first-week-issues]] - Good first issues: #101, #102, #103
- [[Team Contacts|team-contacts]] - Who to ask for what

빠른 참조#

위키 링크 구문#

작업 항목 참조#

위키에서 이슈 만들기#

위키의 작업 목록을 사용하여 이슈로 변환할 수 있습니다:

## Action items from retrospective

- [ ] Improve CI pipeline performance
- [ ] Update documentation
- [ ] Add monitoring for API endpoints

체크 박스를 선택하고 Create issue를 사용하여 작업을 추적된 이슈로 변환합니다.

효과적인 통합을 위한 팁#

페이지 슬러그를 올바르게 사용#

• 위키 링크는 페이지 슬러그(URL 친화적 버전)를 사용합니다: API Standards가 아닌 api-standards.
• 페이지가 없으면 링크를 선택하여 만들 수 있습니다.
• 붙여 넣은 위키 URL은 자동으로 읽을 수 있는 텍스트로 변환됩니다(하이픈이 공백이 됩니다).

양방향 링크 유지#

• 위키에서 이슈로 링크할 때 이슈도 위키 페이지를 참조하도록 업데이트합니다.
• 더 쉽게 발견할 수 있도록 일관된 명명 규칙을 사용합니다.
• 웹훅 또는 CI/CD로 링크 생성을 자동화하는 것을 고려합니다.

발견을 위해 구성#

• 모든 계획 문서를 색인화하는 위키 홈 페이지를 만듭니다.
• 일관된 페이지 이름을 사용합니다: sprint-2025-01, adr-001, feature-name.
• 대형 위키에는 폴더가 있는 계층적 구조를 사용합니다.
• 레이블 분류와 일치하는 카테고리로 위키 페이지에 태그를 지정합니다.

문서를 최신 상태로 유지#

• 완료 정의에 문서 업데이트를 포함합니다.
• 스프린트 계획 중에 위키 페이지를 검토합니다.
• 오래된 페이지를 archive/ 폴더에 보관합니다.

템플릿 사용#

일반적인 문서에 대한 위키 템플릿을 만듭니다:

• 스프린트 계획 템플릿
• 회고 템플릿
• 기능 사양 템플릿
• 아키텍처 결정 기록 템플릿

관련 주제#

• 위키
• 이슈
• 이슈 보드
• 에픽
• GitLab Query Language
• GitLab Flavored Markdown