2년전 나에게 - git으로 협업할래? (실습편)

A. 배경

블로그를 찾아주시는 분들도 아마 저처럼 “이론은 중요하지만, 결국 내가 맡은 첫 프로젝트의 테스크를 해결하기 위해 글을 읽으신 분이 많을 것” 이라고 생각합니다. 그래서 이번 글에서는 앞선 이론에서 다뤘던 내용을 직접 실습해보는 데 집중하려고 합니다. 물론, 이론을 이해하고 시작하면 훨씬 더 쉽게 다가갈 수 있기 때문에, 실습 편을 따라 하시기 전에 이론 설명도 꼭 한 번 읽어보시길 추천드려요. 단순히 따라하는 것과 원리를 알고 응용하는 것은 분명히 다르니까요.

이 글을 보시면 프로젝트 세팅과 기본적인 협업을 맛볼 수 있을것이라고 생각합니다.

이번 실습은 Git이 이미 컴퓨터에 설치되어 있다는 전제로 진행합니다. 혹시 아직 Git을 설치하지 않으셨다면, 먼저 설치부터 해 주세요.

B. Organization 세팅

1.Organization

GitHub 우측 상단 프로필 메뉴에서 Settings → Organizations로 이동합니다.

우측 상단의 New organization 버튼을 클릭합니다.

https://github.com/settings/organizations 탭에 들어가 위 화면의 New Organization을 누르면 됩니다.

Organization 정보를 입력합니다.

• Organization name: 조직 이름
• Contact email: 연락 가능한 이메일
• This organization belongs to: 개인 계정 혹은 비즈니스 중 선택
  
  이렇게 Organization 정보를 작성하면 됩니다.

멤버 초대

• Organization을 생성한 뒤, 상단 메뉴에서 People 탭을 선택합니다.
• Invite member 버튼을 클릭합니다.
• 초대할 사용자의 GitHub 이름, 이메일 등을 입력하여 멤버로 초대하면 됩니다.
  

만들고 나서는 People항목의 Invite Member로 초대하시면 됩니다.

2. Repository

직접 코드를 저장하고 관리할 Repository(저장소)를 만들어보겠습니다.

New Repository 선택

GitHub Organization 또는 개인 계정의 메인 페이지에서 "New Repository" 버튼을 클릭하세요.

• Repository 이름을 입력합니다.
• 필수 정보만 단순하게 입력해도 됩니다.
• 공개(public)/비공개(private) 여부를 선택할 수 있습니다.
  

옵션 설정 예시

아래와 같이 주로 사용하는 최소한의 설정만 선택해도 무방합니다.

• Repository name: 저장소 이름 (예: my-first-repo)
• Description: 저장소 설명 (필 optional)
• Public/Private: 노출 범위 선택
  

저는 보통 요렇게 만 설정을 하고 만듭니다.

Add a README file: 체크

• 이 옵션을 켜두면 저장소가 생성될 때 자동으로 README.md 파일이 포함되어 생성됩니다.
• 처음부터 "첫 커밋" 이 올라간 상태가 되어, 로컬에서 별도의 git init 없이 바로 git clone 명령으로 프로젝트를 내려받아 사용할 수 있습니다.

3. Template

레포지토리를 생성했다면, 이제 이슈(Issue)와 풀 리퀘스트(Pull Request)에 사용할 템플릿을 만들어 협업의 효율을 높일 수 있습니다.

템플릿 생성 방법

• Add File → Create new file로 새로운 파일을 추가합니다.
• 템플릿 관리와 자동 적용을 위해 .github 폴더를 생성합니다
  

폴더 및 파일 구조

• .github/ISSUE_TEMPLATE/: 이 안에 Issue에 사용할 템플릿 파일(.yml 혹은 .md)을 넣습니다.

• .github/pull_request_template.md: Pull Request에 사용할 템플릿 파일은 .github 폴더 바로 안에 만듭니다.

템플릿 작동 원리

• .github/ISSUE_TEMPLATE 폴더 내에 파일이 있으면 GitHub가 자동으로 감지해 이슈 등록 시 템플릿을 사용할 수 있도록 해줍니다.
• Pull Request 역시 .github 폴더 내의 pull_request_template.md를 자동으로 불러옵니다.
• 이 구조를 맞추면 GitHub가 저장소를 분석해, 새로운 이슈나 PR을 생성할 때 선택할 수 있는 템플릿 옵션을 제공합니다.

적용 화면

Issue 작성 버튼을 누르면, 아래와 같이 템플릿 리스트가 나타나 사용자가 원하는 양식을 골라 쓸 수 있습니다.

이렇게 템플릿을 만들어두면 협업에서 발생할 수 있는 의사소통 오류를 줄이고, 효율적으로 프로젝트를 이끌어갈 수 있습니다.
GitHub가 제공하는 템플릿 기능을 최대한 활용해보세요!

4. 코드 꼬임이 걱정된다면 — 브랜치 보호 규칙 활용하기

첫 협업 프로젝트에서는 실수로 잘못된 코드가 저장소에 합쳐져 버릴까봐 걱정이 많을 수 있습니다. 이런 불안감을 줄이기 위한 가장 확실한 방법은 브랜치 보호 규칙(Branch Protection Rule)을 설정하는 것입니다.

브랜치 보호 규칙 설정 방법

조직(Organization) 또는 저장소(Repository)에서
Settings → Branch → Add classic branch protection rule 메뉴로 이동합니다.

보호할 브랜치 지정 및 승인 절차(Approvals) 설정

• 예시) main 또는 develop 등 실제로 배포하거나 중요한 브랜치를 지정하세요.

• 브랜치명에 패턴(예: main, release/* 등)도 사용할 수 있습니다.

• "Require approvals before merging" 항목에서 몇 명의 리뷰어 승인이 필요한지 지정할 수 있습니다.

  예를 들어 "2"를 입력하면 적어도 두 명이 승인해야만 PR(Pull Request)이 병합됩니다.

이렇게 브랜치 보호 규칙을 활용하면, 첫 팀 프로젝트에서도 코드 꼬임에 대한 불안이나 실수 걱정을 획기적으로 줄일 수 있습니다. 무작정 코드가 섞이는 걸 방지하고, 모두가 검토한 코드만 합쳐진다는 경험을 직접 할 수 있을거에요.

C. 코드 올려보기

1. Clone

프로젝트의 실질적인 시작은 레포지토리를 자신의 컴퓨터로 복제(clone)하는 과정에서 시작됩니다.

레포지토리 주소 복사

• GitHub의 해당 레포지토리 페이지로 이동합니다.
• 화면 상단의 Code 버튼을 클릭하면 HTTPS 주소를 복사할 수 있습니다.
• 복사한 주소를 이후 명령어에 사용할 예정입니다.
  

빈 디렉토리 준비

• 터미널(명령 프롬프트)에서 작업할 공간을 만들면 프로젝트 관리가 편리합니다.
• 예를 들면, 홈 디렉토리에서 git이라는 폴더를 만들어 여러 프로젝트를 한 눈에 관리할 수 있습니다.

2. Issue 작성하기

이슈 템플릿 활용해서 Issue 등록

• GitHub 저장소의 Issues 탭에 들어가서, 미리 만들어둔 이슈 템플릿 중 원하는 양식을 선택합니다.
• 템플릿에 맞게 이슈 내용을 구체적으로 작성합니다.
• 이슈를 제출하면 해당 작업의 시작점이 됩니다.

이슈에서 브랜치 생성 (Create branch)

• 작성한 이슈 하단이나 우측에서 Create branch 버튼을 클릭합니다.
• 새 브랜치가 자동으로 생성되며, 브랜치와 이슈가 서로 자동으로 연결됩니다.
  이렇게 하면 추후에 해당 이슈를 통해 관련 브랜치 이력까지 한눈에 추적할 수 있어 프로젝트 관리가 쉬워집니다.

브랜치 네이밍 규칙

• 브랜치 이름은 팀 내 약속에 따라 통일하면 좋습니다.
• 일반적으로는 feature/이슈번호-작업내용 또는 fix/이슈번호-수정내용 형태가 많이 활용됩니다.

IDE에서 작업 브랜치로 이동

• 터미널에서 최신 브랜치 정보를 받아오기 위해 fetch 명령어로 받아올 수 있습니다.
• checkout을 통해 해당 브랜치로 이동합니다.

• 이슈 기반 브랜치 전략을 쓰면, 누가 어떤 작업을 맡았는지 명확하게 관리할 수 있어 협업 프로젝트에 특히 유용합니다.
• 브랜치와 이슈가 자동으로 연결되므로, 코드 리뷰, 변경 내역 추적, PR 작성까지 일련의 작업이 훨씬 체계적으로 흘러갑니다.

3. 코드 올리기 (add commit push)

코드를 작업한 뒤 GitHub에 올리는 전 과정을 Jetbrains IDE의 GUI 기반으로 설명합니다. 초보자를 위해 최대한 gui를 통한 작업을 소개해드리려고 합니다.

변경사항 확인

• 파일을 수정하면 IDE 좌측 Commit(커밋) 패널에 변경된 파일이 파란색 등으로 표시됩니다.
• 이 패널에서 어떤 파일이 수정되었는지 한눈에 확인할 수 있습니다

커밋할 파일 선택 및 커밋 메세지

• 올리고 싶은(커밋하고 싶은) 파일의 체크박스를 선택합니다.
• 여러 파일을 한 번에, 또는 일부만 선택해서 커밋할 수 있습니다.
• 아래 입력창에 간결하고 명확한 커밋 메시지를 작성합니다.
  예: "로그인 폼 레이아웃 수정", "README 추가" 등.
• Commit 버튼 클릭 후, 이어서 Push 버튼을 클릭하면 방금 만든 커밋이 내 이슈 브랜치의 원격 저장소(GitHub)에 업로드됩니다

• 이렇게 하면 별도의 터미널 명령어 입력 없이, GUI 기반으로
  add → commit → push 전체 과정을 마칠 수 있습니다.
• 초보자도 실수 없이, 변경한 내용을 팀원들과 안전하게 공유할 수 있게 됩니다.

4. Pull request

작업한 내용을 공유하고, 코드 리뷰를 받기 위해서는 Pull Request (PR)를 만들어야 합니다. PR은 협업 과정에서 가장 중요한 과정 중 하나로, 내 작업물을 다른 사람과 검토하고 합치는 단계입니다.

IDE에서 PR? 저는 GitHub에서 합니다

JetBrains IDE (예: IntelliJ, WebStorm 등)에서도 왼쪽 메뉴에 Pull Request 항목이 존재하지만,
👉 글자가 작고 불편해서 저는 GitHub 웹 사이트에서 직접 PR을 생성하는 방식을 선호합니다.

GitHub에서 PR 생성하기

• GitHub 저장소의 "Pull Requests" 탭으로 이동합니다.
• GitHub는 자동으로 내가 작업한 브랜치 중 현재 PR 대상이 될 수 있는 브랜치 목록을 보여줍니다.
• 해당 브랜치에서 변경된 내용을 기준으로 PR을 생성하라는 추천 정보가 뜨기도 합니다.

만약 추천 목록이 보이지 않아도 걱정 마세요!
"New pull request" 버튼을 클릭하면 수동으로 브랜치를 지정하여 PR을 만들 수 있습니다.

PR 템플릿 작성 및 이슈 연결

• 이전에 만들었던 PR 템플릿이 자동으로 입력됩니다.
• 템플릿에 따라 변경 내용을 차근차근 정리하고, 설명을 작성해주세요.
• 이때 #이슈번호 형태로 작성하면 자동으로 이슈와 PR이 연결됩니다.
  예시: Fixes #23 또는 Closes #10
  이렇게 해두면 해당 PR이 머지될 때 이슈가 자동으로 닫히기도 하며,
  "어떤 이슈를 해결하는 PR인지 명확하게 드러나서 협업에 도움이 됩니다.

D. 내 코드를 main 최종에 합치기

Pull Request를 만든 뒤에는 곧바로 main 브랜치(혹은 상위 브랜치)로 머지할 수 있어야 하지만,
앞서 설정한 브랜치 보호 규칙(Approvals 설정) 덕분에 PR을 바로 머지할 수 없도록 잠겨 있는 상태가 됩니다.

이 방식은 초보자들이 실수로 코드를 바로 머지하는 일을 방지하고, 꼭 검토(리뷰)를 거치도록 만들어주는 안전 장치 역할을 합니다.

1. 코드 리뷰 (Code Review)

화면의 "Files changed" 탭에 들어가면 변경된 코드들을 한눈에 볼 수 있습니다.

• 코드 옆 줄번호에 마우스를 올리면 “+” 버튼이 나타납니다.
• 이 버튼을 누르면 해당 줄에 리뷰 코멘트를 남길 수 있습니다.
  

💡 리뷰를 통해 코드의 개선 사항이나 이해되지 않는 부분을 질문하거나, 의견을 나눌 수 있어 협업의 퀄리티를 높여줍니다.

2. Approve

문제가 없다고 판단되면 리뷰어는 "Approve" 버튼을 클릭해 PR을 승인합니다.

• 승인되지 않은 PR은 머지가 잠겨 있으므로, 반드시 리뷰 → approve 과정을 거쳐야 합니다.

위와 같이 Merge 버튼이 활성화되면서 머지할 수 있는 상태가 됩니다.

3. merge 하기

Merge pull request" 버튼을 눌러 작업한 내용을 main 브랜치에 병합하세요.

• 이로써 내가 만든 기능 또는 수정사항이 공식 브랜치(main)에 반영됩니다.
• 옵션에 따라 Squash and merge, Rebase and merge 등을 선택할 수도 있습니다. (기본은 일반 Merge)

E. 마무리

처음엔 많이 서툴고, 뭐가 뭔지 몰라 망설였던 것도 사실이었죠.
하지만 하나씩 직접 따라 해보니, 생각보다 금방 익숙해지더라고요.

“완벽하게 다 알고 시작해야 할까?” 고민하지 말고, 그냥 한 번 해본다는 마음으로 도전하세요.
에러도 겪고, 새로운 것도 부딪히다 보면 금세 자신감이 붙고 협업도 더 즐거워질 거예요.

실습을 쓰는 블로그는 처음이여서 글이 서투른것 같습니다. 다음에는 더 개선해서 써보겠습니다...