GitLab에서 빈 프로젝트를 만들고 기존 로컬 프로젝트 Push하기

1. 이 글에서 다루는 내용

GitLab을 처음 사용하거나, 기존 로컬 프로젝트를 GitLab 저장소에 올려야 할 때는 다음 순서로 진행하면 됩니다.

순서 작업 설명

1	GitLab 그룹 선택	프로젝트를 생성할 그룹으로 이동합니다.
2	새 프로젝트 생성	그룹 화면에서 Create project를 클릭합니다.
3	빈 프로젝트 선택	기존 로컬 프로젝트를 올릴 예정이므로 Create blank project를 선택합니다.
4	프로젝트 정보 입력	프로젝트 이름과 공개 범위를 확인한 뒤 프로젝트를 생성합니다.
5	인증 토큰 준비	Git push/pull 시 사용할 Personal Access Token을 준비합니다.
6	로컬 프로젝트 Push	로컬 프로젝트에 GitLab 원격 저장소를 연결하고 push합니다.
7	권한 범위 이해	Group Members와 Project Members의 차이를 이해합니다.

---

2. GitLab에서 프로젝트 생성하기

먼저 GitLab 웹 화면에서 빈 프로젝트를 생성합니다. 이미 로컬에 작업 중인 프로젝트가 있으므로 GitLab에서 샘플 코드나 README를 자동으로 만들지 않는 것이 좋습니다.

2.1 Groups 메뉴로 이동하기

GitLab 메인 화면의 왼쪽 메뉴에서 Groups를 클릭합니다.

 

화면 왼쪽 사이드바에 Home, Projects, Groups 같은 메뉴가 보이고, 이 중 Groups 메뉴가 강조되어 있습니다. 이 화면은 사용자가 프로젝트를 만들 그룹 목록으로 이동하는 첫 단계입니다.

2.2 프로젝트를 생성할 그룹 선택하기

Groups 화면에서 프로젝트를 생성할 그룹을 선택합니다.

공개 문서에서는 실제 그룹명 대신 아래와 같이 예시 이름을 사용하는 것이 좋습니다.

example-group

 

Groups 목록 화면에 하나 이상의 그룹이 표시됩니다. 사용자는 프로젝트를 생성할 대상 그룹을 클릭합니다. 실제 회사명이나 조직명은 문서에 그대로 노출하지 말고 example-group, sample-group처럼 일반적인 이름으로 바꿔 설명하는 것이 안전합니다.

2.3 Create project 클릭하기

그룹 화면으로 이동한 뒤 오른쪽 상단의 Create project 버튼을 클릭합니다.

그룹 상세 화면 상단에 그룹명이 표시되고, 오른쪽 상단에 Create project 버튼이 있습니다. 이 버튼을 눌러 새 프로젝트 생성 화면으로 이동합니다.

2.4 Create blank project 선택하기

새 프로젝트 생성 화면에서는 여러 선택지가 나올 수 있습니다.

이 글에서는 기존 로컬 프로젝트를 GitLab에 올리는 상황이므로 Create blank project를 선택합니다.

선택지 설명 사용 상황

Create blank project	빈 저장소를 생성합니다.	이미 로컬에 프로젝트가 있을 때 추천
Create from template	템플릿 기반 프로젝트를 생성합니다.	GitLab에서 제공하는 샘플 구조로 새로 시작할 때 사용

Create new project 화면에 Create blank project와 Create from template이 표시됩니다. 기존 로컬 프로젝트를 그대로 올릴 예정이라면 Create blank project를 선택하는 것이 가장 단순합니다.

2.5 프로젝트 이름 입력 후 생성하기

프로젝트 생성 화면에서 다음 항목을 입력하거나 확인합니다.

항목 예시 설명

Project name	sample-project	GitLab에 표시될 프로젝트 이름입니다.
Project slug	sample-project	저장소 URL에 사용되는 이름입니다. 보통 자동 입력됩니다.
Visibility Level	Private	외부 공개가 필요 없다면 Private을 권장합니다.
Initialize repository with a README	체크하지 않음	기존 로컬 프로젝트를 올릴 예정이라면 체크하지 않는 것이 좋습니다.

중요

이미 로컬 프로젝트가 있고 그것을 그대로 GitLab에 올릴 예정이라면 Initialize repository with a README 옵션은 체크하지 않는 것이 좋습니다.

README가 먼저 생성되면 원격 저장소와 로컬 저장소의 최초 커밋 이력이 달라져 push 과정에서 충돌이 발생할 수 있습니다.

프로젝트 이름 입력란과 Create project 버튼이 강조되어 있습니다. 프로젝트 이름을 입력하고 공개 범위를 확인한 뒤 Create project를 클릭하면 GitLab에 빈 저장소가 생성됩니다.

---

3. Git 인증용 Personal Access Token 준비하기

GitLab에 로컬 프로젝트를 push하거나, GitLab 저장소에서 pull할 때 로그인 창이 표시될 수 있습니다.

이때 GitLab 계정 비밀번호 대신 Personal Access Token을 비밀번호처럼 입력합니다.

3.1 Personal Access Token 메뉴 위치

GitLab 화면 오른쪽 위의 사용자 아이콘을 클릭한 뒤 다음 메뉴로 이동합니다.

Edit profile
→ Access tokens
또는
User Settings
→ Personal access tokens

사용자 프로필 메뉴에서 Edit profile을 선택하고, 설정 화면의 왼쪽 메뉴에서 Personal access tokens를 선택하는 흐름입니다. 이 메뉴에서 Git 인증에 사용할 토큰을 생성할 수 있습니다.

3.2 토큰 생성 시 입력할 값

항목 입력 또는 선택 내용

Token name	나중에 알아볼 수 있는 이름을 입력합니다. 예: sample-push-token
Expiration date	조직 정책에 맞는 만료일을 선택합니다. 너무 길게 설정하지 않는 것이 좋습니다.
Scopes	read_repository, write_repository 두 항목만 체크합니다.

3.3 pull/push 목적에 필요한 권한

일반적인 Git 저장소 작업에는 아래 권한만 있으면 충분합니다.

Scope 가능한 작업

read_repository	git clone, git pull, git fetch
write_repository	git push

api 권한은 GitLab API 전체 접근 권한에 가까우므로, 단순히 프로젝트를 pull/push하는 목적이라면 체크하지 않는 것이 좋습니다.

중요

토큰 값은 생성 직후 한 번만 확인할 수 있습니다.

Generate token을 누른 후에는 토큰 값을 바로 복사해 안전한 곳에 저장하세요.

이후 Git 로그인 창이 나타나면 Username에는 GitLab 아이디를, Password에는 생성한 토큰 값을 입력합니다.

---

4. 로컬 프로젝트를 GitLab에 Push하기

프로젝트 생성이 완료되면 GitLab에서 제공하는 원격 저장소 URL을 복사합니다.

공개 문서에서는 실제 서버 주소 대신 아래처럼 예시 주소를 사용합니다.

<https://git.example.com/example-group/sample-project.git>

GitLab 화면에 표시되는 주소가 localhost로 되어 있다면, 다른 사용자의 PC에서는 접근할 수 없습니다. 실제 환경에서는 접속 가능한 도메인이나 서버 주소로 변경해서 사용해야 합니다.

잘못된 예시: 
권장 예시: <https://git.example.com/example-group/sample-project.git>

4.1 Git Bash 실행하기

Windows 환경에서는 현재 작업 중인 로컬 프로젝트 폴더에서 Git Bash를 실행하는 것이 편합니다.

프로젝트 폴더에서 마우스 오른쪽 버튼을 클릭한 뒤 Open Git Bash here를 선택합니다.

그림 설명

GitLab 프로젝트 화면의 Code 버튼을 누르면 HTTPS 또는 SSH 주소를 복사할 수 있는 영역이 표시됩니다. 기존 로컬 프로젝트를 올릴 경우에는 HTTPS 주소를 복사한 뒤, 로컬 프로젝트 폴더에서 Git Bash를 실행해 아래 명령어를 입력합니다.

4.2 현재 폴더가 Git 저장소인지 확인하기

git status

이미 Git으로 관리되고 있는 프로젝트라면 현재 브랜치와 변경 사항 정보가 표시됩니다.

아직 Git 저장소가 아니라면 아래와 같은 메시지가 나올 수 있습니다.

fatal: not a git repository

이 경우 다음 단계에서 Git 저장소를 초기화합니다.

4.3 Git 저장소 초기화 및 첫 커밋 만들기

이미 Git으로 관리되고 있는 프로젝트라면 이 단계는 생략해도 됩니다.

아직 Git 저장소로 초기화되지 않은 프로젝트라면 아래 명령어를 실행합니다.

git init
git add .
git commit -m "init: initial project commit"

커밋 메시지는 공개 문서에서는 영어 또는 일반적인 표현을 사용하는 것이 좋습니다.

init: initial project commit

4.4 GitLab 원격 저장소 연결하기

GitLab에서 복사한 URL을 사용해 로컬 저장소에 원격 저장소를 연결합니다.

git remote add origin <https://git.example.com/example-group/sample-project.git>

여기서 origin은 원격 저장소의 기본 이름입니다. 대부분의 Git 프로젝트에서 기본 원격 저장소 이름으로 origin을 사용합니다.

4.5 기본 브랜치명을 main으로 맞추고 push하기

git branch -M main
git push -u origin main

위 명령어의 의미는 다음과 같습니다.

명령어 설명

git branch -M main	현재 브랜치명을 main으로 변경합니다.
git push -u origin main	로컬 main 브랜치를 원격 저장소에 push하고, 이후 기본 push 대상이 되도록 설정합니다.

---

5. 이미 origin이 등록되어 있을 때

기존에 다른 원격 저장소가 연결되어 있으면 아래 명령어에서 오류가 발생할 수 있습니다.

git remote add origin <https://git.example.com/example-group/sample-project.git>

대표적인 오류는 다음과 같습니다.

fatal: remote origin already exists.

이 경우 먼저 현재 연결된 원격 저장소를 확인합니다.

git remote -v

기존 origin 주소를 새 GitLab 프로젝트 주소로 변경합니다.

git remote set-url origin <https://git.example.com/example-group/sample-project.git>
git push -u origin main

---

6. 작업 완료 확인하기

push가 정상적으로 완료되면 GitLab 프로젝트 화면에서 소스 파일과 커밋 내역을 확인할 수 있습니다.

확인할 항목은 다음과 같습니다.

• GitLab 프로젝트 화면에 소스 파일이 표시되는지 확인합니다.
• Repository > Commits 메뉴에서 방금 push한 커밋 메시지를 확인합니다.
• 로컬에서 git status를 실행했을 때 working tree clean 상태인지 확인합니다.

git status

정상적인 상태라면 아래와 비슷한 메시지가 표시됩니다.

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

---

7. 자주 발생하는 문제

상황 원인 해결 방법

remote origin already exists	이미 origin이 등록되어 있음	git remote set-url origin <URL>로 주소를 변경합니다.
rejected / non-fast-forward	원격 저장소에 README 등 초기 커밋이 있음	원격 저장소를 비우거나 pull 후 충돌을 정리합니다.
Authentication failed	계정, 토큰, 권한 문제	GitLab 아이디와 Personal Access Token을 확인합니다.
branch name mismatch	로컬 브랜치명과 원격 기본 브랜치명이 다름	git branch -M main 후 다시 push합니다.

---

8. Group Members와 Project Members 차이 이해하기

GitLab에서는 사용자 권한을 크게 두 위치에서 관리할 수 있습니다.

• Group Members
• Project Members

두 항목은 비슷해 보이지만, 권한이 적용되는 범위가 다릅니다.

8.1 이미지 분석

위 예시 이미지는 GitLab 관리자 화면에서 프로젝트 상세 정보를 보여주는 화면입니다. 실제 회사명, 프로젝트명, 사용자명, URL, 내부 경로는 모두 교육용 예시 값으로 변경했습니다.

화면은 크게 두 영역으로 나뉩니다.

위치 화면 구성 의미

왼쪽	Project information	프로젝트 이름, 네임스페이스, 저장소 URL, SSH URL 등 프로젝트 기본 정보
오른쪽 위	Group members	그룹에 속한 사용자 목록
오른쪽 아래	Project members	현재 프로젝트에만 직접 추가된 사용자 목록

이미지에서 빨간 밑줄로 강조된 부분은 Group members와 Project members입니다. 이 두 항목을 비교하면 GitLab 권한 구조를 쉽게 이해할 수 있습니다.

8.2 Group Members란?

Group Members는 그룹에 속한 사용자 목록입니다.

그룹에 추가된 사용자는 권한 범위 내에서 해당 그룹 아래에 있는 모든 프로젝트에 접근할 수 있습니다.

예를 들어 아래와 같은 구조가 있다고 가정합니다.

example-group
├── backend-service
├── frontend-app
├── batch-job
└── admin-tool

이 경우 example-group의 멤버로 추가된 사용자는 부여된 역할에 따라 그룹 아래의 모든 프로젝트에 접근할 수 있습니다.

즉, 한 명의 개발자를 그룹 멤버로 추가하면 다음 프로젝트에 모두 접근할 수 있습니다.

• backend-service
• frontend-app
• batch-job
• admin-tool

8.3 Project Members란?

Project Members는 특정 프로젝트에만 직접 권한을 부여하는 사용자 목록입니다.

예를 들어 아래처럼 특정 프로젝트 하나만 참여해야 하는 사용자가 있다고 가정합니다.

example-group
├── backend-service
├── frontend-app   ← 이 프로젝트에만 접근 허용
├── batch-job
└── admin-tool

이 경우 사용자를 example-group 전체에 추가하지 않고, frontend-app 프로젝트의 Project Members에만 추가할 수 있습니다.

그러면 해당 사용자는 frontend-app에는 접근할 수 있지만, 같은 그룹 아래의 다른 프로젝트에는 접근할 수 없습니다.

8.4 Group Members와 Project Members 비교

구분 Group Members Project Members

권한 범위	그룹 전체	특정 프로젝트 하나
접근 대상	그룹 아래 모든 프로젝트	선택한 프로젝트만
관리 방식	한 번 추가하면 여러 프로젝트에 적용	프로젝트별로 개별 관리
추천 상황	팀원이 여러 프로젝트를 함께 관리할 때	외부 사용자나 특정 프로젝트 담당자에게만 권한을 줄 때

8.5 실무에서 권장하는 방식

대부분의 실무 환경에서는 Group Members 중심으로 권한을 관리하는 것이 편합니다.

예를 들어 같은 팀의 개발자들이 여러 프로젝트를 함께 관리한다면, 각 프로젝트마다 사용자를 추가하는 것보다 그룹에 한 번만 추가하는 방식이 효율적입니다.

반대로 다음과 같은 경우에는 Project Members를 사용하는 것이 적합합니다.

• 특정 프로젝트만 담당하는 외부 사용자
• 일부 저장소만 접근해야 하는 단기 참여자
• 보안상 특정 프로젝트에만 접근을 제한해야 하는 사용자

8.6 쉽게 이해하기

비유 설명

Group Members	건물 전체 출입 권한
Project Members	특정 회의실만 출입 가능한 권한

Group Members는 그룹 전체 프로젝트를 관리할 때 편리하고, Project Members는 특정 프로젝트만 예외적으로 접근을 허용할 때 유용합니다.

---

---

10. 전체 명령어 요약

새 GitLab 프로젝트를 만든 뒤 기존 로컬 프로젝트를 올리는 전체 명령어는 다음과 같습니다.

# 1. 현재 폴더가 Git 저장소인지 확인
git status

# 2. Git 저장소가 아니라면 초기화 및 첫 커밋 생성
git init
git add .
git commit -m "init: initial project commit"

# 3. GitLab 원격 저장소 연결
git remote add origin <https://git.example.com/example-group/sample-project.git>

# 4. 기본 브랜치명을 main으로 맞추고 push
git branch -M main
git push -u origin main

이미 origin이 있다면 아래 명령어를 사용합니다.

git remote -v
git remote set-url origin <https://git.example.com/example-group/sample-project.git>
git push -u origin main

---

마무리

GitLab에서 기존 로컬 프로젝트를 올릴 때 핵심은 다음 세 가지입니다.

1. GitLab에서는 빈 프로젝트를 생성합니다.
2. 로컬 프로젝트에서는 Git Bash를 열고 원격 저장소 URL을 연결합니다.
3. 인증이 필요하면 비밀번호 대신 Personal Access Token을 사용합니다.