GitLab 도입 시 작성한 매뉴얼 (이클립스 위주)

gitLab 팀내 도입시 작성한 매뉴얼 내용 

GitLab 을 활용한 Workflow

프로젝트 수행에 필요한 업무를 GitLab 기반 시스템을 통해 진행하는 절차를 설명한다.

그룹 생성

GitLab을 이용하여 팀을 구성(Group, Member, Permission)하고 업무를 계획(Milestone)하고 업무 세분화하여 팀원에게 배정(Issue)하는 단계로 프로세스는 다음과 같다

1. 그룹을 등록한다. 프로젝트를 수행하는 팀 단위로 Group을 만든다. 유지보수를 수행하는 팀이라면 운영하는 시스템 단위로 Group을 생성한다. (Menu > Groups > Create group)

2. 그룹명, 공개레벨 등을 설정하고 그룹을 생성한다.

3. 그룹에 사용자를 추가

그룹에 사용자를 추가하고 역할을 부여한다.

   

    역할의 권한은 다음과 같다

구분	내용
Guest	이슈만 생성가능
Reporter	이슈 관리, Merge Request 가능
Developer	브랜치 생성, Merge Request 가능 (개발자/주니어)
Maintainer	Master Push, 배포, Merge Request 승인 등 가능 그룹/프로젝트/구성원 관리를 제외하고 대부분 Owner와 동일 (PL/시니어)
Owner	그룹이나 프로젝트 관리자 관리권한 (PM/팀장/관리자)

 

    그룹에 멤버가 추가되었다

 

 

프로젝트 등록

1. 소스코드 관리 단위로 Project를 만든다. 소스코드 관리 단위라는 것은 IDE(통합개발도구)에서 git을 통해 Project를 checkout해서 개발이 가능한 형태를 이야기한다.

예)웹 관리도구 및 서버 2개의 프로젝트라면 최소 2개의 프로젝트를 등록한다.

   

New Project 클릭

   

    프로젝트 명 및 관련 내용을 기입한다.

 

프로젝트가 생성되었다.

 

 

2. 프로젝트에 소스 등록

1. 이클립스에서 프로젝트 우클릭 후 Team>ShareProject

(위 기능을 사용하려면 Help > Eclipse Marketplce > egit검색 > EGit 설치가 필요하다.)

 

로컬 리파지토리에 공유 시키기

 

 

        Finish 클릭하면 이제 team 메뉴에서 Git관련 명령어를 사용할 수 있다.

       

 

window > show view > other... 클릭

Git > Git Repositories > Open

메뉴를 열면 Git에 대한 정보를 볼 수 있다.

 

1. 로컬에 커밋

package Explorer 창에서 프로젝트 명(git) 우클릭 COMMIT 후

프로젝트의 파일 전체를 커밋한다.

 

1. 원격 저장소에(GitLab) 연동

기존의 생성한 프로젝트에 연동해보자

(http://gitlabserver_IP/testgroup[그룹명]/testfido[프로젝트명])

Git Repositories에서 Remotes 우클릭 Create Remote 클릭

 

1. 바로 push 할 예정이므로  Configure fetch를 누른다 (사진은 한번 이미해서 다음과같이 나옴)

 

change 클릭

 

git 주소와 해당 프로젝트에 유효한 GitLab 아이디와 비밀번호를 입력해준다.

 

 

(주의 : 사내 깃랩은 도메인으로 입력시 어떻게 push 해도 오류 나므로 다음과 같이 도메인 대신

아이피로 입력 해야 정상적으로 Push 후 mergerRequest를 할 수 있다.)

Finish 클릭후 Save 클릭

 

Git Repositories를 확인하면 원격 저장소가 추가된 것이 확인된다.

1. 브랜치 push 브랜치 생성후 GitLab에도 로컬 브랜치가 생성했다는 것을 push하여 등록해야한다.

1. gitLab 사이트에 가면 자신의 로컬브랜치가 등록되어있다. 로컬에서 커밋하다가 바로 브랜치 Push 후 mergeRequest를 날리는게 아니고 일단 브랜치 등록 후 로컬에서 소스 커밋 후 반영 후

mergeRequest를 만들어서 진행한다.

 

 

 

 

1. 로컬 브랜치에서 커밋후 push branch를 진행하면 해당 commit 이력이 gitLab에 반영된다.

1. MergeRequest 진행 전에 main(master)의 코드 변경점(다른사람이 반영하여 기존 소스가코드가 변경되어 있응 가능성이 있음) 확인하고

충돌하는 부분을 반영 후 MergeRequest를 진행해야한다.

 

1. MergeRequest를 진행하기

gitlab에 들어가면 mergerequest 요청이 와 있다.

 

create merge 클릭 후 관련 내용을 적어준다.

 

 

mergeRequest가 등록된다.

 

MergeRequest 상세설명

[OverView] 해당 Merge를 승인하거나 코멘트를 달 수 있다.

[commits] 해당 branch에서 커밋을 몇번 진행했는지

[Changes] 실제 소스의 변경사항을 보여준다.

승인자 혹은 리뷰어는 궁금한거나 버그가 될수있는 라인에 코맨트를 달수있다

승인(approve) 후 merge를 하면 merge가 완료된다 지금은 나자신이 owner 권한이므로 merge 버튼이 활성화 되지만 권한이없으면 Merge 버튼이 활성화 되지 않는다.

반영된 모습

1. 개발업무 절차 (workflow)

프로젝트관리자가 등록한 프로젝트를 팀원이 업무결과인 코드 또는 문서를 git 저장소에 올리고

Issue를 종료하는 절차이다.

비교적 간단한 Feature 브랜치 workflow로 진행한다.

1. Issue가 할당되면 master(main) 브랜치에서 feature 브랜치를 생성하고
2. 생성한 feature 브랜치에서 할당된 이슈 (기능 추가 등등) 를 작업한다.
3. 작업 후 commit & push하고 master 브랜치로 Merge 하는 방식이다.

 

1. 팀원 개발 프로세스
2. gitlab에 접속하여 해당하는 프로젝트를 clone 버튼 클릭 후 프로젝트의 http git url을 복사한다.

    이클립스 Git Repositories > Clone a git repository

복사한 git uri 정보와 팀원 자신의 User/Password 값을 입력한다.

next 클릭

1. Finish 클릭

Git Repositories 창에 해당 Git이 생성 되었다.

로컬로 프로젝트를 Import 한다.

Finish 클릭

이클립스와 git이 연동되었다.

협업을 위해 새 브랜치를 만든다.

브랜치 명을 설정 후 해당 브랜치를 생성한다.

브랜치 명명 규칙은 다음과 같다

[브랜치 명명 규칙]

1) master branch, develop branch master와 develop 브랜치는 본래 이름 그대로 사용하는 경우가 일반적이다.   2) feature branch (기존소스에 추가되는 기능이므로 이것에 해당한다.) 어떤 이름도 가능하다. 단, master, develop, release-..., hotfix-... 같은 이름은 사용할 수 없다. feature/기능요약 형식을 추천한다. ex) feature/login   feature/{issue-number}-{feature-name} 이슈추적을 사용한다면 이와 같은 형식을 따른다. ex) feature/1-init-project, feature/2-build-gradle-script-write   3) release branch release-RB_... 또는 release-... 또는 release/...같은 이름이 일반적이다. release-... 형식을 추천한다. ex) release-1.2 4) hotfix branch hotfix-... 형식을 추천한다. ex) hotfix-1.2.1

 

생성된 개인 브랜치로 이동되었다 이 프로젝트에서 소스를 수정하면 된다.

 

1. 소스를 수정 및 추가를 진행한다.
2. Synchronize workspace 로 들어가서 확인하면 local에서 변경 한 부분이 확인 가능하다.

좌측 로컬 변경 소스 우측 기존 소스

 

commit 을 진행한다.

1. push 이전에 main 브랜치가 업데이트 된 경우 해당 main을 pull 받아 최신화 한다.
2. 수정 및 추가가 완료된 경우 Commit Message 작성후 Commit And Push 한다.

내부적으로 코드를 한번 확인 후 수정사항 확인한 경우는 Commit 만 진행하여 중간 저장후

완료되면 Push를 진행한다.

 

[Push 시 https repository 연결시 ssl 인증서 관련 오류해결법]

해당 프로젝트의 .git 디렉터리의 config 파일의 해당 값을 추가하고 다시 push한다.

[http] sslVerify = false

gitLab 페이지에가면 Merge request를 작성하라고 알림이 뜬다

merge Request를 작성한다. (Assigner 및 Reviewer지정)

참조된 팀원들에게 메일이 전송된다.

승인자 및 리뷰어는 해당 변경된 소스를 확인하고 리뷰하고 코맨트 및 승인을 진행한다.

 

요청자에게 리뷰에 대한 내용이 메일로 전달되어 옵니다.

코드 리뷰 종료후 답글로 수정사항에대한 의문점이나 답변을 게시 후 close merge request 로 merge를 반려합니다 반려가되면 해당 이슈는 클로즈 됨.

해당 사항 수정 후 commit 및 다시 Push를 한다.

다시 gitlab에서 merge request 작성 후 승인자 및 리뷰어는 확인을을 한다.

이상이 없을 경우 approve (승인) 및 Merge를 실시한다.

잘한 경우 따봉도 찍어준다

Merge 완료 후

[Merge 할 경우 다음 에러 메일이 오면서 Merge가 되지 않는 경우]

프로젝트 > settings > CI/CD > Auto DevOps> Default to Auto DevOps pipeline 체크 해제 후 다시 Merge 실행

1. 이클립스로 돌아가 branch에서 main으로 돌아가 반영된 소스를 받는다 (pull)

(현재 사진은 이미 main이라 비활성화됨)

추가 기능 및 수정시 다시 브랜치를 생성하여 위와 같은 프로세스를 반복한다

GitLab 사용자 등록 및 유저 관리 기능

로컬 gitlab은 관리자가 계정을 만들어 주거나 사용자가 자신의 정보를 입력 후

회원가입을 신청후 관리자가 승인하는 형태로 회원가입이 이루어진다.

1. gitlab 접속 후 회원가입(Register now) 버튼 클릭

회원가입에 필요한 정보를 입력한다.

관리자에게 승인 요청을 한다.

[관리자로 유저 승인]

관리자 계정정보로 gitlab 접속 후

admin>Users>Pending approval 에 요청한 유저를 승인한다.

   

사전 설치 프로그램

• 사전에 gtibash 및 이클립스 플러그인 Egit이 필요하다
• 해당 모듈은 인터넷에서 가이드를 받아 설치한다.
• Egit 설치 시 주의점 Egit을 인터넷에 나와있는 아무 링크로 받게 되면 자신의 이클립스 버전과 달라 에러가 나는 경우가 있다 다음 링크를 참고하여 자신의 이클립스 버전과 맞게 Egit을 설치하도록 한다.
• 참고 링크 (https://projects.eclipse.org/projects/technology.egit)

 

마일스톤 및 이슈 작성법

GitLab 마일스톤이란?

프로젝트에서 주요한 이벤트를 표시하는 기준점 , 프로젝트의 진척을 관찰하기 위해 사용한다.

프로젝트의 최종 목표점이나 완성을 의미하는 것은 아니며 프로젝트가 진행되는동안 달성되어야하는 특정한 목표라고 이해하면 된다. gitLab에서는 프로젝트를 위한 마일스톤을 관리 할 수 있다.

프로젝트 혹은 그룹별로 마일스톤을 만들어 목표 날짜를 설정할 수 있다.

마일스톤에 도달하기 위한 작업들을 등록한다. 마일스톤에 이슈를 추가하므로 마일스톤에 도달하기 위한

작업들을 등록한다. GitLab에서는 생성된 이슈와 완성된 이슈으이 비율을 계산하여 마일스톤의 진척율을 한 눈에 볼 수 있는 milestone view를 제공한다.

 

[참고] 마일스톤 뷰

 

  GitLab 이슈란?

    GitLab 프로젝트에서 개선되거나 해결되어야할 것을 의미하는 이슈를 등록할 수 있다.

    이슈는 제목과 설명을 기입하고 이슈가 할당되는 사람 (처리해야하는사람) 기한, 해당하는 마일스톤,

    라벨 등을 입력하여 등록하게 된다. 이슈가 프로젝트의 issuetracker에 등록되면 이슈가 열리며(open)

    코멘트를 남기거나 참여시키고 싶은 사람 (@+’사용자아이디’를 사용하여)을 언급할 수 도 있습니다.

    만약 이슈가 해결되면 merge request에 이슈를 연결 시킬 수도 있고 커밋 메시지를 통해 issue가

    close되게 할 수도 있습니다.

 

    [참고] 이슈관리 뷰

 

마일스톤 생성하기

GitLab 사이트 접속 > Menu > milestones

Select project to create milestone V 클릭 하면 그룹에 대한 마일스톤인지 프로젝트에 대한 마일스톤으로 지정할 건지 선택할 수 있다.

마일스톤에 대한 제목 및 설명을 입력후 마일스톤을 생성한다.

생성된 마일 스톤 모습

이슈 생성하기

1. 이슈는 마일스톤에 포함시킬수 있으며 마일스톤이 없더라도 독립적으로 생성가능하다.
2. 프로젝트 좌측 UI에서 이슈 탭을 클릭 후 new Issue 를 클릭한다.

 

해당 이슈가 포함 될 MileStone 및 Labels를 추가합니다 (기능 수정, 기능 추가 ,버그 등등)

라벨 종류

버그, 긴급 : [빨간색]

기능 추가 : [초록]

질문 , 논의 : [파랑]

문서, 지원 : [노란색]

 

다음과 같이 이슈가 생성되고 해당 이슈에 대한 merge requst 생성이 가능하다.

해당 이슈에 대한 처리가 완료되면 해당 이슈는 close 시킨다.

해당 이슈에 처리 퍼센트가 표시된다.

 

 

템플릿 작성 및 적용방법

GitLab 템플릿이란 issue나 merger request 처럼 협업에 필수적으로 사용되는 요소들에 공통된 양식으로 가독성과 코드리뷰를 원활하기 위해 사용하는 양식이다.

적용 방법

1. 본인의 repository root 경로에 .gitlab 디렉터리를 생성한다.
2. .gitlab/issue_templates/ 내부 md 파일은 모두 issue 템플릿으로 활용된다.
3. .gitlab/merge_request_templates/ 내부 md 파일은 mr 템플릿으로 활용된다.

 

[템플릿 예시]

bug_report.md

<!--bug_report.md--> --- name: Bug report about: Report a bug you've encountered title: "[Bug]: Please add a title" labels: bug assignees: '' --- ## Summary 어떤 버그인지 명확하고 간결한 서술 ## To Reproduce 해당 버그를 재현하기 위한 단계: 1. Go to '...' 2. Click on '....' 3. Scroll down to '....' 4. See error ## Expected behaviour 왜 일어났는지에 대한 명확하고 간결한 서술 ## Screenshots 가능하다면 문제를 해결하기 적합한 스크린샷 첨부 ## Environment - 자바 버전: [e.g. 3.8.0] - 리눅스 버전: [e.g. 20.04LTS] ## Browser(s)  - Browser [e.g. chrome, safari]  - Version [e.g. 22] ## Additional context 위에 해당되지 않은 항목 기술 e.g. 이슈 #397과 유사한 증상입니다. /label ~버그 ~문제 /cc @juhyeon /assign @juhyeon

 

merge_request.md

## 어떤 이유로 MR를 하셨나요? - [ ] feature 병합(feature issue #를 남겨주세요) - [ ] 버그 수정(아래에 issue #를 남겨주세요) - [ ] 코드 개선 - [ ] 기타(아래에 자세한 내용 기입해주세요) ## 스크린샷 및 세부 내용 - 왜 해당 MR이 필요한지 자세하게 설명해주세요 - 세부사항을 항목으로 설명해주세요 ## MR하기 전에 확인해주세요 - [ ] local code lint 검사를 진행하셨나요? - [ ] local ci test를 진행하셨나요 ? ## relavant issue number - 관련된 이슈 넘버가 있으면 이곳에 기입해주세요

merge_request.md

### 작업 개요 <!--   ex) 로직 수정 --> ### Issue <!--   ex) #21342 --> ### 작업 분류 - [ ] 버그 수정 - [ ] 신규 기능 - [ ] 프로젝트 구조 변경 <!--   - [ ] 버그 수정   - [x] 신규 기능   - [ ] 프로젝트 구조 변경 --> ### 작업 상세 내용 <!--   ex)   1. 클래스에 함수 추가   2. 어떤 클래스에서 어떤 함수에 어떤 기능이 작동하도록 추가 --> ### 생각해볼 문제 <!--   ex)   1. 여러번 호출하는 로직이 있으므로 귀찮음 -->

 

 

issue_templet.md

# Issue 🙋🏻‍♂️ ## 개요 현재 브랜치에 대한 정보를 입력해주세요. - [ ] New Feature - [ ] Bug Fix - [ ] CI / CD - [ ] Setup ## 이슈 내용 버그일 경우에는 버그가 발생한 위치도 함께 입력해주세요. ## 체크 리스트 ## 기타

해당 파일을 main에 push 후 해당 프로젝트 이슈 생성시 다음과 같이 탬플릿을 지정 가능한 것이 확인된다.

 

커밋 (commit)

• 커밋은 GitLab에서 진행하지 않고 , 로컬에서 진행하는 때가 대부분이기 때문에 탬플릿 적용은 힘이든다 그러나 공통된 양식이 없으면 서로의 커밋 양식이 중구난방이 되어버리기 때문에 다음과 같은 양식을 지정한다.

커밋 메시지의 7가지 규칙

      1. 제목과 본문을 빈 행으로 구분한다

      2. 제목을 50글자 내로 제한

      3. 제목 첫 글자는 대문자로 작성

      4. 제목 끝에 마침표 넣지 않기

      5. 제목은 명령문으로 사용하며 과거형을 사용하지 않는다

      6. 본문의 각 행은 72글자 내로 제한

      7. 어떻게 보다는 무엇과 왜를 설명한다

 

1. 커밋 메시지 구조

헤더는 필수이며, 범위(scope), 본문(body), 바닥글(footer)은 선택사항입니다.

<type>(<scope>): <subject>          -- 헤더 <BLANK LINE> <body>                              -- 본문 <BLANK LINE> <footer>                            -- 바닥글

    <type>은 해당 커밋의 성격을 나타내며 아래 중 하나여야 합니다

feat : 새로운 기능에 대한 커밋 fix : 버그 수정에 대한 커밋 build : 빌드 관련 파일 수정에 대한 커밋 chore : 그 외 자잘한 수정에 대한 커밋 ci : CI관련 설정 수정에 대한 커밋 docs : 문서 수정에 대한 커밋 style : 코드 스타일 혹은 포맷 등에 관한 커밋 refactor :  코드 리팩토링에 대한 커밋 test : 테스트 코드 수정에 대한 커밋

    <body>는 본문으로 헤더로 표현할 수 없는 상세한 내용을 적습니다.

    헤더로 표현이 가능하다면 생략가능하다.

<footer>는 바닥글로 어떤 이슈에서 왔는지 같은 참조 정보들을 추가하는 용도로 사용합니다

예를 들어 특정 이슈를 참조하려면 close #1233 과 같이 추가하면 됩니다.

close는 이슈를 참조하면서 main브랜치로 푸시될 때 이슈를 닫게 됩니다.

 

<예시 커밋 메시지>

feat: 관심지역 알림 ON/OFF 기능 추가(#123)    시군구의 알림을 각각 ON/OFF 할 수 있도록 기능을 추가함  - opnion0055: 구분 코드 해결: close #123

 

   

git 사용법

• reset이란 기록이 남지 않게 커밋을 취소하는 것이다. 아래방법은 푸쉬 하지 않고 로컬에서만 커밋을 반영했을 경우 유효하다.
• 이클립스로 커밋을 진행했는데 취소하고 싶은경우
• history 창을 연다.

• 이동하고 싶은 타임라인을 클릭 후 reset을 클릭한다.

• reset은 hard, mixed, soft 3단계 모드를 지정할 수 있다.

mode	Working Tree	Staging Area	Repository
hard	되돌림	되돌림	되돌림
mixed	유지	되돌림(unstaged로 변경)	되돌림
soft	유지	유지	되돌림

 

• 뭔말이냐
• soft : commit을 취소하고 해당 파일들은 staged 상태로 워킹 디렉터리에 보존
• mixed : commit을 취소하고 해당파일들은 unstaged상태로 워킹디렉터리에 보존
• hard : commit을 취소하고 해당 파일들은 unstaged 상태로 워킹 디렉터리에서 삭제

1. SVN프로젝트 GitLab으로 이전하기

• IDE에서는 git 혹은 svn프로젝트 둘중 1개만 사용할 수 있다.
• 기존 솔루션을 gitlab으로 이전하려면 프로젝트 복사후 GitLab 전용 workSpace 따로 설정한뒤 사용한다.(이전 후 그냥 사용하는 게 좋지만 현재 SVN도 기본으로 사용해야한다고 함 완전 이전 문의는 팀장님께 문의)
• Gitlab 에 반영 후 추가로 Svn 에도 해당 내용을 업데이트해서 반영해야한다.
• 기존 커밋이력도 옮기는 방법을 시도했으나 svn 서버 자체를 수정해야하는 에러같아서 해당방법으로는 불가능할 것으로 보이므로 X.X.X.X 버전 이후 관리 이렇게만 등록한다.

1. 에러 케이스 대응 방법

에러 발생 상황

• GitLab에 main 혹은 master 브랜치를 pull 할 경우 발생

예상 에러 원인

• GitLab에 설정 되어 있는 브랜치명과 로컬 레포지터리에 설정된 브랜치 명이 다를 경우

이전에는 기본이 master 였지만 윤리적으로 부적절하다고 여겨져 최근에는 main이 기본 브랜치 명으로 변경되었음에도 IDE(이클립스) 등에서는 과거 기본 브랜치명으로 레포지터리 명으로 설정하기 때문이다.

해결 방법

• 로컬의 브랜치 명을 GitLab의 브랜치 명으로 수정해 준다.(master -> main)

에러 발생 상황

• GitLab에 branch를 MergeRequest 진행 후 local의 main을 최신으로 반영하기 위해 Pull 할경우 발생

예상 에러 원인

• 위 상황과 동일

해결 방법

• 위 상황과 동일