egbim_qa_platform/GITEA_VARIABLES.md

# Gitea Actions 변수·Secret 등록 가이드

이 문서는 현재 [`deploy-staging.yml`](./.gitea/workflows/deploy-staging.yml)이 사용하는 피드백 작성 전용 배포 설정입니다. 이 workflow는 `web` 컨테이너만 `10.13.10.4:8864`에 배포합니다. ABC API·Secretary API·MySQL을 배포하던 이전 전체 플랫폼용 변수 목록과 섞어 등록하지 않습니다.

## 1. 등록 위치와 구분

Gitea 저장소 `b24014/egbim_qa_platform`에서 다음 메뉴를 엽니다.

```text
Repository Settings → Actions → Variables / Secrets
```

Gitea 버전에 따라 메뉴명이 `Actions secrets and variables`로 보일 수 있습니다. workflow의 표현식 기준은 다음과 같습니다.

```yaml
${{ vars.NAME }}       # 일반 Variables
${{ secrets.NAME }}    # 마스킹되는 Secrets
```

등록할 때 변수 이름은 대문자·underscore까지 아래 표와 똑같이 입력합니다. 값에 따옴표를 붙이지 않습니다. Secret은 채팅, 이슈, commit, workflow 로그에 기록하지 않습니다.

## 2. Variables

다음은 공개되어도 되는 주소·포트·동작 설정입니다. 표의 `기본값`은 Gitea에 생략해도 workflow가 사용하는 값입니다.

| 이름 | 필수 | 권장값/기본값 | 용도 |
| --- | --- | --- | --- |
| `STAGING_HOST` | 선택 | `10.13.10.4` | SSH 대상. 현재 workflow가 이 값만 허용 |
| `STAGING_PORT` | 선택 | `22` | SSH 포트 |
| `STAGING_APP_DIR` | 선택 | `/home/user/egbim_qa_platform` | 원격 배포 디렉터리 |
| `WEB_PORT` | 선택 | `8864` | 외부 Web 포트. 현재 workflow가 이 값만 허용 |
| `SUPPORT_CONSOLE_API_BASE_URL` | 선택 | `https://feedback.hmac.kr/api/support` | 관리 콘솔 Support API |
| `SSO_ISSUER` | 선택 | `https://sso.hmac.kr/oidc` | BARON-SSO issuer |
| `SSO_AUTHORIZATION_ENDPOINT` | 선택 | `https://sso.hmac.kr/oidc/oauth2/auth` | OAuth authorization endpoint |
| `SSO_TOKEN_ENDPOINT` | 선택 | `https://sso.hmac.kr/oidc/oauth2/token` | 서버 간 code 교환 endpoint |
| `SSO_USERINFO_ENDPOINT` | 선택 | `https://sso.hmac.kr/oidc/userinfo` | 로그인 사용자 정보 endpoint |
| `SSO_SCOPE` | 선택 | `openid profile email` | BARON-SSO scope |
| `SSO_CLIENT_ID` | 권장 | BARON-SSO 작성 서버 Client ID | 공개 식별자. Variable 등록 권장 |
| `SUPPORT_TENANT_ID` | 선택 | 빈 값 | userinfo에 `tenant_id`가 없을 때 사용할 tenant |

`STAGING_HOST`와 `WEB_PORT`는 선택으로 표시했지만 다른 값으로 바꾸면 현재 workflow의 사전 검사를 통과하지 못합니다. 스테이징 대상이나 포트를 변경하려면 workflow의 고정 검사를 코드와 함께 변경하고 BARON-SSO redirect URI도 다시 등록합니다.

### `SSO_CLIENT_ID`를 Secret에 넣은 경우

현재 workflow는 호환성을 위해 `secrets.SSO_CLIENT_ID`를 `vars.SSO_CLIENT_ID`보다 우선합니다. 새로 등록할 때는 Client ID를 Variable에만 등록합니다. 두 위치에 동시에 넣으면 어느 값이 적용되는지 혼동할 수 있습니다.

## 3. Secrets

다음 5개는 workflow가 필수로 검사합니다.

| 이름 | 필수 | 등록 내용 | 주의 |
| --- | --- | --- | --- |
| `STAGING_USER` | 필수 | 스테이징 서버 SSH 사용자 | Docker 명령 실행 권한 필요 |
| `STAGING_SSH_PRIVATE_KEY` | 필수 | 배포용 Ed25519 private key 전체 | passphrase가 없는 키를 사용해야 함 |
| `STAGING_SSH_KNOWN_HOSTS` | 필수 | 스테이징 서버의 검증된 known_hosts 한 줄 이상 | 줄바꿈 보존, 임의 값 금지 |
| `SSO_CLIENT_SECRET` | 필수 | 작성 서버 전용 BARON-SSO confidential client secret | 관리 콘솔 client secret과 분리 |
| `JWT_SECRET` | 필수 | 작성 서버와 관리 콘솔 Support API가 공유하는 HS256 secret | 두 서버 값이 반드시 같아야 함 |

### SSH key 등록

private key는 로컬 파일 내용을 그대로 복사합니다. 앞뒤 공백이나 줄바꿈을 임의로 제거하지 않습니다. passphrase가 있는 키는 현재 workflow의 `ssh-keygen -y` 검사와 비대화형 SSH에서 실패할 수 있습니다.

공개키는 스테이징 서버의 해당 사용자의 `~/.ssh/authorized_keys`에 등록합니다. private key는 Gitea Secret에만 둡니다.

`known_hosts`는 다음처럼 수집할 수 있지만, 결과 fingerprint를 서버 관리자나 별도 신뢰 채널로 확인한 뒤 등록합니다.

```bash
ssh-keyscan -p 22 10.13.10.4
```

현재 workflow는 `StrictHostKeyChecking=yes`를 사용하므로 `STAGING_SSH_KNOWN_HOSTS`가 틀리거나 누락되면 배포하지 않습니다. 이 검사를 끄거나 `accept-new`로 완화하지 않습니다.

### JWT secret 등록

작성 서버는 BARON-SSO token을 그대로 브라우저에 노출하지 않고, userinfo를 기반으로 자체 HS256 JWT를 만듭니다. 관리 콘솔의 Support API가 검증하는 secret과 같은 값을 사용해야 합니다.

```text
작성 서버 JWT_SECRET       ─┐
                            ├─ 같은 값
관리 콘솔 Support JWT 검증 ─┘
```

값이 다르면 로그인 callback은 끝나도 `/api/support/access`가 `401 Unauthorized`를 반환합니다. 이 secret은 새로 발급하거나 변경할 때 양쪽을 같은 변경 창에 갱신하고 기존 세션 만료를 고려합니다.

## 4. 현재 등록하지 않는 변수

피드백 작성 전용 `docker/docker-compose.prod.yml`에는 `web`만 있으므로 다음은 이 workflow에 등록할 필요가 없습니다.

```text
ABC_API_KEY
SECRETARY_ABC_API_KEY
MASTER_API_KEY
GITEA_API_URL
GITEA_API_TOKEN
GITHUB_API_TOKEN
JIRA_API_TOKEN
SMTP_USERNAME
SMTP_PASSWORD
NAVER_WORKS_ACCESS_TOKEN
MYSQL_* / DATABASE_URL
OPENSEARCH_*
```

이 값들은 과거 전체 플랫폼 배포 또는 관리 콘솔 서버의 책임입니다. 작성 서버에 추가하면 보안 경계와 배포 목적이 흐려집니다. 특히 API key를 `NEXT_PUBLIC_*` 변수나 Web 이미지 build arg로 만들지 않습니다.

또한 현재 workflow는 `SSO_REDIRECT_URI`를 전달하지 않습니다. callback은 요청의 `Host`와 `X-Forwarded-Proto`로 동적으로 계산됩니다. 고정 URI가 필요하면 코드·Compose·workflow를 먼저 일관되게 변경해야 합니다.

## 5. 등록 후 확인

### 등록 체크리스트

- [ ] `STAGING_HOST=10.13.10.4`
- [ ] `WEB_PORT=8864`
- [ ] `SUPPORT_CONSOLE_API_BASE_URL=https://feedback.hmac.kr/api/support`
- [ ] SSO endpoint 4개가 `https://sso.hmac.kr/oidc` 계열인지 확인
- [ ] `SSO_CLIENT_ID`는 Variable에 등록하고 Secret에는 중복 등록하지 않음
- [ ] `STAGING_USER`가 올바른 SSH 사용자임
- [ ] private key에 대응하는 public key가 원격 `authorized_keys`에 있음
- [ ] 검증된 host key가 `STAGING_SSH_KNOWN_HOSTS`에 있음
- [ ] 작성 서버 전용 `SSO_CLIENT_SECRET`이 맞음
- [ ] `JWT_SECRET`이 관리 콘솔 Support API 설정과 같음
- [ ] BARON-SSO에 실제 접속 주소의 callback URI가 등록됨

Gitea Actions에서 `Deploy feedback demo`를 수동 실행합니다. 첫 단계의 `Validate deployment settings`가 secret 값을 출력하지 않고 설정 존재 여부만 통과해야 합니다.

성공 후 스테이징 서버에서 확인합니다.

```bash
docker compose -f docker/docker-compose.prod.yml ps
curl -fsS http://127.0.0.1:8864/api/health
```

그 다음 브라우저에서 `/support/EGBIM_DEMO/new`에 로그인해 양식 조회·피드백 등록·첨부파일 등록을 확인하고, 최종 데이터가 `https://feedback.hmac.kr/`에 보이는지 검증합니다.

## 6. 자주 발생한 실패와 대응

| 증상 | 원인 후보 | 확인 |
| --- | --- | --- |
| workflow 사전 검사에서 `Missing Gitea secret` | 이름 오타, Variables/Secrets 위치 오류, 빈 값 | workflow의 `${{ vars.* }}`/`${{ secrets.* }}`와 표 대조 |
| SSH host key 오류 | known_hosts 불일치 또는 서버 재설치 | fingerprint를 확인한 뒤 Secret 갱신 |
| callback 이후 `401` | `JWT_SECRET` 불일치, userinfo tenant 누락 | 두 서버 설정과 `SUPPORT_TENANT_ID` 확인 |
| 로그인 URL 또는 API가 localhost로 감 | 공개 API base URL을 build에 주입 | `NEXT_PUBLIC_API_BASE_URL`을 빈 값으로 빌드했는지 확인 |
| 양식 조회 `404` | 잘못된 Support base URL 또는 workspace code | `/api/support` suffix와 mapping 확인 |
| 첨부파일 `413` | 파일당/전체 30MB 또는 10개 초과 | 파일 수와 용량 확인 |
| 배포 script shell syntax 오류 | 원격 login shell이 zsh 등으로 실행 | workflow의 `bash -s` 경계를 유지 |

문제 해결 중 secret을 `echo`, `set -x`, `docker compose config` 출력으로 노출하지 않습니다. 필요한 로그는 값이 아닌 변수 이름과 HTTP 상태만 남깁니다.