이제 하나의 흐름으로 연결하자
GitHub를 제대로 익히는 가장 좋은 방법은 작은 프로젝트를 끝까지 운영해 보는 것입니다. 명령어를 외우는 것보다 중요한 것은 "어떤 순서로 일하는가"입니다. 저장소를 만들고, 이슈로 할 일을 정리하고, 브랜치에서 작업하고, Pull Request로 검토하고, 자동 검사 후 병합하는 흐름을 한 번 경험하면 GitHub가 훨씬 선명해집니다.
이번 장에서는 개인 포트폴리오 웹사이트를 예시로 진행합니다. 코드가 어렵지 않고, 공개해도 부담이 적으며, GitHub Pages로 바로 배포할 수 있기 때문입니다. 초보자는 처음부터 큰 앱을 만들기보다 작고 관심 있는 주제로 시작하는 것이 좋습니다.
프로젝트 주제와 저장소 구조 정하기
예시 프로젝트 이름은 my-profile-site입니다. 목표는 단순합니다.
나를 소개하는 웹페이지 만들기
README에 프로젝트 설명 작성하기
GitHub Actions로 PR 검사하기
GitHub Pages로 배포하기
Release로 첫 버전 기록하기
처음 저장소를 만들 때는 GitHub에서 다음처럼 설정합니다.
Repository name:
my-profile-siteVisibility:
PublicAdd a README file: 체크
Add .gitignore: 필요하면 선택, 정적 HTML만 쓴다면 없어도 됨
License: 공개 프로젝트라면 목적에 맞게 선택
라이선스는 "공개 저장소이니 아무거나 고르면 되는 항목"이 아닙니다. 학습용 공개 프로젝트라면 MIT License처럼 널리 쓰이는 라이선스를 선택할 수 있지만, 회사 코드나 중요한 서비스 코드라면 조직 정책을 먼저 확인해야 합니다.
초기 파일 구조는 아래처럼 단순하게 시작합니다.
my-profile-site/
├─ README.md
├─ index.html
├─ style.css
├─ docs/
│ └─ learning-log.md
└─ .github/
└─ workflows/
└─ pr-check.ymlREADME.md에는 이 저장소가 무엇인지 먼저 적습니다. GitHub도 좋은 저장소를 만들기 위한 기본 요소로 README, 라이선스, 기여 가이드 같은 문서를 강조합니다.1
# My Profile Site
개인 소개와 GitHub 학습 기록을 담은 포트폴리오 웹사이트입니다.
## 주요 내용
- 자기소개
- 학습한 기술 목록
- GitHub 실습 기록
- 배포 링크
## 배포 주소
추후 GitHub Pages 주소를 추가합니다.여기서 중요한 점은 완벽한 결과물을 만들려 하지 않는 것입니다. 이 프로젝트의 목적은 멋진 디자인보다 실무 흐름을 끝까지 경험하는 것입니다.
Issue로 할 일을 먼저 정의하기
실무에서는 코드를 바로 수정하지 않습니다. 먼저 해야 할 일을 Issue로 남깁니다. Issue는 "왜 이 작업을 하는지"를 기록하는 공간입니다.
다음과 같이 4개의 Issue를 만들어 봅니다.
#1 README에 프로젝트 소개 작성
#2 메인 페이지 기본 화면 만들기
#3 PR 자동 검사 GitHub Actions 추가
#4 GitHub Pages 배포와 첫 Release 작성Issue 본문은 짧아도 됩니다. 대신 완료 조건을 분명히 적습니다.
## 목적
프로젝트를 처음 보는 사람이 저장소의 목적을 이해할 수 있게 한다.
## 작업 내용
- README에 프로젝트 소개 추가
- 주요 기능 목록 작성
- 배포 주소 영역 추가
## 완료 조건
- README만 보고 프로젝트 목적을 알 수 있다.이렇게 하면 나중에 커밋, PR, 병합 기록이 모두 "어떤 일을 해결했는지"와 연결됩니다.
브랜치에서 작업하고 커밋하기
이제 Issue 하나를 선택해 브랜치를 만듭니다. 예를 들어 #1 README에 프로젝트 소개 작성을 작업한다면 브랜치 이름을 이렇게 정합니다.
git switch -c feature/1-readme브랜치 이름에 Issue 번호를 넣으면 추적하기 쉽습니다.
작업 후에는 변경 사항을 확인합니다.
git status
git diff문제가 없다면 스테이징하고 커밋합니다.
git add README.md
git commit -m "docs: add project introduction"커밋 메시지는 길 필요가 없습니다. 대신 무엇을 했는지 드러나야 합니다.
좋은 예시는 다음과 같습니다.
docs: add project introduction
feat: add profile home page
ci: add pull request check workflow
fix: correct broken README link작업한 브랜치를 GitHub에 올립니다.
git push -u origin feature/1-readme이제 GitHub에서 Pull Request를 만들 준비가 끝났습니다.
Pull Request로 변경 사항 제출하기
Pull Request는 브랜치에서 만든 변경 사항을 main 브랜치에 합쳐 달라고 요청하는 과정입니다. GitHub 공식 문서도 PR을 "변경 사항을 제안하고 협업하는 방법"으로 설명하며, 기본 브랜치에는 완료되고 승인된 작업만 남기도록 돕는다고 설명합니다.2
GitHub 저장소에 들어가면 Compare & pull request 버튼이 보입니다. 클릭한 뒤 다음처럼 작성합니다.
## 요약
README에 프로젝트 소개와 주요 내용을 추가했습니다.
## 변경 내용
- 프로젝트 목적 추가
- 주요 내용 목록 추가
- 배포 주소 영역 추가
## 확인 방법
- README.md를 열어 내용이 자연스러운지 확인합니다.
Closes #1Closes #1처럼 적으면 PR이 main에 병합될 때 관련 Issue가 자동으로 닫힙니다. 이것이 작업 추적과 코드 변경을 연결하는 가장 기본적인 방법입니다.
PR을 만들기 전에는 스스로 한 번 확인합니다.
파일이 너무 많이 바뀌지 않았는가?
Issue의 완료 조건을 만족하는가?
설명만 보고 리뷰어가 이해할 수 있는가?
불필요한 임시 파일이 포함되지 않았는가?
GitHub의 초보자용 PR 가이드에서도 작은 PR을 만들고, 제출 전 직접 검토하고, 명확한 설명을 쓰는 습관을 권장합니다.3
리뷰 코멘트를 받았다고 가정해 봅시다. 예를 들어 "배포 주소는 아직 없으니 예정이라고 표시해 주세요"라는 코멘트가 달렸다면 같은 브랜치에서 수정합니다.
git add README.md
git commit -m "docs: clarify deployment link status"
git push추가 커밋은 기존 PR에 자동으로 반영됩니다. 이 과정을 통해 PR은 단순 제출물이 아니라 대화와 개선의 공간이라는 것을 체험하게 됩니다.
PR마다 GitHub Actions 실행하기
이번에는 PR이 열릴 때마다 자동 검사를 실행해 봅니다. GitHub Actions 워크플로우는 저장소의 .github/workflows 폴더에 YAML 파일로 정의합니다. 워크플로우는 push, pull_request 같은 이벤트가 발생할 때 자동으로 실행될 수 있습니다.4
feature/3-pr-check 브랜치를 만들고 다음 파일을 추가합니다.
git switch -c feature/3-pr-check
mkdir -p .github/workflows.github/workflows/pr-check.yml 파일을 만듭니다.
name: PR Check
on:
pull_request:
branches: [main]
jobs:
basic-check:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Check required files
run: |
test -f README.md
test -f index.html
test -f style.css
- name: Check README content
run: |
grep -q "프로젝트" README.md이 워크플로우는 아주 단순합니다. PR이 main을 대상으로 열리면 다음을 확인합니다.
README.md가 있는가?index.html이 있는가?style.css가 있는가?README에 "프로젝트"라는 단어가 있는가?
실무의 테스트에 비하면 작지만, 핵심은 같습니다. 검사를 통과한 변경만 병합한다는 습관을 만드는 것입니다.
커밋하고 푸시합니다.
git add .github/workflows/pr-check.yml
git commit -m "ci: add pull request basic checks"
git push -u origin feature/3-pr-check그다음 PR을 만들고 Closes #3을 적습니다. Actions 탭 또는 PR 화면에서 초록색 체크가 뜨면 검사가 통과한 것입니다. 실패했다면 로그를 열어 원인을 보고 수정한 뒤 다시 푸시합니다.
Projects 보드로 상태 관리하기
이제 GitHub Projects에서 보드를 만듭니다. 가장 단순한 칸은 세 개면 충분합니다.
할 일 → 진행 중 → 완료각 Issue를 보드에 추가하고 상태를 관리합니다.
새 Issue를 만들면
할 일브랜치를 만들고 작업을 시작하면
진행 중PR이 병합되고 Issue가 닫히면
완료
처음에는 수동으로 옮겨도 괜찮습니다. 중요한 것은 코드 변경만 보는 것이 아니라, 작업의 상태를 함께 보는 습관입니다.
PR 본문에 Closes #1 같은 문구를 넣으면 병합 시 Issue가 자동으로 닫힙니다. 그러면 Projects에서도 완료된 작업을 확인하기 쉬워집니다. 이것이 실무에서 많이 쓰는 기본 흐름입니다.
PR 템플릿으로 설명을 표준화하기
PR 설명을 매번 새로 쓰기 어렵다면 템플릿을 추가합니다. GitHub 공식 문서에 따르면 저장소에 Pull Request 템플릿을 추가하면, 기여자가 새 PR을 만들 때 템플릿 내용이 본문에 자동으로 표시됩니다.5
.github/pull_request_template.md 파일을 추가합니다.
## 요약
## 변경 내용
-
## 확인 방법
-
## 관련 Issue
Closes #
## 체크리스트
- [ ] 변경 범위가 작습니다.
- [ ] 직접 실행 또는 확인했습니다.
- [ ] 불필요한 파일을 포함하지 않았습니다.이제 새 PR을 만들 때마다 이 양식이 자동으로 표시됩니다. 초보자에게는 특히 유용합니다. 무엇을 써야 할지 고민하는 시간을 줄이고, 리뷰어가 필요한 정보를 빠르게 확인할 수 있습니다.
GitHub Pages로 배포하기
기본 페이지가 완성되었다면 GitHub Pages로 배포합니다.
저장소의
Settings로 이동합니다.왼쪽 메뉴에서
Pages를 선택합니다.Source를
Deploy from a branch로 선택합니다.Branch는
main, 폴더는/root를 선택합니다.저장 후 배포 주소가 생성될 때까지 기다립니다.
배포가 완료되면 README의 배포 주소 영역을 수정합니다.
## 배포 주소
https://사용자이름.github.io/my-profile-site/이 수정도 바로 main에서 하지 말고 Issue와 브랜치, PR을 거쳐 반영합니다. 작은 수정이라도 같은 흐름을 반복해야 습관이 됩니다.
Release와 공개 전 점검
마지막으로 첫 번째 Release를 작성합니다.
Tag:
v1.0.0Release title:
First portfolio site releaseDescription:
자기소개 페이지 추가
README 정리
PR 자동 검사 추가
GitHub Pages 배포 완료
Release는 "이 시점의 결과물"을 표시하는 기록입니다. 포트폴리오로 보여 줄 때도 좋고, 나중에 프로젝트가 어떻게 발전했는지 돌아보기에도 좋습니다.
공개 전에는 다음을 확인합니다.
저장소 공개 범위가 의도한 대로인가?
이름, 이메일, 전화번호 등 민감한 개인정보가 과하게 들어가지 않았는가?
.env, API 키, 비밀번호 같은 비밀 정보가 커밋되지 않았는가?LICENSE가 포함되어 있는가?
README에 실행 방법과 배포 주소가 있는가?
PR과 Issue 기록이 자연스럽게 연결되어 있는가?
특히 민감 정보는 한 번 공개 저장소에 올라가면 완전히 회수하기 어렵습니다. 포트폴리오에는 보여 주고 싶은 정보만 남기고, 계정 토큰이나 비밀번호는 절대 올리지 않습니다.
최종 실습 체크리스트
아래 항목을 모두 완료했다면 이 책의 핵심 흐름을 한 번 끝까지 경험한 것입니다.
작은 공개 프로젝트 주제를 정했다.
저장소를 만들고 기본 파일 구조를 구성했다.
README에 프로젝트 목적과 사용 방법을 적었다.
Issue로 할 일을 나누었다.
기능별 브랜치에서 작업했다.
의미 있는 커밋 메시지를 남겼다.
Pull Request로 변경 사항을 제출했다.
리뷰 코멘트를 반영하는 추가 커밋을 경험했다.
GitHub Actions로 PR 자동 검사를 실행했다.
Projects 보드에서 작업 상태를 관리했다.
Closes #번호로 PR과 Issue를 연결했다.GitHub Pages로 결과물을 배포했다.
Release를 작성했다.
라이선스와 민감 정보 포함 여부를 확인했다.
GitHub 실력은 한 번에 완성되지 않습니다. 하지만 이 흐름을 반복하면 실력이 쌓입니다. 앞으로 어떤 프로젝트를 하든 기본 단위는 같습니다.
Issue로 정의하고, 브랜치에서 작업하고, PR로 검토하고, 자동 검사 후 병합한다.
이 흐름을 몸에 익히면 GitHub는 단순히 코드를 올리는 곳이 아니라, 프로젝트를 안전하게 성장시키는 작업 공간이 됩니다.
참고
1Best practices for repositories - GitHub Docs
2Creating a pull request - GitHub Docs
3Beginner's guide to GitHub: Creating a pull request
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.