.gitea/workflows/deploy.yml

@@ -0,0 +1,36 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Configure npm registry
+        run: |
+          echo "registry=https://nexus.gc-si.dev/repository/npm-public/" > .npmrc
+          echo "//nexus.gc-si.dev/repository/npm-public/:_auth=${{ secrets.NEXUS_NPM_AUTH }}" >> .npmrc
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Deploy to server
+        run: |
+          rm -rf /deploy/guide/*
+          cp -r dist/* /deploy/guide/
+          echo "Deployed at $(date '+%Y-%m-%d %H:%M:%S')"
+          ls -la /deploy/guide/

src/content/CiCdGuide.tsx

@@ -0,0 +1,506 @@
+import { Alert } from '../components/common/Alert';
+import { CodeBlock } from '../components/common/CodeBlock';
+import { StepGuide } from '../components/common/StepGuide';
+
+export default function CiCdGuide() {
+  return (
+    <div className="max-w-4xl mx-auto py-12 px-6">
+      <h1 className="text-3xl font-bold text-text-primary mb-2">CI/CD 자동 배포</h1>
+      <p className="text-text-secondary mb-8">
+        Gitea Actions를 이용한 자동 빌드 및 배포 파이프라인 구성 방법을 안내합니다.
+      </p>
+
+      {/* 개요 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">개요</h2>
+      <p className="text-text-secondary mb-4">
+        <strong>Gitea Actions</strong>는 GitHub Actions와 호환되는 CI/CD 시스템입니다.
+        리포지토리에 워크플로우 파일을 추가하면, 특정 이벤트(push, MR 등) 발생 시
+        자동으로 빌드와 배포가 실행됩니다.
+      </p>
+      <div className="bg-surface border border-border-default rounded-xl p-5 mb-6">
+        <div className="font-mono text-sm space-y-1.5 text-text-secondary">
+          <div className="flex items-center gap-2 flex-wrap">
+            <span className="text-accent font-semibold">main 머지</span>
+            <span className="text-text-muted">&rarr;</span>
+            <span>Gitea Actions 트리거</span>
+            <span className="text-text-muted">&rarr;</span>
+            <span className="text-accent font-semibold">act_runner</span>
+            <span className="text-text-muted">&rarr;</span>
+            <span>빌드 + 배포</span>
+            <span className="text-text-muted">&rarr;</span>
+            <span className="text-success font-semibold">서비스 갱신</span>
+          </div>
+        </div>
+      </div>
+
+      <div className="bg-surface border border-border-default rounded-xl p-5 mb-6">
+        <h3 className="font-semibold text-text-primary mb-3">배포 흐름</h3>
+        <div className="font-mono text-sm space-y-1 text-text-secondary">
+          <p>개발자 &rarr; feature 브랜치 push &rarr; develop MR 머지</p>
+          <p className="pl-8">&darr;</p>
+          <p className="pl-4">develop &rarr; main MR 생성 &rarr; 리뷰 승인 &rarr; main 머지</p>
+          <p className="pl-8">&darr;</p>
+          <p className="pl-4">
+            <span className="text-accent">Gitea Actions 트리거</span> &rarr; act_runner (Docker 컨테이너)
+          </p>
+          <p className="pl-8">&darr;</p>
+          <p className="pl-4">npm ci &rarr; npm run build &rarr; dist/ 생성</p>
+          <p className="pl-8">&darr;</p>
+          <p className="pl-4">
+            배포 경로에 복사 &rarr; <span className="text-success">Nginx 서빙</span>
+          </p>
+        </div>
+      </div>
+
+      <Alert type="info">
+        GitHub Actions 워크플로우 파일과 동일한 문법을 사용합니다.
+        기존 GitHub Actions 경험이 있다면 쉽게 적용할 수 있습니다.
+      </Alert>
+
+      {/* 워크플로우 파일 구조 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">워크플로우 파일 구조</h2>
+      <p className="text-text-secondary mb-4">
+        워크플로우 파일은 리포지토리의{' '}
+        <code className="bg-bg-tertiary px-1 rounded">.gitea/workflows/</code> 디렉토리에 YAML 형식으로 작성합니다.
+      </p>
+      <CodeBlock
+        language="bash"
+        code={`# 워크플로우 파일 위치
+프로젝트/
+└── .gitea/
+    └── workflows/
+        └── deploy.yml    ← 워크플로우 정의 파일`}
+      />
+
+      <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">기본 구조</h3>
+      <CodeBlock
+        language="yaml"
+        code={`name: 워크플로우 이름
+
+on:                          # 트리거 조건
+  push:
+    branches:
+      - main                 # main 브랜치에 push 시 실행
+
+jobs:                        # 실행할 작업 목록
+  job-name:
+    runs-on: ubuntu-latest   # 실행 환경 (Runner 라벨)
+    steps:                   # 순차 실행할 단계
+      - name: Step 이름
+        uses: actions/checkout@v4  # 액션 사용
+      - name: 명령 실행
+        run: echo "Hello"          # 쉘 명령 실행`}
+      />
+
+      {/* 트리거 조건 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">트리거 조건</h2>
+      <div className="overflow-x-auto">
+        <table className="w-full bg-surface border border-border-default rounded-lg overflow-hidden text-sm">
+          <thead>
+            <tr className="bg-bg-tertiary">
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">이벤트</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">설명</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">예시</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-border-subtle">
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">push</td>
+              <td className="px-4 py-3 text-text-secondary">브랜치에 push 시</td>
+              <td className="px-4 py-3 font-mono text-sm text-text-secondary">branches: [main]</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">pull_request</td>
+              <td className="px-4 py-3 text-text-secondary">MR 생성/업데이트 시</td>
+              <td className="px-4 py-3 font-mono text-sm text-text-secondary">branches: [main], types: [opened, synchronize]</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">schedule</td>
+              <td className="px-4 py-3 text-text-secondary">Cron 스케줄</td>
+              <td className="px-4 py-3 font-mono text-sm text-text-secondary">cron: &apos;0 2 * * *&apos;</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">workflow_dispatch</td>
+              <td className="px-4 py-3 text-text-secondary">수동 실행</td>
+              <td className="px-4 py-3 font-mono text-sm text-text-secondary">Gitea UI에서 수동 트리거</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <Alert type="warning">
+        MR을 통해 main에 머지하면 <code className="bg-bg-tertiary px-1 rounded">push</code> 이벤트가 발생합니다.
+        배포 워크플로우는 <code className="bg-bg-tertiary px-1 rounded">on: push: branches: [main]</code>으로 설정하는 것이 일반적입니다.
+      </Alert>
+
+      {/* 시크릿 관리 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">시크릿 관리</h2>
+      <p className="text-text-secondary mb-4">
+        비밀번호, 인증 토큰 등 민감한 정보는 리포지토리 시크릿으로 관리합니다.
+        워크플로우에서{' '}
+        <code className="bg-bg-tertiary px-1 rounded">{'${{ secrets.시크릿_이름 }}'}</code>으로 참조합니다.
+      </p>
+      <StepGuide
+        steps={[
+          {
+            title: 'Gitea 리포지토리 페이지 접속',
+            content: (
+              <p>
+                대상 리포지토리 &rarr; <strong>Settings</strong> &rarr; <strong>Actions</strong> &rarr;{' '}
+                <strong>Secrets</strong>로 이동합니다.
+              </p>
+            ),
+          },
+          {
+            title: '시크릿 추가',
+            content: (
+              <p>
+                <strong>Add Secret</strong> 클릭 후 이름과 값을 입력합니다.
+                시크릿 이름은 <code className="bg-bg-tertiary px-1 rounded">UPPER_SNAKE_CASE</code>로 작성합니다.
+              </p>
+            ),
+          },
+          {
+            title: '워크플로우에서 사용',
+            content: (
+              <CodeBlock
+                language="yaml"
+                code={`- name: Configure registry
+  run: |
+    echo "//nexus.gc-si.dev/repository/npm-public/:_auth=\${{ secrets.NEXUS_NPM_AUTH }}" >> .npmrc`}
+              />
+            ),
+          },
+        ]}
+      />
+
+      <div className="overflow-x-auto mt-4">
+        <table className="w-full bg-surface border border-border-default rounded-lg overflow-hidden text-sm">
+          <thead>
+            <tr className="bg-bg-tertiary">
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">시크릿 이름</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">용도</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">설정된 리포</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-border-subtle">
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">NEXUS_NPM_AUTH</td>
+              <td className="px-4 py-3 text-text-secondary">Nexus npm 레지스트리 인증 (Base64)</td>
+              <td className="px-4 py-3 text-text-secondary">gc-guide</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      {/* gc-guide 워크플로우 예시 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">gc-guide 워크플로우 (React)</h2>
+      <p className="text-text-secondary mb-4">
+        gc-guide 프로젝트의 실제 배포 워크플로우입니다.
+        main 브랜치에 머지되면 자동으로 빌드하고 서버에 배포합니다.
+      </p>
+      <CodeBlock
+        language="yaml"
+        filename=".gitea/workflows/deploy.yml"
+        code={`name: Build and Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Configure npm registry
+        run: |
+          echo "registry=https://nexus.gc-si.dev/repository/npm-public/" > .npmrc
+          echo "//nexus.gc-si.dev/repository/npm-public/:_auth=\${{ secrets.NEXUS_NPM_AUTH }}" >> .npmrc
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Deploy to server
+        run: |
+          rm -rf /deploy/guide/*
+          cp -r dist/* /deploy/guide/
+          echo "Deployed at $(date '+%Y-%m-%d %H:%M:%S')"
+          ls -la /deploy/guide/`}
+      />
+
+      <Alert type="info">
+        <code className="bg-bg-tertiary px-1 rounded">/deploy/guide/</code>는 act_runner 컨테이너 설정에서
+        호스트의 <code className="bg-bg-tertiary px-1 rounded">/devdata/services/guide/dist/</code>에
+        마운트되어 있습니다. 빌드 결과물을 복사하면 Nginx가 즉시 서빙합니다.
+      </Alert>
+
+      {/* gc-guide-api 워크플로우 예시 (향후) */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">gc-guide-api 워크플로우 (Spring Boot, 예정)</h2>
+      <p className="text-text-secondary mb-4">
+        Java/Spring Boot 프로젝트의 워크플로우 예시입니다. 향후 gc-guide-api에 적용 예정입니다.
+      </p>
+      <CodeBlock
+        language="yaml"
+        filename=".gitea/workflows/deploy.yml (예정)"
+        code={`name: Build and Deploy API
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    container:
+      image: maven:3.9-eclipse-temurin-17
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure Maven (settings.xml)
+        run: |
+          mkdir -p ~/.m2
+          cat > ~/.m2/settings.xml << 'EOF'
+          <settings>
+            <mirrors>
+              <mirror>
+                <id>nexus</id>
+                <mirrorOf>*</mirrorOf>
+                <url>https://nexus.gc-si.dev/repository/maven-public/</url>
+              </mirror>
+            </mirrors>
+            <servers>
+              <server>
+                <id>nexus</id>
+                <username>\${{ secrets.NEXUS_USERNAME }}</username>
+                <password>\${{ secrets.NEXUS_PASSWORD }}</password>
+              </server>
+            </servers>
+          </settings>
+          EOF
+
+      - name: Build
+        run: mvn clean package -DskipTests
+
+      - name: Deploy
+        run: |
+          cp target/*.jar /deploy/api/app.jar
+          # 서비스 재시작은 별도 스크립트로 처리`}
+      />
+
+      {/* Actions 확인 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">빌드 결과 확인</h2>
+      <StepGuide
+        steps={[
+          {
+            title: 'Gitea 리포지토리 접속',
+            content: (
+              <p>
+                <a
+                  href="https://gitea.gc-si.dev/gc/gc-guide"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-accent hover:underline"
+                >
+                  https://gitea.gc-si.dev/gc/gc-guide
+                </a>
+                에 접속합니다.
+              </p>
+            ),
+          },
+          {
+            title: 'Actions 탭 확인',
+            content: (
+              <p>
+                리포지토리 상단의 <strong>Actions</strong> 탭을 클릭하면 워크플로우 실행 이력을 확인할 수 있습니다.
+                각 실행 항목을 클릭하면 상세 로그를 볼 수 있습니다.
+              </p>
+            ),
+          },
+          {
+            title: '배포 결과 확인',
+            content: (
+              <p>
+                빌드 성공 후{' '}
+                <a
+                  href="https://guide.gc-si.dev"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-accent hover:underline"
+                >
+                  https://guide.gc-si.dev
+                </a>
+                에서 배포 결과를 확인합니다. 변경 사항이 반영되지 않으면 브라우저 캐시를 삭제하세요 (Ctrl+Shift+R).
+              </p>
+            ),
+          },
+        ]}
+      />
+
+      {/* 워크플로우 작성 팁 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">워크플로우 작성 팁</h2>
+
+      <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">자주 사용하는 액션</h3>
+      <div className="overflow-x-auto">
+        <table className="w-full bg-surface border border-border-default rounded-lg overflow-hidden text-sm">
+          <thead>
+            <tr className="bg-bg-tertiary">
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">액션</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">용도</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-border-subtle">
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">actions/checkout@v4</td>
+              <td className="px-4 py-3 text-text-secondary">리포지토리 소스코드 체크아웃</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">actions/setup-node@v4</td>
+              <td className="px-4 py-3 text-text-secondary">Node.js 설정</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">actions/setup-java@v4</td>
+              <td className="px-4 py-3 text-text-secondary">JDK 설정</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 font-mono text-text-primary">actions/cache@v4</td>
+              <td className="px-4 py-3 text-text-secondary">의존성 캐시 (빌드 시간 단축)</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">환경변수와 시크릿</h3>
+      <CodeBlock
+        language="yaml"
+        code={`# 워크플로우 레벨 환경변수
+env:
+  NODE_ENV: production
+
+# Step 레벨 환경변수
+steps:
+  - name: Build
+    env:
+      API_URL: https://api.gc-si.dev
+    run: npm run build
+
+# 시크릿 참조
+steps:
+  - name: Deploy
+    run: echo "\${{ secrets.DEPLOY_TOKEN }}"`}
+      />
+
+      {/* Runner 관리 (관리자) */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">Runner 관리 (관리자)</h2>
+      <p className="text-text-secondary mb-4">
+        Gitea Actions는 <strong>act_runner</strong>라는 실행기가 빌드를 처리합니다.
+        Docker 컨테이너로 동작하며, 각 빌드 job을 별도 Docker 컨테이너에서 격리 실행합니다.
+      </p>
+
+      <div className="overflow-x-auto mb-4">
+        <table className="w-full bg-surface border border-border-default rounded-lg overflow-hidden text-sm">
+          <thead>
+            <tr className="bg-bg-tertiary">
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">항목</th>
+              <th className="text-left px-4 py-3 font-semibold text-text-primary">값</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-border-subtle">
+            <tr>
+              <td className="px-4 py-3 text-text-primary">Runner 이름</td>
+              <td className="px-4 py-3 font-mono text-text-secondary">gc-runner-01</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 text-text-primary">컨테이너</td>
+              <td className="px-4 py-3 font-mono text-text-secondary">act-runner (gitea/act_runner:latest)</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 text-text-primary">라벨</td>
+              <td className="px-4 py-3 font-mono text-text-secondary">ubuntu-latest, ubuntu-22.04</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 text-text-primary">빌드 이미지</td>
+              <td className="px-4 py-3 font-mono text-text-secondary">node:20 (Docker)</td>
+            </tr>
+            <tr>
+              <td className="px-4 py-3 text-text-primary">네트워크</td>
+              <td className="px-4 py-3 font-mono text-text-secondary">devnet (Gitea/Nexus와 동일)</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+
+      <h3 className="text-lg font-semibold text-text-primary mt-6 mb-3">관리 명령어</h3>
+      <CodeBlock
+        language="bash"
+        code={`# Runner 상태 확인
+docker ps | grep act-runner
+docker logs act-runner --tail 20
+
+# Runner 재시작
+cd /devdata/services && docker compose restart act-runner
+
+# Runner 등록 상태 확인
+# Gitea 관리자 → Site Administration → Runners
+
+# 전체 서비스 재시작
+cd /devdata/services && docker compose down && docker compose up -d`}
+      />
+
+      {/* 트러블슈팅 */}
+      <h2 className="text-xl font-bold text-text-primary mt-10 mb-4">트러블슈팅</h2>
+
+      <div className="space-y-4">
+        <div className="bg-surface border border-border-default rounded-xl p-5">
+          <h4 className="font-semibold text-text-primary mb-2">빌드가 시작되지 않음</h4>
+          <ul className="list-disc list-inside text-text-secondary space-y-1 text-sm">
+            <li>리포지토리 Settings &rarr; Actions가 활성화되어 있는지 확인</li>
+            <li>워크플로우 파일 경로 확인: <code className="bg-bg-tertiary px-1 rounded">.gitea/workflows/*.yml</code></li>
+            <li>Runner가 Online 상태인지 확인: Gitea 관리자 &rarr; Runners</li>
+            <li><code className="bg-bg-tertiary px-1 rounded">runs-on</code> 라벨이 Runner 라벨과 일치하는지 확인</li>
+          </ul>
+        </div>
+
+        <div className="bg-surface border border-border-default rounded-xl p-5">
+          <h4 className="font-semibold text-text-primary mb-2">npm ci 실패</h4>
+          <ul className="list-disc list-inside text-text-secondary space-y-1 text-sm">
+            <li>NEXUS_NPM_AUTH 시크릿이 올바르게 설정되어 있는지 확인</li>
+            <li>Nexus 서버가 접근 가능한지 확인 (act_runner가 devnet 네트워크에 있어야 함)</li>
+            <li><code className="bg-bg-tertiary px-1 rounded">package-lock.json</code>이 커밋되어 있는지 확인 (npm ci 필수)</li>
+          </ul>
+        </div>
+
+        <div className="bg-surface border border-border-default rounded-xl p-5">
+          <h4 className="font-semibold text-text-primary mb-2">배포 후 변경 사항이 안 보임</h4>
+          <ul className="list-disc list-inside text-text-secondary space-y-1 text-sm">
+            <li>브라우저 캐시 강제 새로고침: <kbd className="bg-bg-tertiary px-1.5 py-0.5 rounded text-xs">Ctrl+Shift+R</kbd></li>
+            <li>Actions 탭에서 Deploy 단계 로그 확인</li>
+            <li>서버에서 파일 확인: <code className="bg-bg-tertiary px-1 rounded">ls -la /devdata/services/guide/dist/</code></li>
+          </ul>
+        </div>
+
+        <div className="bg-surface border border-border-default rounded-xl p-5">
+          <h4 className="font-semibold text-text-primary mb-2">Runner가 Offline으로 표시됨</h4>
+          <ul className="list-disc list-inside text-text-secondary space-y-1 text-sm">
+            <li>컨테이너 상태 확인: <code className="bg-bg-tertiary px-1 rounded">docker ps | grep act-runner</code></li>
+            <li>로그 확인: <code className="bg-bg-tertiary px-1 rounded">docker logs act-runner --tail 30</code></li>
+            <li>컨테이너 재시작: <code className="bg-bg-tertiary px-1 rounded">docker compose restart act-runner</code></li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  );
+}

src/pages/GuidePage.tsx

@@ -10,6 +10,7 @@ const CONTENT_MAP: Record<string, React.LazyExoticComponent<React.ComponentType>
   'chat-bot': lazy(() => import('../content/ChatBotIntegration')),
   'starting-project': lazy(() => import('../content/StartingProject')),
   'design-system': lazy(() => import('../content/DesignSystem')),
+  'ci-cd': lazy(() => import('../content/CiCdGuide')),
 };
 
 export function GuidePage() {

src/utils/navigation.ts

@@ -9,6 +9,7 @@ export const DEV_NAV: NavItem[] = [
   { path: '/dev/chat-bot', label: 'Chat 봇 연동' },
   { path: '/dev/starting-project', label: '프로젝트 시작하기' },
   { path: '/dev/design-system', label: '디자인 시스템' },
+  { path: '/dev/ci-cd', label: 'CI/CD 자동 배포' },
 ];
 
 export const ADMIN_NAV: NavItem[] = [