[강의] 개발자스럽게 Github 사용하기

 

 

 

 

 

 

 

 

 

https://www.boostcourse.org/cs103

개발자스럽게 Github 사용하기

 

 

부스트캠프 방학동안 봐야할 깃 강의 중 하나

주요 개념들 자료들 찾아서 보기 번거로우니 참고할 용도로 간단하게 정리했다

 

 

 

 

 

 

 

 

---

 

 

 

 

브랜치 전략, Flow

 

Flow, Git을 사용하면서 Branch를 어떤 식으로 사용할지에 대한 전략

 

 

Local 중심 Git flow

• 주로 로컬 저장소에서 브랜치를 중심으로 한 개발 흐름
• 주요 브랜치로는 main(master), develop, release, feature, hotfix 등이 존재
• 위의 브랜치들과 같이 목적에 따라 다양한 브랜치를 사용하는 전략
• 관리해야할 브랜치가 많고, 배포하기까지 많은 단계가 필요해 다소 개발속도는 느릴 수 있으나 배포 안정성 높음

 

 

 

main (master)

• 배포의 기준이 되는 브랜치, Release Tag를 기록
• main 브랜치에 직접 commit을 하거나 develop, release 브랜치가 아닌 브랜치에 merge 하면 안됨

develop

• 개발 중심 브랜치
• 배포 버전별 정의된 기능을 구현하여 develop 브랜치에 모음
• 코드 배포시 develop 브랜치로부터 release 브랜치를 만들어 준비
• 실제 기능 구현은 develop 브랜치가 아닌 feature 브랜치에서 진행

feature

• 실제로 기능 구현하는 브랜치
• 기능 구현, 버그픽스, 리팩토링 등을 수행하기 위해 develop 브랜치로부터 브랜치를 만들어 작업 수행
• feature 브랜치에서 작업이 완료된 경우 develop 브랜치에 merge 진행

release

• 배포 준비하는 브랜치
• develop 브랜치에서 배포를 위한 개발이 끝나면, release 브랜치를 만들어 배포 준비
• release 브랜치에서는 bugfix 및 추가적인 리팩토링을 진행, 추가된 작업은 develop 브랜치에도 반영
• 배포 준비 완료시 main 브랜치로 merge 진행

hotfix

• 배포가 완료된 버전 (main 브랜치) 에서 심각한 버그나 문제가 발생했을 때 사용하는 브랜치
• main 브랜치에서 hotfix 브랜치를 만들어 문제를 해결한 후 필요한 브랜치들에 merge

 

 

 

 

Remote 중심 Github flow

• 리모트 저장소, Github에서의 작업 흐름을 중심으로 함
• Git Flow 에 비해 더 빠른 속도와 개발 및 배포가 가능하지만, 배포 관리가 어려울 수 있음
• 주로 main 브랜치와 feature 브랜치로 구성됨
  • main 브랜치 : Git Flow의 main, develop, release 브랜치의 역할이 합쳐진 형태
  • feature 브랜치 : Git Flow의 feature, hotfix 브랜치의 역할이 합쳐진 형태
• Git Flow와 달리 develop, release 브랜치처럼 배포 준비를 위한 브랜치가 따로 없기에 main 브랜치에 merge하는 작업은 늘 조심해야함

 

 

 

 

---

 

 

 

 

Commit 메시지 양식

 

Commit Convention

• Commit을 남기는 규칙
• 일관성 있는 Commit Log를 통해 다른 사람들의 작업 내용을 더 쉽게 파악 및 유지보수
• Header, Body, Footer로 구성됨 (Body, Footer는 선택적으로 사용)

 

 

Subject

• Commit Log 제목을 나타내는 부분
• 50자 넘기지 않음 / 대문자 / 마침표 사용X / 과거 시제 X / 명령문
  ex) Added(x), Add(o)
• 일반적으로 Subject에는 Prefix로 Type이 붙음. Type 뒤에 작업의 대략적인 내용 추가
  • feat(새로운 기능), refactor(리펙토링), fix(버그수정), style(코드 포멧팅 또는 주석처리), chore(빌드 수정, 패키지 관리자수정), tests(테스트 코드), docs(문서 작업) 등

 

Body

• 작업에 대한 상세 기록
• 따로 포맷이 존재하지 않으나 Subject와 Body 구분으로 한칸 공백을 둠
• 필수는 아님. 그러나 Subject로 설명이 힘들 경우 Subject를 더 간략하게 작성하고 Body에 내용 추가

 

Footer

• 해당 작업과 관련된 Issue의 Tag 기록
• Commit Log에 Issue Tag 남기면 Github에서 자동으로 해당 태크를 인식하여 Issue에 관련된 Commit을 연결
• Issue, Commit 양방향으로 참고하기에 작업 History 관리 목적으로 사용
• IssueTag 는 #{Issue번호}로 작성

 

 

Pre-commit

• 코드 커밋 전 정해진 로직(hook)를 자동으로 실행
  • 코드 포맷팅 : 코드의 일관된 스타일 유지를 위한 포맷팅
  • 정적 분석 : 코드에서 잠재적인 버그, 보안 취약점, 코드 품질 문제 확인
  • 테스트 실행 : 자동화된 테스트 실행하여 새로 추가되거나 수정한 코드가 기존 로직에 영향을 주진 않는지 확인
  • 의존성 관리 : 코드에 필요한 모든 라이브러리 의존성 확인

 

 

 

---

 

 

 

Issue

• Issue란 개발 작업 단위, 작업의 History를 관리하기 위해 작성하는 것이 좋다
• Issue로 Commit Convention과 비슷하게 앞에 Type을 붙여준다
  ex) [FEAT] / [BUG] / [REFACTOR]
• 먼저 작업할 사항이 있다면 Issue로 내용 등록, 각 Issue에 맞는 feature 브랜치를 생성하여 작업 진행
• 여기서 feature 브랜치를 생성할 때 브랜치 명에 Issue Tag 붙이면, Local에서 각 브랜치를 식별하기 좋아짐
  ex) feat-3/branch-name (3번 Issue를 해결하는 기능 구현 브랜치

 

 

• Issue는 깃헙 레포의 Issues 란에서 New issue로 생성 가능
• 오른쪽 설정들을 통해 담당자, 라벨, 프로젝트 등을 지정 가능
• Issue에는 왜 이 작업을 해야하고, 어떤 작업을 할 것인지, 관련된 다른 이슈나 작업이 있는지 등을 기록해야 하는데 Issue Template을 통해 간편하게 작성 가능하다
• Issue의 종류로는 대표적으로 Feature Request, Bug Report 등이 존재

 

 

 

• 기존의 템플릿을 사용해도 되고 각 프로젝트, 작업에 따라 필요한 템플릿을 만들어서 사용 가능
• 보통 프로젝트 초기 세팅으로 진행하면 main 브랜치에 직접 추가한다

 

 

 

https://logan-mle.notion.site/2-Github-Issue-1b6bab3523a74e8aa4e83cf6668abbcf

2. Github Issue 기반으로 개발하기 | Notion

 

 

실습은 해당 강의 자료 참고

강의에서는 터미널 명령어를 사용한 것과 달리 VSCode에서 Git Graph를 사용했지만 큰 차이는 없다

 

 

임의의 간단한 이슈를 생성 후 로컬에서 main.py 생성하여 추가 후 커밋, 푸시했을 때 위에 표시한 부분처럼 커밋이 이슈와 연동되어 히스토리로 남는 것을 확인할 수 있다

여기서 커밋할 때 주의할 부분은 작업하고자 하는 이슈의 해당 태그 번호를 잘 확인하고 태깅해야 한다는 것

feat: Add add function #2

이런 식으로 커밋을 남길 때 이슈 태깅을 잘 해줘야한다

 

 

 

 

 

---

 

 

 

 

 

Pull Request

• 보통 PR이라 부르는 Pull Request는 다른 브랜치로 Merge 작업을 진행하기 전 팀원에게 코드 리뷰를 받는 단계이다
• 강의에서는 작업 개요, 변경된 부분, 참고 사항, 관련 이슈 등으로 구성되어 있는데 이런 내용과 템플릿은 회사와 팀마다 차이가 존재할 수 있다
• 상세 내용은 강사님 자료 참고

 

https://logan-mle.notion.site/3-Github-Pull-Request-d26cb4a1623f42c0a73fa34ae4e29ed4

3. Github Pull Request를 통해 코드 리뷰 받기 | Notion

 

• 간단하게 정리해보면
  • PR때 사용할 템플릿을 .github 디렉토리에 추가 (깃허브에서 main 브랜치에 직접 추가할 수도 있고 로컬에서 추가할 경우 main 브랜치에서 생성 후 커밋 및 푸시해줄 것)
  • 이전에 Push 후 main에 병합되지 않은 feature 브랜치를 깃허브에서 Compare & pull request를 클릭한다
  • 추가한 PR 템플릿에 작업 내용 등을 작성 후 Create pull request. 리뷰어 및 담당자, 라벨 등을 설정해준다
  • 정상적으로 진행되었다면 아래처럼 이슈와 작업 내용 사항들을 확인하며 리뷰를 시작한다

 

• Issue Tags에서 특정 키워드와 Issue Tag를 작성하면 자동으로 Issue가 닫히게끔 처리할 수 있다
• close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved

 

 

 

리뷰 시 comment와 review로 리뷰를 남길 수 있다

• Add single comment
  • 남긴 코멘트를 바로 보여주는 방식, 메세지 하나하나를 개별 리뷰로 남긴다
• Start a review
  • 여러 코멘트를 남기고 코멘트를 모아서 한번에 리뷰 메세지와 함께 보여주는 방식

 

 

이렇게 코드에 대해 남겨주는 내용들을 보면서 다시 수정해서 업데이트를 반복하고 조건이 만족되었다면 Merge를 진행한다

코드를 Merge 할 때 3가지 방법이 있다

 

• Create a merge commit - Merge Commit을 남기고 코드를 Merge
  • 브랜치에서 발생한 Commit Log + Merge Commit
• Squash and merge - 브랜치 내에 추가된 모든 Commit을 하나의 Commit으로 Squash 하고 코드를 Merge
  • 브랜치에서 발생한 Commit Log를 합친 하나의 Commit
• Rebase and merge - 브랜치를 대상 브랜치와 Rebase 후 Merge
  • 브랜치에서 발생한 Commit Log

 

Pre-commit 적용

 

https://logan-mle.notion.site/4-Pre-commit-cf428cdc8dce441887b6790de5a42319

4. Pre-commit 으로 코드 포맷팅 자동화 하기 | Notion

 

추가로 위에 commit 메세지 양식 부분에서 pre-commit에 대한 설명이 있었는데 여기에 대한 실습도 있어서 같이 진행해보았다

해당 페이지에서 잘 설명되어 있으니 자세한 내용을 서술하진 않고 간단히만 정리

• pre-commit 추가한다는 이슈 생성
• 해당 기능 구현을 위한 로컬에서 feature 브랜치 생성
• pre-commit 설치 (pip install pre-commit)
• pre-commit config 설정 
  • 터미널에서 pre-commit sample-config > .pre-commit-config.yaml 실행하면 샘플 config yaml 생성됨
  • 공백 제거, end-of-file 검사, yaml 검사, 대용량 파일 검사 등이 기본 hook으로 설정
• pre-commit autoupdate 명령어로 설정된 hook들 업데이트
• pre-commit install 명령어로 현재 프로젝트에 pre-commit 설치
  이제 프로젝트에서 commit을 수행할 때마다 정의된 hook들이 실행된다
• 실습에서는 터미널에서 커밋을 하기 때문에 pre-commit 초기화와 정의된 hook들이 실행되는 내역들이 출력되지만 vscode의 깃 그래프로 커밋할 경우 출력이 나오는대신 커밋과 pre-commit 작업들이 진행되기에 좀 더 오래 걸린다
• 기존 코드에 pre-commit 적용
  • pre-commit run --all-files 명령어로 전체 파일을 검사 및 수정

이렇게 하면 이슈에 커밋들이 연결되어 히스토리가 남고 푸시한 feature 브랜치에 대해서 PR을 진행하여 코드 리뷰, Merge하면 pre-commit까지 적용하는 실습을 마치게된다

 

 

 

 

 

---

 

 

 

 

 

Tag

• 특정 커밋에 대한 표시
• 특정 시점에서 코드가 안정화되거나 특별한 이벤트가 발생했을 때 특정 커밋에 태그를 지정하여 해당 시점을 기록
• 주로 버전 번호와 사용, 일반적으로 출시된 버전에 대한 태그를 지정
  • Lightweight Tag : 버전만을 기록하는 Tag
  • Annotated Tag : 태그를 생성한 유저, 이메일, 태그 생성 날짜, 태그 메시지 등을 함께 기록하는 Tag

 

Semantic Versioning

• 소프트웨어 버전 관리를 위한 표준방법론 중 하나, 주로 오픈 소스 프로젝트에서 널리 사용됨
• 버전 번호 부여를 통해 소프트웨어의 변경 사항을 명확히 하고, 버전 간 호환성 관리에 도움을 줌
• 시맨틱 버전 형식 : MAJOR.MINOR.PATCH
  • MAJOR : 주 버전 번호 / 하위 호환성이 없는 변경 사항이 있을 때 증가 / 주로 큰 기능의 추가, 기존 기능 변경이 있을 때 증가
  • MINOR : 부 버전 번호 / 하위 호환성 유지하면서 기능 추가될 때 증가 / 주로 새로운 기능 추가시 증가
  • PATCH : 패치 번호 / 기존 기능에 대한 버그 수정 등 하위 호환적 변경 사항 있을 시 증가

 

Tag 생성 및 명령어

• git tag <tagname> 으로 태그 생성
  -a 옵션으로 Annotated Tag 생성
• git tag : 생성된 태그 확인
• git show <tag name> : 태그 상세 내용 확인
• git push origin <tag name> : Tag를 깃헙에 업로드
• git log : 현재 commit에 tag 등록된 것 확인

 

 

Release

• 특정 태그를 기반으로 한 공식적인 배포를 나타냄
• 생성한 태그를 기반으로 깃헙에서 Release 버전을 기록할 수 있음
• 릴리즈 페이지를 통해 사용자에게 새로운 버전의 소프트웨어를 제공하고, 해당 버전에 대한 변경 사항 및 릴리즈 노트 제공

 

 

 

 

Git Tag 및 Github Release 생성

 

https://logan-mle.notion.site/5-Git-Tag-Github-Release-255e7e0b6ab849e09924cf7733e0b8fb

5. Git Tag & Github Release 생성하기 | Notion

 

• git tag v0.1.0 명령어로 초기 버전 작성
• git push origin v0.1.0 으로 생성한 Git Tag를 Github Repo로 푸시

C:\Users\userpc\Downloads\git_study\WORK1\git-study2>git push origin v0.1.0
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://github.com/bbonghag/git-study2.git
 * [new tag]         v0.1.0 -> v0.1.0

 

아래 저 부분을 눌러서 태그를 확인할 수 있다

 

 

 

• 주의할 점으로는 vscode 깃 그래프 GUI로 작업하는 걸로 푸시하면 해당 태그가 레포에 푸시되지 않는다
• 간단한 커밋, 푸시와 풀 정도는 GUI의 단축키로 사용하되 결국에는 터미널로도 작업할 줄 알아야한다
• 모든 명령어까지 다 정리하기엔 내용이 너무 많기에.. 주요 명령어 위주로만 간단하게 정리

 

 

 

• 위에 오른쪽 Release 부분에서 아래에 Create a new release 를 누르면 아래와 같은 창이 나온다
• Tag를 눌러보면 이전에 등록한 v0.1.0을 선택, Generate release notes를 누르면 제목과 내용들을 자동으로 작성해준다
• 자동 작성할 경우 이전 Release와 현재 Release 사이에 추가된 Pull Request의 이름이 포함된다
• 맨 아래 Publish release 누르면 Release 생성 완료

 

 

 

---

 

 

Github Action

• Github에서 제공되는 소프트웨어 개발 워크 플로우
• Github Repo에서 빌드, 테스트, 배포와 같은 다양한 작업을 YAML 파일로 정의할 수 있다

 

 

구성 요소	설명	예시
Workflow	자동화 전체 단위를 정의하는 YAML 파일. Job과 Step들로 구성됨 .github/workflows/ 폴더에 위치.	ci.yml, deploy.yml
Event (Trigger)	Workflow가 실행되는 계기(트리거).  ex) push, pull_request, issue 등	on: push, on: pull_request
Job	Workflow 안에서 실행되는 작업 단위. 각 Job은 독립적인 Runner 환경에서 실행.	jobs: build:
Runner	실제 Job을 실행하는 서버 환경 (머신). GitHub-hosted(기본 제공) 또는 Self-hosted 가능.	runs-on: ubuntu-latest
Step	Job 안의 단계 단위 명령어 또는 Action 실행 단위.	steps: - name: Checkout code
Action	재사용 가능한 작업 단위(모듈). Step 안에서 실행되며, Marketplace에서 가져오거나 직접 작성 가능.	uses: actions/checkout@v4
Command (run)	Action 대신 직접 명령어 실행. Shell 명령어를 바로 수행.	run: npm install
Artifact	Job 간 또는 Workflow 간 데이터를 공유·보존할 수 있는 파일.	테스트 결과, 빌드 파일 등
Secret	민감한 데이터(API 키, 토큰 등)를 암호화 저장 후 환경 변수처럼 사용.	{{ secrets.GITHUB_TOKEN }}
Matrix	여러 환경(예: OS, Python 버전 등)에 대해 병렬 Job 실행.	strategy: matrix: os: [ubuntu, windows]
Environment / Context	Workflow 내부에서 참조 가능한 메타데이터, 변수 정보 집합.	{{ github.ref }}, {{ env.VARIABLE }}

 

 

 

대부분 그렇지만 직접 실습해보는게 베스트

아래 자료 참고

 

https://logan-mle.notion.site/6-Github-Action-Workflow-50377538a9734bd0a28765deaa659417

6. Github Action Workflow 자동화 하기 | Notion

 

 

해당 실습 내용은 너무 많아서 다 정리는 못하고 대신 중간에 이슈가 발생했다

이전의 실습 부분과 현재 진행중인 내용이 충돌해서 발생한, 꽤나 유의미한 문제라 끄적이기..

 

 

상황은 Pytest Workflow를 추가하려는 상태

 

로컬에서 새로운 feature 브랜치 하나 파서 실습 내용대로 쭉 진행하고 커밋! 푸시!! PR까지!!

그러나 그 중 requirements.txt를 빠뜨려서 아래의 에러가 발생한다

 

requirements.txt를 만들고 다시 푸시 -> 아 pytest 작성을 또 까먹어서 에러 발생..

 

 

 

 

그래서 requirements.txt에 pytest를 추가하고 다시 커밋하려는데 아래의 이슈가 발생했다

> git -c user.useConfigOnly=true commit --quiet --allow-empty-message --file - --allow-empty-message
trim trailing whitespace.................................................Passed
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing requirements.txt

check yaml...........................................(no files to check)Skipped
check for added large files..............................................Passed
black................................................(no files to check)Skipped

 

뭔소리고...

 

 

 

fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook

Fixing requirements.txt

 

• 이 부분이 핵심. pre-commit의 hook이 실행되었는데 Failed이라 뜬다
• end-of-file-fixer 훅이 requirements.txt 파일을 자동으로 수정했다는 뜻
• 구체적으로는 “파일 끝에 newline(개행문자)”이 없어서 pre-commit이 자동으로 추가한 것

이렇게 되었을 때 스테이지에는 수정되지 않은 requirements.txt가 올라가있고 수정된 requirements.txt가 또 존재한다

수정되지 않은  requirements.txt 는 내리고 수정된 requirements.txt를 스테이지에 올려서 다시 커밋하면 정상 동작한다!!

저 수정안된 파일 그대로 둔 채로 커밋하면 동일한 커밋 중단이 계속 발생하니 주의할 것 

 

 

정리하자면

• pre-commit은 커밋 전에 코드 포맷, 스타일 등을 검사하고 수정하는 툴
• end-of-file-fixer 훅은 모든 파일의 끝이 반드시 개행 문자로 끝나도록 강제한다
• 실패(Failed)로 표시된 건 에러가 아니라, 수정이 이루어졌다는 뜻
  → requirements.txt를 자동 수정했고, 커밋은 멈췄음.

 

 

 

휴 정상 동작 완료..

 

 

 

추가로 확인해보면 좋은 workflow 예제들

Github Release Drafter Workflow

- main 브랜치에 코드가 Merge 되면 자동으로 Git Tag 및 Release Drafter를 생성하는 Workflow

- 추후 자동 배포 파이프라인(CD, Continuous Deployment)에서 Release가 Publish 되는 것을 감지하여 배포되도록 할 수 있습니다.

- 설명은 https://jiyeonseo.github.io/2022/10/15/github-action-release-drafter/ 를 참고하세요.

 

Google Cloud Platform Cloud Run 배포 Workflow

- main 브랜치에 코드가 Merge 되면 GCP Cloud Run으로 배포하는 Workflow

- Docker Image Build → GCR Docker Image Push → Cloud Run Deploy

- 설명은 5.2. CI/CD Workflow 추가하기 를 참고하세요.

- https://github.com/Ilevk/fastapi-tutorial/blob/main/.github/workflows/cd_workflow.yaml

 

요건 나중에 한번 해보면 좋을 것 같아서 가이드에 있는 내용 그대로 가져왔다

두 번째 예제, GCP는 아니지만 이전 Azure 교육 들으면서 레포에 코드 푸시될 경우 Docker Image Build -> Azure Container Registry Push -> ArgoCD로 AKS 이미지-컨테이너 배포까지 작업했던 적이 있는데 기록했던 내용들 블로그 글로 정리해야겠다

 

 

 

 

 

---

 

 

Readme

• Github Repository에 들어갔을 때 만나는 가장 첫 페이지이자 프로젝트의 얼굴
• Markdown 문법에 따라 작성시 Github 페이지에서 자동으로 렌더링되어 보여진다
• 프로젝트에 대한 간략한 소개 및 설명, 목적, 사용 방법, 설치 방법 등 사용자가 프로젝트를 쉽게 이해하고 시작할 수 있도록 가이드를 작성한다
• 양식이 따로 정해져있는 것은 아니지만 기본적인 구성 요소들이 추가되어 있으면 좋다
  • 프로젝트 소개 : 프로젝트의 목적과 내용을 간략하게 설명. 어떤 프로젝트인지 소개하고 사용된 기술 스택 및 환경
  • 설치 및 사용 방법 : 사용한 언어와 버전, 설치하는 방법과 커맨드 또는 스크립트
  • 기능 및 예시 : 프로젝트에 포함된 모듈의 기능과 대표적인 설명, 예시. 실행 커맨드나 사용 방법
  • 라이선스 정보 : 해당 프로젝트의 사용 범위를 알려줌 (MIT, Apache, GPL, BSD)
  • 기여 방법 : 오픈 소스일 경우 중요. 프로젝트에 기여하는 방법에 대한 안내

 

 

https://logan-mle.notion.site/7-Readme-27ceda4576aa482297472338a2d755c0

7. Readme 작성하기 | Notion

 

 

 

 

 

실습 가이드 따라 쭉 진행하면 위와 같은 결과가 나온다

리드미는 웹의 깃헙에서도 직접 수정 가능하다

 

 

 

 

---

 

 

 

지금까지 깃 관련 강의 2개를 연달아보면서 여러가지 공부 및 실습을 진행해보았다

아래 강의로 VSCode에서 깃을 다루는 전반적인 기능을 확인하였고 이번 강의를 통해 직접 실습해보니까 어렴풋이만 알고 있던 깃과 깃허브에 대해 많이 배우게 된 좋은 기회였다

 

 

https://www.boostcourse.org/cs102

Github으로 따라하는 버전 관리