GitLab Issue

GitLab Issue 온보딩 가이드

GitLab Issue 기능을 빠르게 실무에 적용할 수 있도록 작성된 실전 가이드입니다.

1. GitLab Issue란?

Issue가 무엇인가요?

GitLab Issue는 프로젝트에서 처리해야 할 작업 단위를 기록하고 추적하는 기능입니다.

버그 수정, 기능 개발, 문서 작업, 논의 사항 등 팀에서 다뤄야 하는 모든 것이 Issue가 될 수 있습니다.

왜 사용하나요?

코드 변경은 커밋과 브랜치로 추적할 수 있지만, "왜 이 작업을 했는가" 에 대한 맥락은 코드만으로는 남기기 어렵습니다.

Issue를 사용하면:

• 작업의 목적과 범위를 명확히 정의할 수 있습니다.
• 담당자·기한·진행 상태를 한눈에 파악할 수 있습니다.
• 코드 변경(MR)과 작업(Issue)을 연결해 히스토리를 추적할 수 있습니다.

이슈 상태 흐름

GitLab Issue는 두 가지 상태를 가집니다.

Open ──────────────────────────────────────────► Closed
 │                                                   │
 │  작업 시작 전 또는 진행 중인 상태                      │  작업 완료 또는 논의 종료 상태
 │  → 팀원 누구나 댓글·수정 가능                         │  → Reopen으로 다시 Open 전환 가능

상태 의미 전환 방법

Open	작업이 진행 중이거나 대기 중	이슈 생성 시 기본값
Closed	작업 완료 또는 불필요 판단	Close issue 버튼 클릭, 또는 MR 병합 시 자동 닫힘

💡 팁: MR 설명에 Closes #42를 입력하면 해당 MR이 병합될 때 Issue #42가 자동으로 Closed 처리됩니다.

2. 필수 용어 정리

용어 설명

Label	이슈를 분류하는 태그. bug, feature, in-progress 등으로 상태나 유형을 표시하며 필터링에 활용됩니다.
Assignee	해당 이슈를 담당하는 팀원. 1명 이상 지정 가능하며, 지정된 사람에게 알림이 전송됩니다.
Milestone	여러 이슈를 묶는 기간 단위 목표. 스프린트나 릴리즈 버전 관리에 주로 사용됩니다.
Task list	이슈 설명 안에 작성하는 체크리스트(- [ ] 항목). 세부 작업의 완료 여부를 이슈 목록에서 바로 확인할 수 있습니다.
Comment	이슈에 달리는 댓글. 논의 내용, 진행 상황 업데이트, 참고 정보 공유 등에 사용됩니다.
MR 연결 (Closes #이슈번호)	MR 설명에 작성하는 키워드. MR 병합 시 연결된 이슈를 자동으로 Close 처리합니다.

3. Milestone 생성 방법

Milestone은 이슈를 묶을 기간 목표(예: Sprint 1, v1.2.0 릴리즈)입니다.

이슈를 등록하기 전에 먼저 Milestone을 생성해 두는 것을 권장합니다.

생성 절차

1. 좌측 사이드바에서 {project-name} 프로젝트로 이동합니다.
2. 사이드바 메뉴에서 Plan → Milestones를 클릭합니다.
3. 우측 상단의 New milestone 버튼을 클릭합니다.
4. 아래 항목을 입력합니다.필드 입력 예시 설명

   Title	Sprint 3 또는 v1.2.0	Milestone 이름 (필수)
   Start date	2025-07-01	시작일 (선택)
   Due date	2025-07-14	종료일 (선택, 진행률 표시에 사용)
   Description	결제 모듈 개발 완료 목표	해당 Milestone의 목표 설명 (선택)

5. Create milestone 버튼을 클릭해 생성을 완료합니다.
6. 생성된 Milestone은 Plan → Milestones 목록에서 확인할 수 있으며, 이슈 등록 시 바로 선택 가능합니다.

⚠️ 주의: Milestone은 프로젝트 단위로 생성됩니다. 다른 프로젝트에서 동일한 Milestone을 사용하려면 해당 프로젝트에서 별도로 생성해야 합니다.

4. 이슈 등록 실전 흐름

아래 흐름을 순서대로 따라하면 이슈 하나를 완전하게 등록할 수 있습니다.

Step 1. 이슈 작성 시작

1. 좌측 사이드바에서 Plan → Issues로 이동합니다.
2. 우측 상단 New issue 버튼을 클릭합니다.
3. Title 필드에 이슈 제목을 입력합니다.💡 제목은 [유형] 작업 내용 형태로 작성하면 이슈 목록에서 파악이 쉽습니다.
4. 유형 예시: [Bug], [Feature], [Docs], [Refactor]
5. [Feature] 로그인 페이지 소셜 로그인(Google) 버튼 추가
6. Description 필드에 아래 구조로 본문을 작성합니다.
7. ## 배경 사용자 피드백으로 소셜 로그인 요구사항이 확인됨. 구글 계정으로 로그인 기능 추가 필요. ## 작업 범위 - Google OAuth 2.0 연동 - 로그인 버튼 UI 구현 - 로그인 성공/실패 처리 로직 작성 ## 참고 - 디자인 시안: [Figma 링크] - 관련 문서: [Google OAuth 공식 문서]

Step 2. Assignee / Label / Milestone 설정

이슈 작성 화면 우측 패널에서 아래 항목을 설정합니다.

1. Assignee 설정
   • Assignee 항목 옆 Edit을 클릭합니다.
   • 검색창에 @{username}을 입력해 담당자를 선택합니다.
   • 본인이 담당이라면 Assign to me를 클릭합니다.
2. Label 설정
   • Labels 항목 옆 Edit을 클릭합니다.
   • feature, in-progress 등 적절한 Label을 선택합니다.
   • Label이 없다면 Create project label로 신규 생성할 수 있습니다.
   💡 Label 컨벤션 예시 (팀 내 합의 후 사용):Label 용도

   bug	버그 수정 작업
   feature	신규 기능 개발
   in-progress	현재 진행 중
   blocked	외부 의존성으로 대기 중
   needs-review	리뷰 요청 상태

3. Milestone 설정
   • Milestone 항목 옆 Edit을 클릭합니다.
   • 3단계에서 생성한 Milestone을 선택합니다.

Step 3. Task list 작성

Description에 체크리스트를 추가해 세부 작업을 관리합니다.

## Task list

- [ ] Google Cloud Console에서 OAuth 클라이언트 ID 발급
- [ ] 환경 변수 설정 (`.env` 파일에 `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` 추가)
- [ ] 소셜 로그인 버튼 컴포넌트 구현
- [ ] OAuth 콜백 핸들러 구현
- [ ] 로컬 테스트 완료
- [ ] QA 환경 배포 및 검증

💡 Task list의 완료율은 이슈 목록 카드(◼ 2/6)에 자동으로 표시됩니다.

각 항목을 완료할 때마다 - [x]로 체크해 주세요.

Step 4. 이슈 제출

모든 항목 입력 후 Create issue 버튼을 클릭합니다.

이슈가 생성되면 URL에 이슈 번호(#42 형태)가 부여됩니다. 이 번호는 MR 연결에 사용됩니다.

Step 5. MR 연결 (Closes #이슈번호)

작업을 완료하고 MR을 생성할 때, MR 설명에 아래 키워드를 추가합니다.

## 관련 이슈

Closes #42

키워드 동작

Closes #42	MR 병합 시 Issue #42 자동 Close
Fixes #42	Closes와 동일
Resolves #42	Closes와 동일

⚠️ 주의: Closes #42는 MR 설명(Description) 에 작성해야 합니다.

커밋 메시지에 작성하면 동작하지 않을 수 있습니다.

MR이 기본 브랜치(보통 main 또는 develop)에 병합되면 연결된 이슈가 자동으로 Closed 처리됩니다.

요약: 이슈 등록 체크리스트

이슈를 등록할 때 아래 항목을 확인하세요.

• [ ] 제목에 유형 태그 포함 ([Feature], [Bug] 등)
• [ ] Description에 배경·작업 범위 명시
• [ ] Assignee 지정 완료
• [ ] Label 1개 이상 설정
• [ ] Milestone 연결 완료
• [ ] Task list 작성 완료
• [ ] MR 생성 시 Closes #이슈번호 입력