Jenkins와 git을 사용한 GitBook 빌드 자동화

Jekyll이나 GitBook같은 static site generator를 쓰는 장점 중 하나는 콘텐츠가 늘어나더라도 DB액세스 없이 빠르게 볼 수 있다는 것이다. 순서를 거꾸로 말하게 된 것 같지만, 그 이유는 결국 명칭에서 알 수 있듯이 콘텐츠를 만드는 데이터를 미리 “빌드"해서 사이트에 게시한 덕분이다.

그렇다면 static site generator도 결국 콘텐츠가 많아지면 빌드 시간이 증가한다. 다만 빌드 시간을 느끼는 것은 새 콘텐츠를 릴리즈하는 콘텐츠 제공자이지, 콘텐츠 소비자가 아닐 뿐.

나 같은 테크니컬 라이터는 당연히 콘텐츠 제공자로서 그 빌드 시간의 증가를 느끼는 입장이다. Jekyll같은 경우는 그나마 GitHub pages에 게시하면 자동 빌드해주므로 낫지만, GitBook은 직접 빌드해야 한다.

물론 그 시간이 견디지 못할만큼 길지는 않지만, 콘텐츠 작성 혹은 수정 → GitBook 빌드 → 사이트 게시라는 절차는 귀찮기도 하고 가끔 실수도 생기는 작업이다. 급한 와중에 이 짧은 시간이 아까워서 “이미 익숙한 내가 썼으니 빌드가 안될 리 없어!”라거나 “딱 한 줄 바꿨는데, 뭐"라는 생각으로 빌드 테스트 없이 콘텐츠를 릴리즈하는 경우가 왕왕 있다.

구구절절 말은 길었지만, 이미 이런 것들은 오래전부터 소프트웨어 개발자들이 고민해왔던 것이고 이미 해결했던 것이다. 테크니컬 라이터의 베이스가 소프트웨어 개발일 때 좋은 점은 이런 해결책들을 이미 들여다 본 경험이 있다는 점이 아닐까. 다른 포스트에서 쓰겠지만, 이미 잘 쓰고 있는 이런 해결책을 적용할 수 있다는 것도 소프트웨어 문서를 소스코드와 동일한 것으로 간주해야 하는 이유다.

소프트웨어 개발에서는 이미 CI 툴을 통해 이런 작업들을 수행하고 있다. 물론 이런 툴은 단순히 빌드 시간을 아끼겠다거나 빌드/테스트 없이 콘텐츠를 릴리즈하는 것을 막기보다 더 심오한(!) 철학을 바탕으로 하고 있지만, 여기서는 이 단순한 두 가지 이유를 위해서 널리 쓰이는 CI 툴인 Jenkins를 써 보겠다.

GitBook 빌드 자동화를 하려는 이유

• 콘텐츠 작성자의 개별 빌드 시간을 줄이기
• 콘텐츠 작성자가 빌드를 깜빡했더라도 빌드 오류를 알려주기
• GitBook을 게시할 때 각각의 사이트에 필요한 사전 작업 처리하기

세 번째 항목은 앞서 설명하지 않았는데, 주로 GitBook 결과물을 게시하기 전에 미리 해야할 작업이 있을 때를 대비한 것이다. 예를 들어 GitHub pages는 Jekyll을 지원하기 때문에 콘텐츠를 업로드하면 Jekyll 빌드를 하기 때문에 GitBook 문법이 있는 markdown 파일은 빌드 오류를 발생시킨다. GitBook으로 빌드한 결과물에는 원본 markdown 파일이 포함되어 있기 때문에 이런 경우가 자주 발생해 사전에 결과물 안에서 markdown 파일을 삭제해야 한다. 사람이 수동으로 작업하면 이런 사전 작업을 깜빡할 가능성이 높다.

자동 빌드에 필요한 것

• git 저장소: 콘텐츠 원본을 저장할 저장소, Jenkins를 지원하는 GitHub, GitLab등을 쓸 수 있다. 여기서는 GitHub를 사용한다.
• 게시 사이트: 콘텐츠를 게시할 사이트. Jenkins를 지원하거나 API, command line등으로 게시물을 배포할 수 있어야 한다. 여기서는 GitHub pages를 사용한다.
• Jenkins: 자동 빌드 툴로 사용한다.

어떤 방식으로 자동 빌드할까

Jenkins 설정

먼저 GitBook을 빌드할 환경을 갖추어야 한다. NPM으로 제공되는 GitBook 모듈을 설치하면 되는데, 이는 Jenkins의 Global Tool Configuration 설정 → NodeJS Installation에서 설정해야 한다.

1. Name: 그냥 구분할 수 있는 이름
2. Install automatically 체크
3. Add Installer에서 install from nodejs.org 선택 후 아래처럼 설정
   • Version: NodeJS 9.0.0 이상 아무거나 선택
   • Global npm packages to install: gitbook-cli 입력

이제 저장소의 콘텐츠가 변경될 때마다 작업할 Jenkins 아이템을 만들자. 프리스타일로 선택한 후 다음처럼 설정한다.

• 소스코드 탭

  1. git을 선택하고, repository URL에 콘텐츠 저장소의 clone 주소 입력
  2. credential에 저장소에 접근할 수 있는 credential을 입력

• 빌드 유발 탭

  1. Github hook trigger for GITScm polling 선택

• 빌드 환경 탭

  1. Provide Node & npm bin/ folder to PATH 체크
  2. NodeJs Installation에서 앞서 Global Tool Configuration에서 만든 NodeJS 설정을 선택

• 빌드 탭

  1. Execute shell 선택
  2. 다음 내용 입력

  gitbook install
  gitbook build . docs
  find docs -name "*.md"|xargs rm
  git commit -a -m "build a book for $GIT_COMMIT by jenkins (#$BUILD_NUMBER)"
  git push origin master
  

이렇게 하면, 아이템이 실행될 때마다 저장소의 콘텐츠를 다운로드하여 GitBook을 빌드하고, 원본 markdown 파일을 삭제한 후 저장소의 master 브랜치의 docs 디렉터리에 결과물을 업로드 한다.

빌드 후 조치 탭에서 메일 알림을 받도록 설정하면 빌드 오류가 발생했을 때 메일로 알려주므로 바로 오류를 인지하여 고칠 수도 있다.

이제 GitHub에서 Jenkins로 trigger를 보낼 수 있도록 설정한다. GitHub 내저장소의 Settings → Integrations & services에서 Jenkins 플러그인을 등록하자.

1. Integrations & services 화면 오른쪽의 Add service” 누름
2. Jenkins로 검색하여 “Jenkins (Github plugin)”을 선택
3. Jenkins hook url에 “{Jenkins주소}/github-webhook/”을 입력

Trigger가 잘 되는지 확인하려면 service 설정 화면 오른쪽의 “Test service” 버튼을 눌러보면 된다. 최종 빌드 이후로 저장소 내용이 변경되지 않았다면 Jenkins에 설정한 내용이 실행되지는 않지만, 해당 아이템의 ‘GitHub hook log’에서 trigger 수신 여부 정도는 확인할 수 있다.