목차
- 1 이 글에서 먼저 결정할 것
- 2 Work N Rich 재현 워크시트
- 3 이번 개편에서 추가로 확인할 증거
- 4 먼저 결정할 것: 사용자 사이트인가, 프로젝트 사이트인가
- 5 1단계: 공개해도 되는 파일인지 먼저 검사합니다
- 6 2단계: 저장소 이름과 공개 범위를 정합니다
- 7 3단계: 바로 쓸 수 있는 index.html을 준비합니다
- 8 4단계: 브라우저에서 파일을 업로드하고 커밋합니다
- 9 5단계: Settings에서 Pages를 켭니다
- 10 6단계: 예상 주소를 먼저 계산합니다
- 11 7단계: 404가 나면 이 순서로만 확인합니다
- 12 실제 입력값으로 하는 3분 사전 점검
- 13 이 글이 합친 네 가지 질문
- 14 함께 읽으면 좋은 글
- 15 자주 막히는 질문
- 16 확인한 공식 자료
- 17 함께 읽으면 좋은 글
- 18 한계와 업데이트
이 글에서 먼저 결정할 것
독자 질문: 이 AI 기능이나 방법을 실제 업무에 적용할 때 무엇을 확인해야 할까?
첫 답변: 기능을 바로 믿고 맡기기보다 입력 범위·권한·결과·사람 검수·실패 복구를 정한 뒤 작은 비식별 예시로 확인하는 것이 먼저다.
판단 기준: 공식 기능 사실, 합성 입력·출력, 사람의 검수 기준, 권한·보안 한계를 분리한다.
Work N Rich 재현 워크시트
이 워크시트는 사실을 다시 요약하는 칸이 아니라, 독자가 자기 상황의 입력·검수·다음 행동을 기록하는 칸이다.
| 단계 | 기록할 내용 |
|---|---|
| 입력 | 실제 회사자료 대신 비식별·합성 업무 자료를 넣고, 입력하지 않은 정보는 무엇인지 적는다. |
| 결과 | AI가 만든 결과에서 사실·추정·누락을 나누어 기록한다. |
| 사람 확인 | 사실 오류·권한·개인정보·업무 책임을 사람이 확인할 기준을 적는다. |
| 실패 복구 | 오류가 나면 중지할 행동, 원문으로 되돌아갈 방법, 다시 시도할 조건을 적는다. |
이번 개편에서 추가로 확인할 증거
- 독자용 증거 자산: 비식별 합성 입력 + 권한/실패 검수
- 개편 공백: 합성 입력 → 결과 → 사람의 확인 → 실패 복구 흐름 추가
GitHub에 처음 가입한 직장인이 가장 자주 막히는 지점은 코딩이 아닙니다. Repository, Commit, Branch, Pages라는 네 단어가 서로 어떻게 이어지는지 한 화면에서 보이지 않는 것이 문제입니다. 그래서 이 글은 가입 설명, 저장소 만들기, HTML 업로드, Pages 설정, 주소 규칙을 네 편으로 나누지 않고 하나의 완주 흐름으로 묶었습니다.
완료 기준은 네 가지입니다.
- 내 저장소에
index.html이 보인다. - 변경 기록에 첫 커밋이 남는다.
Settings → Pages에서 배포 소스를 선택한다.https://아이디.github.io/저장소이름/주소에서 실제 화면을 확인한다.
이 글은 2026년 7월 11일 GitHub 공식 문서를 기준으로 검증했습니다. GitHub 화면의 버튼 위치나 문구는 바뀔 수 있지만, 저장소 생성 → 파일 커밋 → Pages 배포 소스 선택 → 공개 주소 확인이라는 구조는 같습니다.
확인 기준일: 2026-07-11
아래 흐름도는 이 글의 실행 순서와 404가 날 때의 첫 점검 항목을 한 장으로 만든 Work N Rich 원본 자료입니다.
먼저 결정할 것: 사용자 사이트인가, 프로젝트 사이트인가
GitHub Pages 주소는 두 종류입니다. 이 구분을 모르고 시작하면 저장소 이름과 예상 주소가 어긋납니다.
| 구분 | 저장소 이름 | 기본 주소 | 추천 상황 |
|---|---|---|---|
| 사용자 사이트 | 아이디.github.io |
https://아이디.github.io/ |
개인 대표 홈페이지 하나를 만들 때 |
| 프로젝트 사이트 | 원하는 저장소 이름 | https://아이디.github.io/저장소이름/ |
강의 소개, 포트폴리오, 행사 안내처럼 여러 페이지를 나눌 때 |
처음 연습한다면 프로젝트 사이트가 관리하기 쉽습니다. 예를 들어 아이디가 goodteacher, 저장소가 ai-class-page라면 예상 주소는 https://goodteacher.github.io/ai-class-page/입니다. 반대로 계정 대표 사이트 하나가 목적이라면 저장소 이름을 정확히 goodteacher.github.io로 만듭니다.
1단계: 공개해도 되는 파일인지 먼저 검사합니다
GitHub Pages는 웹사이트입니다. 공개 저장소에 올린 파일은 다른 사람이 저장소에서도 볼 수 있습니다. 아래 항목이 하나라도 들어 있다면 업로드 전에 제거해야 합니다.
| 올리면 안 되는 정보 | 왜 위험한가 | 안전한 대체 방법 |
|---|---|---|
| 비밀번호·API 키·토큰 | 계정이나 유료 API가 탈취될 수 있음 | 환경변수나 서버 측 비밀 저장소 사용 |
| 고객 이름·전화번호·이메일 | 개인정보 노출 | 가상 예시 데이터로 교체 |
| 회사 내부 문서·매출 자료 | 영업비밀 노출 | 공개 가능한 요약본만 사용 |
| 유료 이미지 원본 | 라이선스 위반 가능 | 직접 제작하거나 공개 허용 자산 사용 |
| 로그인 기능이 필요한 자료 | 정적 사이트만으로 보호되지 않음 | 별도 인증 서비스 사용 |
HTML에 키가 보이지 않더라도 JavaScript 파일이나 이미지 메타데이터에 남아 있을 수 있습니다. 업로드 폴더 전체를 한 번 확인하는 습관이 중요합니다.
2단계: 저장소 이름과 공개 범위를 정합니다
GitHub의 현재 저장소 생성 안내에 따르면 오른쪽 위 새로 만들기 메뉴에서 New repository를 선택하고, 소유자·이름·설명·공개 범위를 정한 뒤 저장소를 만듭니다.
초보자용 설정표는 다음과 같습니다.
| 항목 | 권장 입력 | 판단 기준 |
|---|---|---|
| Owner | 본인 계정 | 조직 계정은 생성 권한이 있어야 함 |
| Repository name | ai-class-page처럼 짧은 영어 |
주소 뒷부분에 그대로 들어갈 수 있음 |
| Description | 페이지 목적을 한 문장으로 | 나중에 저장소를 찾기 쉬움 |
| Visibility | 실습용이면 Public | GitHub Free의 Pages는 공개 저장소에서 사용 가능 |
| README | 선택 | 빈 저장소보다 첫 화면을 이해하기 쉬움 |
저장소 이름은 test, final-final, new-page-2026-real보다 목적이 드러나는 portfolio, training-page, career-guide가 낫습니다. 공개 링크를 소리 내어 읽었을 때 설명하기 쉬운 이름이면 충분합니다.
3단계: 바로 쓸 수 있는 index.html을 준비합니다
아래 코드는 외부 라이브러리 없이 작동하는 최소 시작 파일입니다. 메모장이나 Visual Studio Code에 붙여 넣고 UTF-8로 저장하세요. 파일명은 index.html로 정확히 적습니다. index.html.txt가 되지 않도록 Windows 파일 확장명 표시를 켜는 것이 안전합니다.
<!doctype html>
<html lang="ko">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>나의 첫 GitHub Pages</title>
<style>
body { max-width: 720px; margin: 64px auto; padding: 0 20px; font-family: system-ui, sans-serif; line-height: 1.7; }
.card { padding: 24px; border: 1px solid #d0d7de; border-radius: 16px; background: #f6f8fa; }
a { color: #0969da; }
</style>
</head>
<body>
<main class="card">
<p>배포 확인용 페이지</p>
<h1>GitHub Pages 연결 성공</h1>
<p>이 문장이 보이면 저장소, index.html, Pages 설정이 모두 연결된 것입니다.</p>
<a href="https://docs.github.com/pages">GitHub Pages 공식 문서</a>
</main>
</body>
</html>이 파일에는 일부러 세 가지 확인 장치를 넣었습니다.
<meta charset="utf-8">: 한글 깨짐을 줄입니다.- viewport 메타: 휴대전화 화면 폭에 맞춥니다.
GitHub Pages 연결 성공: 배포된 파일이 새 파일인지 즉시 구분합니다.
아래 화면은 위 코드를 별도 파일로 저장해 Chrome에서 직접 렌더링한 결과입니다. 실제 공개 주소에서도 같은 성공 문구가 보여야 합니다.
4단계: 브라우저에서 파일을 업로드하고 커밋합니다
GitHub의 파일 추가 안내 기준 흐름은 저장소 메인 → Add file → Upload files → 파일 선택 → 변경 설명 → 커밋입니다.
| 순서 | 화면에서 할 일 | 성공 확인 |
|---|---|---|
| 1 | 방금 만든 저장소로 이동 | 저장소 이름이 화면 위에 보임 |
| 2 | Add file에서 Upload files 선택 |
파일 선택 영역이 열림 |
| 3 | index.html을 끌어 놓거나 선택 |
업로드 목록에 파일명이 보임 |
| 4 | 변경 설명에 Add starter index page 입력 |
무엇을 바꿨는지 기록됨 |
| 5 | Commit changes 또는 Propose changes 선택 |
저장소 파일 목록에 index.html이 보임 |
버튼이 Commit changes가 아니라 Propose changes로 보일 수 있습니다. 저장소의 브랜치 보호나 현재 권한에 따라 흐름이 달라지기 때문입니다. 본인이 만든 단순 실습 저장소라면 기본 브랜치에 바로 커밋할 수 있는 경우가 많고, 보호 규칙이 있으면 새 브랜치와 Pull Request가 필요할 수 있습니다.
브라우저 업로드는 파일당 25MiB, 한 번에 100개 파일 제한이 있습니다. 더 큰 파일은 명령줄이나 Git LFS가 필요합니다. 그러나 첫 index.html 하나에는 이 제한이 문제가 되지 않습니다.
5단계: Settings에서 Pages를 켭니다
GitHub Pages 빠른 시작의 현재 흐름은 다음과 같습니다.
| 설정 위치 | 선택 | 의미 |
|---|---|---|
| 저장소 상단 | Settings |
저장소 설정으로 이동 |
왼쪽 Code and automation |
Pages |
웹사이트 배포 설정 |
| Build and deployment / Source | Deploy from a branch |
브랜치의 정적 파일을 배포 |
| Branch | main 또는 실제 기본 브랜치 |
어느 브랜치를 공개할지 선택 |
| Folder | /(root) |
저장소 최상위의 index.html 사용 |
| 마지막 | Save |
배포 설정 확정 |
Settings가 안 보이면 상단 메뉴의 더보기에서 찾습니다. Branch 목록이 None만 보인다면 먼저 index.html을 커밋했는지 확인하세요. 커밋이 있어야 기본 브랜치가 생깁니다.
설정을 저장한 뒤 주소가 즉시 열리지 않아도 실패로 단정하지 않습니다. GitHub는 변경 사항 게시에 최대 10분이 걸릴 수 있다고 안내합니다.
6단계: 예상 주소를 먼저 계산합니다
주소를 기다리는 동안 저장소 유형으로 예상 주소를 계산할 수 있습니다.
| 입력 | 예시 |
|---|---|
| GitHub 아이디 | goodteacher |
| 저장소 이름 | ai-class-page |
| 사이트 유형 | 프로젝트 사이트 |
| 예상 주소 | https://goodteacher.github.io/ai-class-page/ |
사용자 사이트라면 저장소 이름을 goodteacher.github.io로 만들고 주소는 https://goodteacher.github.io/가 됩니다. 프로젝트 사이트에는 저장소 이름이 경로로 붙습니다. 이 차이가 404를 진단할 때 매우 중요합니다.
7단계: 404가 나면 이 순서로만 확인합니다
무작정 설정을 반복 저장하면 원인을 놓칩니다. 아래 순서를 위에서 아래로 한 번씩 확인하세요.
| 증상 | 먼저 확인할 것 | 고치는 방법 |
|---|---|---|
| 주소 전체가 404 | 주소 유형 | 프로젝트 사이트라면 /저장소이름/까지 입력 |
| Pages에 Branch가 없음 | 첫 커밋 | index.html을 올리고 커밋 완료 |
| 주소는 열리지만 빈 화면 | 파일 내용 | index.html의 본문과 태그 닫힘 확인 |
| 한글이 깨짐 | 문자 인코딩 | UTF-8 저장과 charset 메타 확인 |
| CSS·이미지만 깨짐 | 절대경로 / 사용 |
프로젝트 사이트에서는 상대경로 ./부터 점검 |
| 변경이 반영되지 않음 | 배포 시간·캐시 | 최대 10분 기다리고 강력 새로고침 |
| Settings가 안 보임 | 권한 | 본인 저장소인지, 조직 권한이 있는지 확인 |
| 업로드가 차단됨 | 비밀정보 감지 | 토큰·키를 제거하고 다시 업로드 |
특히 프로젝트 사이트에서 이미지 주소를 /image.png로 쓰면 계정 루트를 가리킬 수 있습니다. 같은 폴더의 이미지는 처음에 ./image.png처럼 상대경로로 두는 편이 안전합니다.
실제 입력값으로 하는 3분 사전 점검
아래 네 칸을 직접 채우면 실수가 크게 줄어듭니다.
| 질문 | 내 답 |
|---|---|
| GitHub 아이디는 무엇인가 | |
| 저장소 이름은 무엇인가 | |
| 사용자 사이트인가, 프로젝트 사이트인가 | |
| 예상 공개 주소는 무엇인가 |
그 다음 아래 완료 증거를 하나씩 확인합니다.
- [ ] 저장소 파일 목록에서
index.html을 확인했다. - [ ]
index.html을 눌렀을 때 방금 넣은 성공 문구가 보인다. - [ ] 커밋 기록에 변경 설명이 남아 있다.
- [ ] Pages Source와 Branch를 선택하고 저장했다.
- [ ] 예상 주소에서 성공 문구를 확인했다.
- [ ] 휴대전화에서도 글자가 화면 밖으로 나가지 않는다.
- [ ] 저장소 전체에서 비밀번호·토큰·개인정보가 없음을 재확인했다.
이 글이 합친 네 가지 질문
기존에는 가입과 첫 화면, 저장소와 HTML 업로드, Pages의 main 설정, URL 이름 규칙을 각각 다른 글로 설명했습니다. 하지만 실제 사용자는 네 글을 읽는 것이 목적이 아니라 한 번에 공개 주소를 얻는 것이 목적입니다. 이 글은 그 네 검색 의도를 한 실행 흐름으로 통합했습니다.
화면이 달라져도 다음 문장만 기억하면 됩니다.
공개할 수 있는 파일을 준비하고, 목적이 드러나는 저장소에 커밋한 뒤, Pages에서 그 브랜치를 배포 소스로 선택하고, 계산한 주소에서 결과를 확인합니다.
함께 읽으면 좋은 글
- 반복 업무를 AI 시스템으로 바꾸는 30일 점검법: 웹페이지 공개를 일회성 작업이 아니라 반복 가능한 체크리스트로 만드는 데 도움이 됩니다.
- Gemini Canvas로 문서에서 웹페이지까지 만드는 흐름: HTML 초안을 만드는 단계부터 연결하고 싶을 때 참고하세요.
자주 막히는 질문
GitHub 가입 중 보안 확인이 나오면 잘못된 것인가요?
아닙니다. 자동 가입을 막기 위한 확인 절차가 나타날 수 있습니다. 화면은 시점과 환경에 따라 달라지므로 특정 게임 모양을 외우기보다 안내를 천천히 읽고, 가입 뒤 이메일 인증까지 완료하세요.
Public 저장소가 아니면 Pages를 못 쓰나요?
GitHub Free에서는 공개 저장소에서 Pages를 사용할 수 있습니다. 비공개 저장소의 Pages 사용 가능 여부는 요금제에 따라 다릅니다. 처음 실습은 공개 가능한 샘플 파일만 담은 Public 저장소가 가장 단순합니다.
저장소 이름을 나중에 바꿔도 되나요?
바꿀 수 있지만 프로젝트 사이트 주소도 달라질 수 있습니다. 이미 공유한 링크와 문서가 있다면 수정 비용이 생기므로, 공개 전에 짧고 의미 있는 이름을 확정하는 편이 좋습니다.
회사 자료를 잠깐 올렸다가 지우면 괜찮나요?
괜찮다고 볼 수 없습니다. Git 기록과 캐시에 남을 수 있습니다. 비밀번호나 고객정보를 올렸다면 파일 삭제만 하지 말고 해당 비밀을 즉시 폐기·교체하고, 조직의 보안 절차에 따라 이력을 정리해야 합니다.
확인한 공식 자료
함께 읽으면 좋은 글
- AI가 내 일을 바꿀 때, 신입 직장인이 먼저 할 일 — 같은 카테고리에서 검수와 실행 범위를 비교할 수 있는 글
- AI에 회사 문서를 넣어도 될까? 8월 31일 개인정보 제도 제안 전 점검표 — 같은 카테고리에서 검수와 실행 범위를 비교할 수 있는 글
한계와 업데이트
실제 회사 자료나 개인 정보로 검증한 경험을 의미하지 않는다. 기능·요금·권한은 계정 유형과 시점에 따라 달라질 수 있으므로 공식 문서와 조직 정책을 다시 확인한다. 이 글의 기준일과 공식 출처는 공개 전 다시 확인한다. 마지막 확인일: https://work-n-rich.com/github-repository-and-html-upload-guide/.