2026 Linux OpenClaw Gateway GitLab CI/CD vs SSH | 의사결정 매트릭스 FAQ

Linux 클라우드 호스트 한 대에 OpenClaw Gateway를 올린 뒤에는 「배포 권한이 파이프라인에만 있는가, 아니면 누구나 SSH로 바꿀 수 있는가」가 사고 범위를 가릅니다. GitLab CI/CD는 태그·머지 요청과 연동된 자동 릴리스로 감사 추적에 강하고, 순수 SSH 수동 업데이트는 초기 부담은 작지만 절차가 사람 머릿속에 남기 쉽습니다. GitHub 기반 비교는 동일 주제의 GitHub Actions 대비 글을 함께 보시고, 배포 후 프로세스·포트·로그는 상주 장애 systemd·게이트웨이 포트 FAQ와 연결해 점검하세요.

CI/CD

브랜치 규칙·수동 잡 게이트

SSH

즉시 대응·낮은 YAML 부채

공통

이미지 다이제스트·헬스체크

의사결정 매트릭스

아래는 단일 VPS, 동일 Compose 매니페스트를 전제로 한 실무 규칙입니다. 「SSH」는 배포 전용 계정으로 접속해 스크립트 또는 docker compose를 직접 실행하는 경로를 뜻합니다.

기준	GitLab CI/CD 자동 배포	순수 SSH 수동 업데이트
변경 빈도	주·일 단위 채널·플러그인 업데이트, 다중 기여자	월 단위 미세 조정, 1–2명 운영
감사·추적	파이프라인 ID, 승인 잡, 환경 보호 규칙	쉘 히스토리·메모 의존, 동시 편집 충돌
비밀·토큰	CI 변수·파일 변수, 짧은 TTL 배포 키와 궁합	서버 내 `.env`, 복사 실수·스냅샷 유출 위험
롤백	이전 파이프라인 재실행 또는 고정 다이제스트 재배포	백업 tarball·이전 태그 수동 체크아웃
러너·비용	공유 러너 큐 지연, 프로젝트 분당 한도	인적 단일 장애점, 야근 비용이 숨은 과금

실무 절충

초기에는 SSH로 검증하고, 웹훅 재시도·환경 분기가 늘면 GitLab에 동일한 배포 스크립트를 옮겨 「수동 승인 잡」만 파이프라인에 두는 하이브리드가 덜 아픕니다. 두 경로 모두 같은 헬스 URL과 롤백 명령을 README 한 곳에 고정하세요.

재현 절차 A: GitLab CI/CD 배포 잡

배포 잡은 보통 tags:로 전용 셸 러너를 묶거나, Docker executor 안에서 ssh로 VPS에 들어가 Compose를 갱신합니다. 머지 파이프라인과 릴리스 파이프라인을 분리하면 실험 브랜치가 운영 호스트를 건드리는 사고를 줄입니다.

.gitlab-ci.yml 의미 요약 (개념)

# stages: verify → deploy_prod (manual 또는 tag)
# deploy_prod:
#   rules: if $CI_COMMIT_TAG
#   script: ssh deploy@host 'cd /opt/openclaw-gateway && ./rollout.sh'
# rollout.sh 내부: compose pull 고정 다이제스트 → up -d → curl 헬스

보호된 브랜치·보호된 환경 변수·수동 승인(when: manual)을 조합하면 「누가 언제 프로덕션을 바꿨는지」가 파이프라인 로그에 남습니다. 동시에 두 경로를 열어 두지 마세요: 파이프라인이 올리는 중에 SSH로 덮어쓰면 레이스가 납니다.

파이프라인 주의

CI_JOB_TOKEN 기본 권한을 과대평가하지 마세요. 레지스트리 풀·서브모듈 접근 범위를 최소화하고, 장기 SSH 키는 러너 호스트와 개발 노트북을 분리하세요. 공유 러너만 쓸 경우 배포 단계는 큐 지연에 묶이므로 SLO를 정해 두는 것이 좋습니다.

재현 절차 B: 순수 SSH 수동 업데이트

운영자 한 명이 익숙한 순서로 이미지를 당기고 컨테이너를 재기동하는 방식입니다. 재현성은 스크립트와 체크리스트에 달려 있으며, 팀이 커지면 같은 명령을 여러 사람이 다르게 실행하기 쉽습니다.

서버에서 (개념 예시)

ssh -i ~/.ssh/deploy_ed25519 deploy@your-vps
cd /opt/openclaw-gateway
# .env 는 비밀 저장소에서만 복사
docker compose pull
docker compose up -d
curl -fsS http://127.0.0.1:${GATEWAY_PORT}/health

FAQ: 파이프라인에서 자주 밟는 함정

Q1. 머지할 때마다 배포 잡이 돌아가 버립니다.

rules:에서 브랜치·태그·변경 경로를 제한하거나, 프로덕션은 when: manual 승인 잡만 남기세요. 그렇지 않으면 실패한 중간 커밋이 운영 호스트를 흔들 수 있습니다.

Q2. 러너와 VPS 시각이 어긋나 서명·토큰이 깨집니다.

NTP 동기화와 타임존을 통일하세요. 짧은 수명 토큰을 쓰는 경우 몇 분의 시계 오차만으로도 인증 오류가 나며, 로그에는 단순 401으로만 보입니다.

Q3. SSH와 CI를 병행해도 되나요?

긴급 패치 한정으로만 허용하고, 이후 파이프라인 정의를 같은 커밋으로 맞추지 않으면 다음 자동 배포 때 설정이 되돌아갑니다. 표준 경로를 하나로 줄이는 것이 안전합니다.

한 줄 요약

변경이 잦고 책임 분산이 필요하면 GitLab CI/CD로 표준화하고, 초기 실험과 단일 관리자라면 SSH 수동이 더 빠릅니다. 어느 쪽이든 이미지 다이제스트·헬스체크·토큰 회전을 문서화하지 않으면 결과는 같습니다.