8.6 KiB
Gitea Actions 변수·Secret 등록 가이드
이 문서는 현재 deploy-staging.yml이 사용하는 피드백 작성 전용 배포 설정입니다. 이 workflow는 web 컨테이너만 10.13.10.4:8864에 배포합니다. ABC API·Secretary API·MySQL을 배포하던 이전 전체 플랫폼용 변수 목록과 섞어 등록하지 않습니다.
1. 등록 위치와 구분
Gitea 저장소 b24014/egbim_qa_platform에서 다음 메뉴를 엽니다.
Repository Settings → Actions → Variables / Secrets
Gitea 버전에 따라 메뉴명이 Actions secrets and variables로 보일 수 있습니다. workflow의 표현식 기준은 다음과 같습니다.
${{ 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를 서버 관리자나 별도 신뢰 채널로 확인한 뒤 등록합니다.
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과 같은 값을 사용해야 합니다.
작성 서버 JWT_SECRET ─┐
├─ 같은 값
관리 콘솔 Support JWT 검증 ─┘
값이 다르면 로그인 callback은 끝나도 /api/support/access가 401 Unauthorized를 반환합니다. 이 secret은 새로 발급하거나 변경할 때 양쪽을 같은 변경 창에 갱신하고 기존 세션 만료를 고려합니다.
4. 현재 등록하지 않는 변수
피드백 작성 전용 docker/docker-compose.prod.yml에는 web만 있으므로 다음은 이 workflow에 등록할 필요가 없습니다.
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.4WEB_PORT=8864SUPPORT_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 값을 출력하지 않고 설정 존재 여부만 통과해야 합니다.
성공 후 스테이징 서버에서 확인합니다.
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 상태만 남깁니다.