[gitlab pages] gitlab pages로 배포하기

Innes·2025년 6월 26일

GitLab Pages로 React 프로젝트 배포하기

🎯 배포의 필요성

React + Vite로 개발한 mpi-skeleton 프로젝트를 GitLab Pages로 배포하기로 결정했습니다. GitHub Pages가 아닌 GitLab Pages를 선택한 이유는 프로젝트가 GitLab에서 관리되고 있었기 때문입니다.

또한 처음엔 vercel로 배포를 시도했으나, 회사 vercel 계정이 아직 무료 플랜었는데 gitlab 프로젝트는 그룹 내에 비공개 프로젝트로 위치해있어 무료버전으로는 배포가 불가능했습니다.

따라서 gitlab의 장점인 CI/CD 편리성을 활용해보고자 gitlab pages를 선택했습니다.

🛠️ 초기 설정과 첫 번째 시도

커스텀 도메인을 사용하지 않는 기본 배포 과정을 정리하였습니다.

GitLab CI/CD 설정 파일 생성
프로젝트 루트에 .gitlab-ci.yml 파일을 생성했습니다:

image: node:20.19.1
// node:latest 로 해도 되지만, 혹시 모를 node 버전 충돌을 막고자 특정 버전을 지정함

cache:
  paths:
    - node_modules/

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - cp -r dist/* public/
  artifacts:
    paths:
      - public
  only:
    - main

Vite 설정 수정
vite.config.ts 파일 수정

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from "path";

export default defineConfig({
  base : '/',
  plugins: [react()],
  resolve: {
    alias: {
      "@": "/src",
    },
  },
  build: {
    outDir: path.resolve(import.meta.dirname, "dist"),
    emptyOutDir: true,
  },
})

추가 - 커스텀 도메인 사용하는 경우

.gitlab-ci.yml 파일 맨 아래에 variables 추가

variables:
  CUSTOM_DOMAIN: "<커스텀 도메인>"

public 폴더 내 CNAME 파일 추가
CNAME 파일 안에는 커스텀 도메인만 작성해둡니다.

public > .well-known > acme-challenge 폴더 생성
폴더 안에 .gitkeep 파일 생성 및 아래 내용 작성

```
# 이 파일은 디렉토리 구조를 유지하기 위한 것입니다.
# Let's Encrypt와 같은 SSL 인증서 발급 서비스가 acme-challenge 파일을 이 디렉토리에 저장합니다. 
```

🚨 트러블 슈팅

1. 첫 번째 실패: TypeScript 컴파일 에러

src/App.tsx(46,7): error TS6133: 'LOARequestsPage' is declared but its value is never read.
src/components/mpi/ClaimsUnderReviewTable.tsx(195,36): error TS7053: Element implicitly has an 'any' type...

문제 : 사용되지 않는 변수 및 함수들, type 에러 등의 문제
해결 과정:
사용되지 않는 import들 제거
STATUS_CONFIG에 누락된 상태들 추가 (approved, rejected, cancelled)
타입 안전성을 위한 null 체크 구현 등

2. 두 번째 실패: public 폴더 없음 에러

cp: target 'public/': No such file or directory

문제 : 로컬에서는 분명 public 폴더가 있는데 build만 하면 public폴더가 없다고 한다. public폴더 내부에 아무 파일도 없어서 생긴 문제인 것 같았습니다.
해결책: .gitlab-ci.yml에 폴더 생성 명령어 추가

script:
  - npm ci
  - npm run build
  - mkdir -p public  # 추가
  - cp -r dist/* public/

3. 세 번째 실패: 배포 사이트 최초 접속시 뜨는 Redirecting 메시지

배포는 성공했지만 브라우저에서 접속 시 'Redirecting : ...' 라는 불필요한 리다이렉팅 화면이 떴습니다.

문제 : 배포 사이트의 접근 권한이 설정되어 있었기 때문!
해결 :
⭐️ 마지막엔 Setting > General > Visibility, project features, permissions > Pages 에서 배포 사이트 접근 권한을 전체공개로 바꿔줘야함!
(기본 : only project members)