GitLab Runner 도입 — SSH 배포와 apidoc 문서 자동 빌드

GitLab Runner를 도입함. 형상관리 없이 작업하던 소스들이 GitLab에 다 올라간 상태에서, 이번에 외부 서비스를 새로 하게 되면서 클라우드 서버를 새로 사고 거기에 git 설치하고 배포까지 세팅함. PHP는 Docker로 안 띄우면 사실 배포라는 게 서버에서 git pull 한 번이면 끝이라, 이걸 자동으로 해주는 것부터 시작함.

배포 방식 두 가지

전 회사에서 본 방식과 이번에 한 방식이 다름.

• 전 회사 — 배포 대상 서버에 GitLab Runner를 직접 설치. 잡이 돌면 그 서버에서 git pull 하고 끝.
• 지금 회사 — Runner는 컨테이너(docker executor)로 띄움. 잡이 컨테이너 안에서 돌기 때문에 배포 대상 서버에 직접 손이 안 닿음. 그래서 GitLab CI/CD Variables에 SSH 개인키를 넣어두고, 잡에서 그 키로 서버에 SSH 접속해서 git pull을 날리는 구조.

컨테이너 방식이 한 단계 더 번거롭긴 한데, 러너가 서버에 종속 안 되고 키 관리도 GitLab 안에서 되어서 선택.

deploy:
  stage: deploy
  image: alpine
  before_script:
    - apk add --no-cache openssh-client
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
  script:
    - ssh -o StrictHostKeyChecking=no user@$DEPLOY_HOST "cd /var/www/service && git pull"
  only:
    - main

SSH_PRIVATE_KEY, DEPLOY_HOST는 GitLab 프로젝트의 Settings > CI/CD > Variables에 넣어둠. 키가 저장소에 안 남는 게 핵심.

PHP와 API 문서

FastAPI나 Spring Boot 써보면 알겠지만 스웨거가 어노테이션이나 모델만 잘 잡으면 거의 공짜로 나옴. PHP는 방법이 없는 건 아닌데 힘듦. 찾다가 apidoc이라는 JS 도구를 발견함.

doc 주석처럼 쓰면 됨. 코드 위에 이런 식으로 달면 HTML 문서가 만들어짐.

/**
 * @api {get} /user/:id 회원 조회
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id 회원 고유 ID
 *
 * @apiSuccess {String} name 이름
 * @apiSuccess {String} email 이메일
 */

물론 API에 필드가 바뀌거나 추가될 때마다 주석을 수동으로 고쳐야 하는 건 힘듦. 스웨거처럼 코드에서 자동으로 뽑히는 게 아니니까. 그래도 엑셀로 API 명세 관리하는 것보단 백배 나음.

CI/CD에 문서 빌드 얹기

배포 파이프라인에 apidoc 빌드를 끼워 넣음. Node 이미지에서 apidoc 설치하고 빌드해서 docs/에 떨어뜨리는 식.

docs:
  stage: build
  image: node:20-alpine
  script:
    - npm install -g apidoc
    - apidoc -i src/ -o docs/

이러면 push할 때마다 문서가 최신으로 빌드됨. 주석만 제때 달면 문서는 파이프라인이 알아서 만들어줌.

정리

• PHP 배포는 결국 git pull이라 CI/CD 붙이기 제일 쉬운 케이스임. 여기서부터 시작하면 됨.
• Runner를 컨테이너로 띄우면 배포는 SSH로. 키는 GitLab CI/CD Variables에 넣어서 저장소에 안 남게.
• PHP API 문서는 apidoc이 현실적인 선택. 수동 주석이 귀찮지만 엑셀보단 낫고, 빌드는 파이프라인에 맡기면 됨.
• CI/CD 도입하니까 편함.